@agentsfleet/orly 0.5.0

package/dispatch/write_any.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# dispatch/write_any.sh — the cross-cutting authoring dispatch, DETERMINISTIC façade.
+#
+# Pairs with dispatch/write_any.md (the LATENT façade — prose the agent reads).
+# Fires for ANY source file, IN ADDITION to the language façade (write_zig /
+# write_ts_adhere_bun / write_sql). Runs the mechanically-checkable cross-cutting
+# subset and emits ONE verdict block.
+#
+#   dispatch/write_any.sh <file> [...]   # explicit targets (EXECUTE)
+#   dispatch/write_any.sh --staged       # staged source (CONFORM, pre-commit)
+#
+# Layering:  AGENTS.md → write_any.md (latent) → write_any.sh (this) → audits/*.sh
+# Signals:   🟢 pass · 🔴 fail (blocks) · 🤔 DECIDE (judgment; blocks the TURN, not the script) · 🟣 delegated
+# Exit:      0 = mechanical gates pass · 1 = ≥1 failed · 2 = usage error.
+#
+# Leaf modes are verified against each script's own arg-parser (lib.sh warns the
+# contracts are NON-UNIFORM): ufs.sh accepts --all + --staged (--diff retired
+# M70); logging.sh / error-codes.sh / msid-ui.sh all accept --staged.
+# The fn≤50/method≤70 sub-cap (write_any.md, file-length card) is a TODO-CHECK:
+# dispatch_length_gate enforces only the file cap; no fn/method leaf is wired yet.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+dispatch_init "ANY" '*.zig' '*.ts' '*.tsx' '*.js' '*.jsx' '*.py' '*.rs' '*.go' '*.sh' '*.sql'
+dispatch_resolve_files "$@"
+dispatch_add_shebang_files "$@"    # extensionless executables — ambiguous extension ⇒ gate fires
+dispatch_header
+
+# ── deterministic gates ────────────────────────────────────────────
+dispatch_length_gate 350                                       # FLL — file cap (fn/method 50/70 = TODO-CHECK)
+dispatch_run_helper "UFS"  "ufs.sh"          "--all"   # full-tree on purpose: the per-edit lens must not be blind to an unstaged edit
+dispatch_run_helper "LOG"  "logging.sh"      "--staged"
+dispatch_run_helper "MSID" "msid-ui.sh"      "--staged"
+
+# ── delegations (run only in the product repo — need state absent from dotfiles) ──
+# ERR's leaf hard-exits if src/agentsfleetd/errors/error_registry.zig is absent (it
+# cross-references emitted codes against the registry), unlike UFS/LOG/MSID which
+# pass gracefully on empty input. So it can't run in dotfiles — delegate it; the
+# product repo's `make harness-verify` runs error-codes.sh against the real
+# registry. The .md keeps [DETERMINISTIC → ERR]: deterministic, just not run here.
+dispatch_delegate "ERR" "make harness-verify (error-codes.sh — needs src/agentsfleetd/errors/error_registry.zig)"
+
+# ── judgment gates (no script can decide; agent states verdict in chat) ──
+dispatch_judgment "GRP" "per-iteration (diff langs change) + end-of-turn: audit the diff against docs/greptile-learnings/RULES.md — one row per applicable code (UFS/ORP/TST-NAM/PRI/EMS/…); \"it's just a label\" is not an exception"
+dispatch_judgment "NLR" "touching a file with legacy framing / dead code? clean it in the same diff (touch-it-fix-it), or state the surviving legacy + why — never retain silently"
+dispatch_judgment "NLG" "new legacy_* / V2 twin / compat shim / tracking-list while VERSION < 2.0.0? rename to the what-is-wrong form; no new legacy framing pre-2.0"
+dispatch_judgment "LDC" "patching / keeping / testing a legacy-design path? consult Indy — A (remove) / B (patch) / C (keep) — before proceeding; no unilateral call"
+
+dispatch_verdict

package/dispatch/write_auth.md

@@ -0,0 +1,36 @@
+# write_auth.md — auth-flow surface dispatch (LATENT façade, fully delegated)
+
+This is the prose the AGENT reads **before touching any auth-flow, token-minting,
+or credential-typed code**. It is **fully 🟣 delegated**: the canonical rule doc
+`AUTH.md` lives in the **product repo**, not in dotfiles, so dotfiles cannot
+mechanically prove its coverage. This façade carries only the trigger + the routing
++ the cross-cutting auth invariants that hold regardless of repo.
+
+**Signal legend:**
+
+- 🟣 delegated — the auth rules + their checks live and run in the product repo
+  (agentsfleet `docs/AUTH.md`). Dotfiles routes to them and enforces the
+  always-forbidden credential rules (below) that apply everywhere.
+
+## Trigger — read the product repo's `docs/AUTH.md` before
+
+- Editing `src/auth/**`, `ui/packages/app/lib/auth/**`, token-minting handlers,
+  or any credential-typed spec dimension.
+
+**Override:** none — auth is a security boundary.
+
+## Always-forbidden (these hold in dotfiles too, per AGENTS.md Hard Safety)
+
+- **Plaintext secrets in entity tables** — store a vault `key_name` ref, resolve
+  via `crypto_store.load()` at runtime.
+- **Resolving/printing credentials** — never `op read 'op://...'` into logs or
+  output at runtime; never paste a resolved secret.
+- **Static credential strings in SQL schema** — no `DEFAULT 'value'` /
+  `CHECK (col IN (...))`; enforce in app via named constants.
+
+## What it routes to
+
+`docs/AUTH.md` **in the product repo** — token lifecycle, session shape, the
+auth middleware chain, and credential storage rules. Read it first for any
+auth-flow change; this façade exists so the dispatch table has a home for the
+trigger even though the rule body ships with the product, not dotfiles.

package/dispatch/write_changelog.md

@@ -0,0 +1,64 @@
+# write_changelog.md — changelog-voice dispatch (LATENT façade)
+
+This is the prose the AGENT reads after `write_documentation.md` and
+`docs/DOCUMENTATION_RULES.md`, **before writing any `<Update>` entry in the
+changelog** (`~/Projects/docs/changelog.mdx`). Like `verify` and
+`name_architecture`, it has **no deterministic `.sh` half** — voice is a judgment
+call no script can grade. It is a pure **🤔 judgment** dispatch: the agent reads
+this, drafts the entry, and self-audits against the rules below. The deep
+reference is `docs/CHANGELOG_VOICE.md` (Mintlify-style) — read it before writing.
+
+**Signal legend:**
+
+- 🤔 DECIDE — judgment-only; the agent writes to the voice below and self-audits.
+  No script gates it — it blocks the *turn* (the changelog entry), not a commit.
+- 🟣 delegated — the changelog itself lives in `~/Projects/docs` (its own repo +
+  own-branch flow per AGENTS.md Operational defaults); dotfiles carries only the
+  voice discipline.
+
+## Trigger — read `docs/DOCUMENTATION_RULES.md`, then `docs/CHANGELOG_VOICE.md`
+
+Fires before adding or editing an `<Update>` block in `changelog.mdx`, or any
+user-visible release note. Internal-only changes get **no** changelog entry — the
+Changelog Claim Challenge applies: *"Would this be true if the test file
+vanished?"* Only test evidence (not a middleware/handler/CLI path) ≠ an earned
+user-visible claim.
+
+**Override:** none needed — judgment-only. A voice exception (e.g. quoting a
+vendor's marketing term verbatim) is stated inline in the entry, never dressed as
+a gate skip.
+
+## The voice (summary — `docs/CHANGELOG_VOICE.md` is canonical)
+
+- **One headline per entry.** The lead paragraph states *the change*, not the
+  announcement ("X now does Y", not "We're excited to announce Y").
+- **No marketing words** — use the canonical banned-word lists in
+  `docs/CHANGELOG_VOICE.md` and `docs/DOCUMENTATION_RULES.md`; do not duplicate
+  either list here.
+- **Bullets** follow `**Bold lead-noun** — consequence-first clause`.
+- **Never drop load-bearing facts** — error codes, endpoints, env vars, schema
+  names, money amounts stay verbatim.
+- **Internal cleanup** gets aggressive trimming, not a paragraph.
+- **History is archived, not rewritten** — past entries are an immutable record.
+- **Rate constants** stay pinned across the three files (`tenant_billing.zig`,
+  `rates.ts`, `rates.mdx`) — a changelog money/rate claim must match all three.
+
+## Required output (self-audit line before committing the changelog)
+
+```
+📝 CHANGELOG: <N> bullet(s) · no marketing words · load-bearing facts kept · history append-only
+```
+
+If the change is internal-only, emit instead:
+
+```
+📝 CHANGELOG: skipped — internal-only (no user-visible behaviour change)
+```
+
+## Family
+
+- `docs/CHANGELOG_VOICE.md` — the canonical Mintlify-style voice rules (deep reference).
+- `skills/release-template.md` — release template + version-bump matrix; re-source
+  each release, never paraphrase.
+- `verify` — runs before CHORE(close); a changelog claim must be backed by the
+  verification that dispatch reports.

package/dispatch/write_documentation.md

@@ -0,0 +1,45 @@
+# write_documentation.md — published-documentation dispatch
+
+Read `docs/DOCUMENTATION_RULES.md` before
+writing customer-facing documentation. This general rule runs before narrower
+guides selected by domain-specific packs (changelog voice, when selected) and
+before prose about the dispatch model.
+
+## Trigger
+
+- Editing a published Markdown JSX (MDX) page.
+- Editing a reusable `snippets/*.mdx` fragment.
+- Editing public OpenAPI summaries, descriptions, examples, options, or errors.
+- Editing a customer-facing readme or reference page.
+<!-- oracle-packs:start domain.changelog -->
+- Editing `docs/CHANGELOG_VOICE.md` or `docs/DISPATCH_ARCHITECTURE.md`.
+
+`changelog.mdx` history remains excluded from the general page shape. New
+changelog entries read this dispatch first, then `write_changelog.md`.
+<!-- oracle-packs:end -->
+
+## Required order
+
+1. Read `docs/DOCUMENTATION_RULES.md` and identify the page scope.
+2. Read the repository glossary and content boundaries.
+3. Verify claims against runtime code, OpenAPI, and command help.
+4. Write the smallest complete page.
+5. Run the repository-owned pre-commit checker.
+
+## Enforcement
+
+🟣 **Delegated.** Each repository owns its checker: rules resolve from this
+repository's own `docs/`, materialised here by `orly init`. Dotfiles owns the
+rule and the read trigger. Repository hooks own mechanical enforcement.
+
+Before committing, cite the applied Documentation (DOC) rule identifiers:
+
+```text
+📖 DOC READ: docs/DOCUMENTATION_RULES.md — scope <page|fragment|OpenAPI|changelog>; DOC-<rules applied>
+```
+
+## Family
+
+- `docs/DOCUMENTATION_RULES.md` — general customer-documentation rules.
+- Selected changelog and HTTP packs provide their narrower archive, voice, and
+  API design rules.

package/dispatch/write_go.md

@@ -0,0 +1,24 @@
+# Go authoring
+
+Return errors, do not panic across a package boundary. Wrap with `%w` so the
+caller can still match the cause, and add context the caller does not already
+have — never re-wrap the same fact twice.
+
+Every goroutine needs a stated exit: a `context.Context` it honours, a channel
+close, or a `WaitGroup` the caller waits on. A goroutine with no exit path is a
+leak whatever the test says. Take a `context.Context` as the first parameter on
+anything that blocks, and pass it down rather than storing it in a struct.
+
+Defer the release beside the acquire — `defer file.Close()`, `defer mu.Unlock()`
+— so the pairing survives an early return. Check the error from a deferred
+`Close` on a writer; a dropped flush is a silent truncation.
+
+Accept interfaces, return structs, and define the interface where it is
+consumed. Keep zero values usable so a caller need not call a constructor to get
+a working value.
+
+Table-driven tests are the default shape. Concurrency work needs a `-race` run,
+and a deterministic contention test rather than a sleep.
+
+The repository owns formatting, vet, lint, build, and test commands — it
+declares them in `.oracle/orly.json`.

package/dispatch/write_http.md

@@ -0,0 +1,45 @@
+# write_http.md — HTTP/REST surface dispatch (LATENT façade, route-and-delegate)
+
+This is the prose the AGENT reads **before adding, modifying, or removing any HTTP
+endpoint**. Unlike `write_zig`, it does **not** merge its rule doc — the canonical
+checklist `docs/REST_API_DESIGN_GUIDELINES.md` is a
+self-contained product-surface design guide, so this façade *routes* to it rather
+than duplicating it. **Residence vs enforcement:** `orly init` materialises the
+guide into this repository under the `domain.http` pack — it is a real local
+file, not something read through another checkout. Its checks are *enforced*
+in the product repo (`make lint` / `/review` against the guide) — hence
+**🟣 delegated**.
+
+**Signal legend:**
+
+- 🟣 delegated — the REST checklist is enforced in the product repo (agentsfleet),
+  by `make lint` + adversarial `/review` against the guide. Dotfiles carries the
+  doc itself, the routing, and the discipline that the guide is a *checklist, not
+  background reading*.
+
+## Trigger — read `docs/REST_API_DESIGN_GUIDELINES.md` before
+
+- Editing `src/http/handlers/**`, `public/openapi/**`, or any `route_*` file.
+- Adding, modifying, or removing an HTTP endpoint or its OpenAPI shape.
+
+**Override:** none from dotfiles — the REST guide's own `MUST`/`SHOULD`
+semantics govern (a `MUST` violation blocks merge; a `SHOULD` deviation needs a
+one-line PR rationale).
+
+## What it routes to
+
+`docs/REST_API_DESIGN_GUIDELINES.md` — canonical instruction
+set covering URL design (plural-noun resources, no verbs, allowed `:verb`
+categories), path params + trailing-slash rules, HTTP-method semantics + PATCH
+idempotency, the `202 + /v1/operations/{id}` long-running shape, request/response
+body shapes, error envelopes, pagination, and the pre-PR §10 gate. Treat it as a
+checklist run at `CHORE(close)` before `gh pr create`.
+
+## Why route, not merge
+
+REST design rules bind the *product repo's* HTTP surface, but the doc has one
+canonical source in dotfiles — `orly init`/`orly update` materialise it here,
+so this repository's copy tracks that source. Merging its full text into
+this façade would create a second source of truth. The guide stays canonical;
+this façade is the dispatch entry that points the agent at it when the trigger
+fires.

package/dispatch/write_mdx.md

@@ -0,0 +1,7 @@
+# Markdown JSX authoring
+
+Treat Markdown JSX (MDX) as a language, not generic prose. Validate front matter,
+component nesting, links, code fences, and accessible image descriptions.
+
+Mintlify behavior belongs to the Mintlify domain pack. An MDX repository that
+does not use Mintlify must not receive Mintlify-specific rules.

package/dispatch/write_python.md

@@ -0,0 +1,8 @@
+# Python authoring
+
+Use standard-library parsers for structured input. Keep resource ownership in
+context managers. Validate data at parse boundaries and preserve specific
+exception classes until the caller can decide how to respond.
+
+The repository owns formatting, linting, type checking, and tests — it declares
+them in `.oracle/orly.json`.

package/dispatch/write_rust.md

@@ -0,0 +1,38 @@
+# Rust authoring
+
+Use ownership and borrowing to make resource lifetime visible. Keep `unsafe`
+blocks small and state the invariant they rely on. Preserve error variants until
+the caller has enough information to decide whether to retry or stop.
+
+Test the feature combinations the repository actually builds. Concurrency work
+needs a deterministic contention test, not only a happy-path asynchronous test.
+
+The repository owns formatting, Clippy, build, test, security, and benchmark
+commands — it declares them in `.oracle/orly.json`.
+
+## Reference guideline (mandatory in review)
+
+Microsoft's Pragmatic Rust Guidelines are this pack's depth — thorough,
+agent-facing, and continuously maintained upstream. The local copy lives at
+`~/Projects/oss/rust-guidelines/all.txt`; fetch it when absent:
+
+```bash
+mkdir -p ~/Projects/oss/rust-guidelines && \
+  curl -fsSL https://microsoft.github.io/rust-guidelines/agents/all.txt \
+  -o ~/Projects/oss/rust-guidelines/all.txt
+```
+
+Every Rust REVIEW — and any adversarial pass over `*.rs` — reads it
+**sectioned, never whole-file** (186 sections):
+`grep -nE "^#+ " ~/Projects/oss/rust-guidelines/all.txt`, read the sections
+the diff touches, and cite the guideline IDs (`M-…` mnemonics, e.g.
+`M-UNSOUND`, `M-SIMPLE-ABSTRACTIONS`) applied or consciously diverged from.
+Local convention wins on conflict, but the divergence is named in the review
+output. Refresh the copy when the user asks or a cited rule looks stale
+(re-run the fetch; upstream updates continuously).
+
+## Evolution
+
+This pack is young next to the Zig façade and grows the same way: a Rust
+incident worth keeping becomes a rule or **Example:** line via the
+rule-extension protocol — never a memory file, never a milestone cite.

package/dispatch/write_shell.md

@@ -0,0 +1,8 @@
+# Shell authoring
+
+Quote expansions, use arrays for argument lists, and clean temporary files on
+every exit path. Avoid `eval` for external input. Match the repository's required
+shell and macOS Bash compatibility level.
+
+The repository owns ShellCheck and executable tests — it declares them in
+`.oracle/orly.json`.

package/dispatch/write_spec.md

@@ -0,0 +1,105 @@
+# write_spec.md — spec-authoring dispatch (LATENT façade)
+
+This is the prose the AGENT reads **before writing or editing a spec** under
+`docs/v*/{pending,active,done}/`. It pairs with the deterministic half
+`audits/spec-template.sh`, which runs in `make lint`. (This is the former Spec Template gate absorbed into
+the dispatch model — `docs/TEMPLATE.md` remains the canonical section source.)
+
+**Signal legend:**
+
+- 🟢 / 🔴 — `audits/spec-template.sh` mechanically passes/fails the prohibited-pattern and
+  required-section checks.
+- 🤔 DECIDE — whether a required section is *meaningfully filled* (not just
+  present) is the agent's judgment at author time.
+
+## Trigger — every Edit/Write to
+
+- Any spec under `docs/v*/{pending,active,done}/**/*.md`.
+- `docs/TEMPLATE.md` itself.
+- Any `*.md` whose body carries the spec frontmatter pattern (`^**Milestone:** M\d+`).
+
+**Override:** `SPEC TEMPLATE GATE: SKIPPED per user override (reason: ...)`.
+**User-invokable only.** Auto-mode does NOT cover it; reasons must cite a concrete
+external constraint (vendor doc requirement, regulatory format), never internal
+preference.
+
+## What this covers
+
+**Family 1 — prohibited patterns (negative space).** `docs/TEMPLATE.md`
+"Prohibited" forbids: time/effort estimates, effort columns, complexity ratings,
+percentage-complete fields, assigned owners, implementation dates. Specs created
+from the template don't carry the Prohibited section forward — only the body
+below the divider gets copied — so without enforcement these drift back in.
+
+**Family 2 — required-present + no-placeholder (positive space).** The
+agent-facing template mandates the determinism sections the executing agent reads
+to emit invariant output: PR Intent & comprehension handshake, Applicable Rules,
+Applicable Gates, Overview, Prior-Art / Reference Implementations, Files Changed,
+Decomposition & alternatives, Sections, Metrics & Observability, Interfaces,
+Failure Modes, Invariants, Test Specification, Acceptance Rubric (legacy heading `Acceptance Criteria` accepted), Product Clarity (authoring record), Discovery. A spec missing one — or
+leaving template residue (`path/to/file.ext`, `test_<short_name>`,
+`{one-line reason}`, any surviving `tpl:` guidance comment — the template's fill
+grammar deletes them all at authoring) — forces the agent to guess intent.
+
+**Family 2b — declared-command parity.** A staged `pending/` or `active/`
+spec's Acceptance Rubric must quote the repository's declared `conform` and
+`verify.unit` commands (`.oracle/orly.json`) **verbatim** — the same set
+`orly gate` runs, so the rubric and the mechanical PR gate grade one boundary.
+Missing → BLOCK. No config, no bun, or no declared commands → NOTE + skip.
+Done specs are historical records and are never retrofitted.
+
+**Scope (no legacy carve-out).** Family 2 fires in `--staged` only — the spec
+being authored now (the agent's own output): BLOCK. Bulk scans (`--all` /
+`--include-done`, which `make harness-verify` runs) execute Family 1 only, so they
+behave identically over the corpus and never break an existing spec.
+
+## Pre-edit check
+
+| Pattern | Rule |
+|---|---|
+| `## Estimated effort` (any heading variant) | Forbidden. Delete the section. |
+| `## Effort` / `## Complexity` / `## Sizing` | Forbidden. Use Priority. |
+| `\b\d+\s*[-–]\s*\d+\s*h\b` (hour ranges like "10-14h") | Forbidden. |
+| `\b\d+\s*hours?\b` / `\b\d+\s*days?\b` / `\b\d+\s*min(utes?)?\b` | Forbidden. |
+| `\b(low|medium|high|small|large)\s*[:|-]\s*(effort|complexity)\b` | Forbidden. |
+| `\d+%\s*complete` / `\b\d+/\d+\b\s*tasks` | Forbidden — binary PENDING/IN_PROGRESS/DONE. |
+| `**Owner:**` / `**Assigned to:**` | Forbidden — use git history. |
+| `**Due:**` / `**Deadline:**` (with date) | Forbidden — use Priority. |
+| Missing a required determinism section in a **staged** spec | BLOCK — add it. |
+| Rubric missing a declared `conform`/`verify.unit` command (**staged** pending/active) | BLOCK — copy it verbatim from `.oracle/orly.json`. |
+| Unfilled template residue in a **staged** spec | BLOCK — fill the section. |
+| Surviving `tpl:` guidance comment in a **staged** spec | BLOCK — delete it; the executor reads instance content only. |
+| Spec without the SPEC AUTHORING RULES banner | Informational — reminds future edits. |
+
+## Required output (default — one line)
+
+```
+SPEC TEMPLATE GATE: <file> | prohibited:<0|list> required-sections:<all-present|missing-list — staged only> placeholders:<0|list> banner:<yes|no>
+```
+
+Full multi-line block fires on violation (prohibited sections / time estimates /
+effort fields / %-complete / owner-date fields, each with line numbers, plus the
+`audits/spec-template.sh` staged-diff finding count).
+
+## Scope
+
+`audits/spec-template.sh` walks the **full pending+active spec set** via `git ls-files`;
+the index includes staged-but-uncommitted content, so a fix staged in pre-commit
+satisfies the check on the same hook run. `--staged` is the opt-in narrowing mode.
+
+## Authoring discipline (judgment layer)
+
+Incident-derived rules the deterministic half can't check — apply while writing the spec, not after:
+
+- **Validate intent against the repo, not the words.** Grep the codebase for the existing meaning of the spec's key nouns ("e2e", "acceptance", "live") before encoding them. The **duplicate-target smell**: a new target/recipe that comes out byte-identical to an existing one means the abstraction is wrong — STOP and surface (one incident's new e2e umbrella came out byte-identical to the existing integration target). And verify lanes in the real CI environment — a green local `docker compose` run proves nothing about a compose-less CI container.
+- **Teardown / rename / flip specs open with a blast-radius grep.** `git grep -rn -w '<token>'` from repo root, no path or file-type filter; every surviving hit lands in Files Changed with production and test files separated. Word-boundary, never quoted-literal (YAML / multiline-string refs carry no quotes); grep filenames as tokens, never path-anchored (same-directory `@import("foo.zig")` has no path prefix); separate true targets from same-spelling-different-meaning hits (skill ref vs repo slug). The spec's invariant/rubric greps must use the same pattern as the discovery grep.
+- **Grep-gate carve-outs for English.** A `\b(word)\b` zero-match gate overreaches when the word has a common English meaning ("run" is the usual offender). Encode the intent as enumerated product phrases (`run interrupt`, `spec init`, `gate loop`); when a literal gate fires on legitimate English, amend the spec — don't contort the prose.
+- **No pre-/post-milestone or "production today" framing while pre-launch** — there is no production baseline to anchor a current-vs-future split against. Describe the target design as *the* design; mark a superseded model neutrally ("this file describes the single-process model; the M80 split supersedes it"), never as "pre-M80 / operational truth".
+- **Security-boundary or backend-heavy follow-ups get their own spec + PR.** RBAC, secret reveal, account/tenant deletion, auth webhooks, new endpoints/scheduled jobs/billing policy — they carry a different review profile (AUTH chain, focused diff, own greptile pass) and never fold into a UI-polish PR, even after a "just fold it in". Small pure-UI items bundle fine; restoring a folded spec to `pending/` is cheap.
+- **Rubric rows are outcomes, not Dimensions.** The Acceptance Rubric is the spec's single scoring surface: 5–12 rows (Section outcomes, failure classes, hygiene gates); every Expected mechanically checkable (exit code / literal substring / match count); Graded = ✅/❌ + one decisive output line. Per-Dimension proof lives in the Test Specification; evidence walls and per-Dimension rubric rows are violations.
+
+## Family
+
+- `docs/TEMPLATE.md` — canonical Prohibited section + required sections.
+- `orly-spec-new` skill — creates specs from the template; inserts the banner.
+- `audits/spec-template.sh` — mechanical regex enforcement, runs in `make lint`.

package/dispatch/write_sql.md

@@ -0,0 +1,112 @@
+# write_sql.md — SQL / schema latent façade
+
+This is the prose the AGENT reads before writing any `schema/*.sql` file. It pairs with the deterministic façade `dispatch/write_sql.sh` — the machine half that runs the mechanically-checkable subset and emits one verdict block. **Read `docs/SCHEMA_CONVENTIONS.md` first** — it is the source-of-truth for table/column naming, type choices, and schema-qualification (the analogue of `docs/REST_API_DESIGN_GUIDELINES.md` for `write_http`). The dissolving **Schema Table Removal Guard** card is merged verbatim below, while the durable SQL rules (`NSQ`, `STS`, `SGR`, `ITF`) stay in `docs/greptile-learnings/RULES.md` (retained) — referenced here, enforced by the GREPTILE GATE. Mechanical thresholds live once in the `.sh`; this file references rule codes, never restates the numbers.
+
+**Signal legend** (printed by `write_sql.sh`):
+
+- 🟢 pass — deterministic check passed.
+- 🔴 fail — deterministic check failed (or helper absent); STOP, fix, rerun.
+- 🤔 DECIDE — judgment-only; no script can decide, the agent reads the section and makes the call (blocks the TURN, not the script).
+- 🟣 delegated — the checker runs only in the product repo, not in dotfiles.
+
+**Tag legend** — each section heading below carries one of:
+
+- `> [DETERMINISTIC → <CODE>]` — a machine can pass/fail it; the `.sh` row for `<CODE>` (e.g. `FLL`) enforces it. `TODO-CHECK` marks a mechanizable rule with no helper wired yet (build-the-check). `NEW:<name>` marks a proposed-but-not-yet-existing code.
+- `> [JUDGMENT → <CODE>]` — no script can decide; the agent decides at write time against the prose.
+- `> [container]` — a non-enforcement wrapper heading (e.g. "Merged from dissolved gate cards"); its tagged subsections carry the real codes, and the coherence audit (§6.3) skips it.
+
+The tag grammar and semantic-anchor model are defined by the tagged sections and
+deterministic façade in this snapshot.
+
+---
+
+# SQL & schema authoring discipline
+
+## Scope
+
+> [JUDGMENT → SCH]
+
+Triggers on every `Edit`/`Write` to `schema/*.sql`, `schema/embed.zig` (`@embedFile` constants), and the canonical migration array in `src/cmd/common.zig`. **Before authoring DDL, read `docs/SCHEMA_CONVENTIONS.md`** (naming, types, schema-qualification). SQL embedded in handlers (`*.zig`) and integration-test fixtures is also governed by the companion rules below — those surfaces additionally fire `write_zig.md` and the GREPTILE GATE.
+
+## Merged from dissolved gate cards
+
+> [container]
+
+The **Schema Table Removal Guard** card dissolves into this façade; its prose is preserved verbatim below (title demoted to a tagged `###`, its subsections demoted to `####` and tagged `SCH`).
+
+### Schema Table Removal Guard (SCHEMA GUARD)
+
+> [JUDGMENT → SCH]
+
+**Family:** Schema discipline. **Source:** `AGENTS.md` (project-side guard). Related: **RULE STS** (no static strings in SQL schema), **RULE NSQ** (named constants, schema-qualified SQL) — both in `docs/greptile-learnings/RULES.md`.
+
+**Triggers** — before any of these, run `cat VERSION` and print the guard output:
+
+- Creating, editing, or deleting any file under `schema/*.sql`.
+- Editing `schema/embed.zig` (any `@embedFile` constant).
+- Editing the canonical migration array in `src/cmd/common.zig`.
+- Writing `DROP TABLE`, `ALTER TABLE`, or `SELECT 1;` into any SQL file.
+- Accepting a spec dimension prescribing a "DROP migration", "ALTER migration", or "version marker".
+
+**Override:** `SCHEMA GUARD: SKIPPED per user override (reason: ...)`. **User-invokable only.** Spec violates the guard → amend the spec first.
+
+#### Pre-v2.0.0 (teardown-rebuild era)
+
+> [JUDGMENT → SCH]
+
+To remove a table:
+
+1. `rm schema/NNN_foo.sql`
+2. Remove `@embedFile` from `schema/embed.zig`
+3. Remove the entry from the migration array in `src/cmd/common.zig` and update length + index-based tests.
+
+**Forbidden:** `ALTER TABLE`, `DROP TABLE`, `SELECT 1;` markers, comment-only files, "keep file for slot numbering". Slot gaps are fine — the DB is wiped on rebuild.
+
+#### v2.0.0+
+
+> [JUDGMENT → SCH]
+
+Proper `ALTER`/`DROP` migrations in new numbered files. No teardown.
+
+#### Required output
+
+> [JUDGMENT → SCH]
+
+```
+SCHEMA GUARD: VERSION=<v> (<2.0.0 ? teardown : alter)
+  rm:schema/<file>.sql
+  rm-embed:<const>
+  rm-migration:v<N>
+```
+
+For pre-v2.0.0 path, all three rm- lines appear. For v2.0.0+, replace with `migration:schema/<NNN>_<change>.sql`.
+
+## Companion SQL rules (retained in `docs/greptile-learnings/RULES.md`)
+
+> [container]
+
+These rules are **not** dissolved — they remain in `docs/greptile-learnings/RULES.md`. STS/NSQ/SGR are enforced by the GREPTILE GATE until a leaf check is wired (`TODO-CHECK`); ITF additionally surfaces as a `🤔 DECIDE` judgment row in `write_sql.sh`. Summarised here so the SQL author sees the full surface in one place; RULES.md stays canonical (read it for the full text + `Ref:` provenance).
+
+### RULE STS — No static strings in SQL schema
+
+> [DETERMINISTIC → TODO-CHECK]
+
+No string literal in `schema/**.sql` may name a value or identifier the application also names — SQL cannot reference Zig/JS constants, so schema strings drift from code. The surface is every literal, not two syntactic forms: `DEFAULT`, `CHECK (… IN (…))`, **trigger-body comparisons against a column**, **`current_setting()` parameter names**, and **`RAISE EXCEPTION` text a caller matches on**. Enforce value constraints via application constants; where SQL cannot import the constant, pin the pair with a slot-grep test. Carve-out: a literal encoding a structural identity rather than a vocabulary value (`'{}'::jsonb`, `'{}'::text[]`) stays, reason stated inline. A drifted `DEFAULT` yields wrong data; a drifted trigger predicate or setting name fails **silently** — the guard stops guarding. (RULES.md `RULE STS`.)
+
+### RULE NSQ — Named constants, schema-qualified SQL
+
+> [DETERMINISTIC → TODO-CHECK]
+
+No magic numbers; all SQL in handlers is schema-qualified (`core.table`, not `table`) — unqualified names fail when `search_path` differs across environments. (RULES.md `RULE NSQ`.)
+
+### RULE SGR — Migrations include GRANT statements
+
+> [DETERMINISTIC → TODO-CHECK]
+
+Every `CREATE TABLE` migration ends with `GRANT`s for every role that queries the table (`api_runtime` / `worker_runtime`), mirroring the table's callers. PostgreSQL denies by default — a missing grant fails only at first runtime use. (RULES.md `RULE SGR`.)
+
+### RULE ITF — Integration tests use the real schema
+
+> [JUDGMENT → ITF]
+
+An integration test touching a production table seeds rows through a shared `src/db/test_fixtures_<scope>.zig` module against the real schema — never a session-local `CREATE TEMP TABLE` mocking the production shape (the mock drifts and hides schema changes). Fixtures use semantic scope names, never milestone-numbered ones. (RULES.md `RULE ITF`.)

package/dispatch/write_sql.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# dispatch/write_sql.sh — the SQL / schema dispatch, DETERMINISTIC façade.
+#
+# Pairs with dispatch/write_sql.md (the LATENT façade — prose the agent reads).
+# This .sh runs the mechanically-checkable subset of the SQL/schema discipline and
+# emits ONE verdict block. The latent trigger ("about to write a schema/*.sql file")
+# dispatches here; everything below is deterministic and re-runnable.
+#
+#   dispatch/write_sql.sh <schema/file.sql> [...]   # explicit targets (EXECUTE)
+#   dispatch/write_sql.sh --staged                  # staged schema/*.sql (CONFORM, pre-commit)
+#
+# Layering:  AGENTS.md → write_sql.md (latent) → write_sql.sh (this) → audits/*.sh
+# Signals:   🟢 pass · 🔴 fail (blocks) · 🤔 DECIDE (judgment; blocks the TURN, not the script) · 🟣 delegated
+# Exit:      0 = mechanical gates pass · 1 = ≥1 failed · 2 = usage error.
+#
+# Note: STS/NSQ/SGR are mechanizable SQL-hygiene rules with no leaf check wired yet
+# (write_sql.md tags them TODO-CHECK). They stay in docs/greptile-learnings/RULES.md
+# (retained) and the GREPTILE GATE enforces them by review until a leaf exists.
+# SCH's pre-2.0 forbidden-token floor (no ALTER/DROP/SELECT 1; in schema/*.sql) is
+# itself a build-the-check (TODO-CHECK) candidate; the teardown-vs-ALTER disposition
+# call above it stays JUDGMENT (which file to rm, which @embedFile, which migration index).
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+dispatch_init "SQL" 'schema/*.sql'
+dispatch_resolve_files "$@"
+dispatch_header
+
+# ── deterministic gates ────────────────────────────────────────────
+dispatch_length_gate 350                                       # FLL — file ≤ 350
+
+# ── judgment gates (no script can decide; agent states verdict in chat) ──
+dispatch_judgment "SCH" "removing/altering a table? cat VERSION — pre-2.0.0 = full teardown (rm schema/NNN.sql + @embedFile + migration-array entry + index tests), never ALTER/DROP/SELECT 1; ≥2.0.0 = numbered ALTER/DROP migration. print the SCHEMA GUARD block"
+dispatch_judgment "ITF" "integration test touching a production table? seed via src/db/test_fixtures_<scope>.zig against the real schema — never CREATE TEMP TABLE mocking the production shape"
+
+dispatch_verdict