@agentsfleet/orly 0.10.14 → 0.12.0

package/docs/SCHEMA_CONVENTIONS.md

@@ -1,12 +1,30 @@
 # Schema Conventions
 
-Canonical reference for agentsfleet database schema patterns. All new tables **must** follow these conventions. Existing tables are brought into compliance when rebuilt.
+## Repository policy
+
+Read the repository's schema sources, migration registration and deployment
+policy before changing its database. Preserve shipped migrations and live data;
+destructive changes need the owner's approval for the specific change.
+Never infer a disposable database from a version threshold in another product.
+
+Use the repository's naming, identity and timestamp conventions consistently.
+Qualify table names, grant only the operations each runtime role needs, and test
+with the real schema through shared fixture helpers.
+Keep migration registration and position assertions synchronized with each edit.
+
+<!-- oracle-packs:start product.agentsfleet -->
+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 < 0.30.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).
+**Additive migrations resume at `VERSION >= 0.30.0`, as RULE SCH specifies.**
+Completing the rebuild alone does not change the version boundary.
+Every subsequent schema change is a new numbered migration file; shipped slots
+are frozen history. Migrations are tracked incrementally through
+`agentsfleetd doctor --schema-gate`; use `IF NOT EXISTS` where appropriate for
+fresh bootstrap and an already provisioned database.
 
 Destructive changes (`DROP TABLE`, `DROP COLUMN`, type rewrites) require an explicit owner decision per change — additive is the default an agent may author alone.
 
@@ -17,7 +35,9 @@ Destructive changes (`DROP TABLE`, `DROP COLUMN`, type rewrites) require an expl
 - 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 `rustd/crates/afd_db/src/migration.rs` (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.
+- Below `0.30.0`, remove obsolete slots and their registrations completely;
+  no-op markers are forbidden. At and above `0.30.0`, preserve shipped slots and
+  apply changes through new migrations.
 
 ## SQL Qualification
 
@@ -91,3 +111,4 @@ Every table must have:
 
 - **Always** use `std.crypto.random` (via `allocUuidV7` in `id_format.zig`).
 - **Never** use custom RNG implementations or `std.rand`.
+<!-- oracle-packs:end -->

package/docs/TEMPLATE.md

@@ -353,14 +353,14 @@ table. -->
 |---|--------------------------------|---------------------|----------|----------|-----------------|
 | R1 | {{fill:outcome the user can observe}} (§1) | `{{fill:command}}` | {{fill: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 | `{{fill:conform command from .oracle/orly.json, verbatim}}` | exit 0 | P0 | |
-| S2 | Unit tests pass | `{{fill:verify.unit command from .oracle/orly.json, verbatim}}` | exit 0 | P0 | |
+| S1 | Conform gates green | `{{fill:conform command from .orly/orly.json, verbatim}}` | exit 0 | P0 | |
+| S2 | Unit tests pass | `{{fill:verify.unit command from .orly/orly.json, verbatim}}` | exit 0 | P0 | |
 | S3 | Slow tier green (code-carrying branch) | `{{fill:one row per remaining declared verify.* command, 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:** copy every declared `conform` and `verify.*` invocation from `.oracle/orly.json` into a Verify cell, verbatim, with an Expected value. Include conditional suites; the final gate decides applicability from the actual branch diff. Additional spec-specific commands, secret scans, and named manual checks are allowed. Missing configuration must be completed before authoring. See `dispatch/lifecycle.md` for command timing; baseline metadata is pending at opening and measured before the Pull Request.
+**Command source rule:** copy every declared `conform` and `verify.*` invocation from `.orly/orly.json` into a Verify cell, verbatim, with an Expected value. Include conditional suites; the final gate decides applicability from the actual branch diff. Additional spec-specific commands, secret scans, and named manual checks are allowed. Missing configuration must be completed before authoring. See `dispatch/lifecycle.md` for command timing; baseline metadata is pending at opening and measured before the Pull Request.
 
 **Grading protocol (VERIFY):** run each spec-specific Verify command verbatim; Graded = ✅/❌ + one decisive output line. Repository-command rows point to the final `orly gate pr` results in Pull Request Session Notes, so recording those results does not require another code commit and suite run. **Ship gate:** every required check must pass before the Pull Request is ready; missing evidence or any ❌ returns to EXECUTE. A P1 ❌ requires an Indy-acked deferral quote in Discovery. A P0 may also be **MOVED** — see below.
 
@@ -378,7 +378,7 @@ A MOVED row is never rendered ✅. The criterion has not been met; it has change
 
 <!-- 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). Repository suite commands come verbatim from `.oracle/orly.json`; expand S3
+per Dimension (that ledger is the Test Specification). Repository suite commands come verbatim from `.orly/orly.json`; expand S3
 for every remaining declared lane. Additional spec-specific checks stay explicit. 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

package/docs/VERIFY_TIERS.md

@@ -9,12 +9,12 @@ page carries only what is specific to this repository.
 | Tier | Command | When |
 |---|---|---|
 | conform | `make harness-verify` | Section lane and boundary, after EXECUTE and before the rest. Any 🔴 returns to EXECUTE. |
-| lint | `make lint-all` | Boundary. Rust rides `lint-rustd` (rustfmt + Clippy, warnings are errors); script self-tests ride `lint-scripts`. |
+| lint | `make lint-all` | Boundary. Rust rides `lint-rustd` (rustfmt + Clippy, warnings are errors). |
 | unit | `make test-unit-all` | Boundary. The cargo workspace plus every TypeScript package coverage gate. |
 | version | `make check-version` | Boundary. `VERSION` against `build.zig.zon`, `cli/package.json` and both `rustd/Cargo.toml` sites. |
 | integration | `make test-integration-rustd` | Boundary. Live Postgres and Dragonfly via docker compose, schemas reset per run. `orly gate pr` skips it on a branch carrying no code. |
 
-These are the commands `.oracle/orly.json` declares. The commit hook runs
+These are the commands `.orly/orly.json` declares. The commit hook runs
 conformance; `orly gate pr` runs every verification row.
 
 The authoritative timing and gate ownership live in

package/docs/greptile-learnings/RULES.md

@@ -131,7 +131,9 @@ every code a dispatch `.sh` emits resolves to exactly one row here.
 
 ## RULE XCC — Cross-compile before commit (Zig)
 
-**Rule:** Run zig build -Dtarget=x86_64-linux && zig build -Dtarget=aarch64-linux before every Zig commit.
+**Rule:** Compile the repository's declared platform matrix and applicable test
+graphs before its Zig verification boundary.
+For `agentsfleet`, compile both `x86_64-linux` and `aarch64-linux`. <!-- oracle-packs:product.agentsfleet -->
 **Why:** macOS APIs (client.open, etc.) compile locally but don't exist on Linux; CI cache hides it in dev.
 **Tags:** zig, ci
 **Example:** client.open compiled on macOS, absent on Linux — 3 rounds to fix. v0.4.0 bare -gnu in CI.
@@ -139,7 +141,10 @@ every code a dispatch `.sh` emits resolves to exactly one row here.
 <!-- oracle-packs:start language.zig -->
 ## RULE FLS — Flush all layers — drain all results
 
-**Rule:** After TLS flush, also flush the socket layer. Cast UUID/JSONB to ::text in SELECT. For pg results: use `PgQuery` (see dispatch/write_zig.md "Pg Query Wrapper") — `defer q.deinit()` auto-drains. Manual `q.drain() catch {}; q.deinit()` on early-exit paths is eliminated by the wrapper.
+**Rule:** Flush every transport layer and drain query results on every exit.
+Use the repository's query wrapper when it owns draining; otherwise release
+results explicitly without discarding a failure silently.
+For `agentsfleet`, use `PgQuery` as `dispatch/write_zig.md` specifies. <!-- oracle-packs:product.agentsfleet -->
 **Why:** TLS flush only encrypts into buffer; undrained slices dangle; ::text prevents binary/text divergence across OS.
 **Tags:** zig, tls, postgres
 **Example:** Zig — missing socket flush → infinite hang. UUID read as binary on Linux CI, text on macOS. PgQuery wraps drain into deinit.
@@ -196,8 +201,14 @@ every code a dispatch `.sh` emits resolves to exactly one row here.
 
 ## RULE MIG — Migration index assertions track position
 
-**Rule:** When inserting, splitting, or removing migration files, update every index-based assertion in `src/cmd/common.zig`. While `cat VERSION` < 0.30.0, removed files become `SELECT 1;` (see RULE SCH) — their array slot stays but the assertion must match the new content.
-**Why:** Stale index silently points at the wrong SQL file with no compile-time error. assertions checked for CREATE TABLE in files that were now `SELECT 1;` version markers.
+**Rule:** When inserting, splitting or removing migrations, update registration
+and every position-based assertion under the repository's live-data policy.
+<!-- oracle-packs:start product.agentsfleet -->
+For `agentsfleet`, RULE SCH requires complete removal below `0.30.0`, including
+embed and migration registrations; `SELECT 1;` markers are forbidden.
+At and above that boundary, preserve shipped slots and add forward migrations.
+<!-- oracle-packs:end -->
+**Why:** A stale position points at the wrong SQL file without a compile error.
 **Tags:** zig, sql
 **Example:** migrations[7] pointed at wrong file after a split. migrations[14]/[15] asserted dropped table names in version marker files.
 
@@ -390,20 +401,34 @@ a rename of the first would have disabled the account purge with no failing test
 **Tags:** zig
 **Example:** HMAC version "v0" derived by slicing "v0=" prefix — fixed with explicit hmac_version field.
 
-## RULE SCH — Pre-v0.30 schema removal: full teardown, no markers, no DROP
+## RULE SCH — Schema removal follows the repository's live-data policy
+
+**Rule:** Preserve shipped migrations and live data under the repository's own
+deployment policy. A destructive change requires the owner's specific approval;
+another product's version number never authorizes a rebuild here.
 
-**Rule:** While `cat VERSION` < 0.30.0 (teardown-rebuild era), removing tables MUST be a full teardown: (1) delete the SQL file (`rm schema/NNN_foo.sql`), (2) remove the `@embedFile` constant from `schema/embed.zig`, (3) remove the migration array entry from `src/cmd/common.zig` and update its array length + any index-based tests. Never write ALTER TABLE, DROP TABLE, or `SELECT 1;` placeholders. Never keep version-marker files. Migration slot numbers are not sacred pre-v0.30 — the DB is wiped on every rebuild, and gaps in numbering are fine. From VERSION >= 0.30.0 the datastore is live production data, so every removal or reshape is a numbered ALTER/DROP migration and the teardown path is closed. **Compare the version field by field, never as a string:** `0.29.0` is under the anchor, `0.30.0` is not, and a lexical compare puts `0.30.0` below `0.9.0` — the anchor moved off a major-number boundary precisely so the minor field decides.
+<!-- oracle-packs:start product.agentsfleet -->
+
+**Rule:** While `cat VERSION` < 0.30.0 (teardown-rebuild era), removing tables MUST be a full teardown: (1) delete the SQL file (`rm schema/NNN_foo.sql`), (2) remove the `@embedFile` constant from `schema/embed.zig`, (3) remove the migration array entry from `rustd/crates/afd_db/src/migration.rs` and update its registration tests. Never write ALTER TABLE, DROP TABLE, or `SELECT 1;` placeholders. Never keep version-marker files. Migration slot numbers are not sacred pre-v0.30 — the DB is wiped on every rebuild, and gaps in numbering are fine. From VERSION >= 0.30.0 the datastore is live production data, so every removal or reshape is a numbered ALTER/DROP migration and the teardown path is closed. **Compare the version field by field, never as a string:** `0.29.0` is under the anchor, `0.30.0` is not, and a lexical compare puts `0.30.0` below `0.9.0` — the anchor moved off a major-number boundary precisely so the minor field decides.
 **Why:** Markers accumulate dead code and still force CI to splitter-parse them. Below 0.30.0 the development database is dropped and re-created from empty, so there is no production data to protect and full removal leaves no false grep hits or stale migration slots. At 0.30.0 that stops being true: the deployment holds data nobody can re-create, which is what makes an in-place migration the only safe shape from then on.
 **Tags:** sql, process
 **Example:** harness teardown — supersedes prior "replace with `SELECT 1;`" guidance. Under the old rule, comment-only markers broke CI (apostrophe in "slots" opened unterminated string in splitter); full deletion avoids the marker problem entirely.
 
-## RULE EP4 — Removed endpoints return 410 Gone, not 404 (from v0.30 on)
+<!-- oracle-packs:end -->
+## RULE EP4 — Endpoint removal follows the declared client policy
+
+**Rule:** Check the repository's deployed clients and deprecation policy before
+removing an endpoint. State the client-visible result and test it; installing
+a pack cannot establish that every caller can be changed together.
+
+<!-- oracle-packs:start product.agentsfleet -->
 
 **Rule:** While `cat VERSION` < 0.30.0 (teardown-rebuild era), removed endpoints MAY simply 404 — API drift is allowed because no deployed client is pinned to the route. Do NOT write 410 Gone stubs for pre-v0.30 removals; they are ceremony without value. From VERSION >= 0.30.0, intentionally removed endpoints MUST return HTTP 410 Gone with a named error code — 404 implies a routing error to monitors and clients, 410 signals permanent intentional removal.
 **Why:** Below 0.30.0 this mirrors the schema teardown policy (RULE SCH) — we tear down DB + APIs freely because nobody downstream is pinned to them. From 0.30.0 the deployment is in production and 410 becomes load-bearing for client behavior and deprecation signals.
 **Tags:** zig, api
 **Example:** shipped /v1/runs/* + /v1/specs as 410 stubs before this rule was scoped. removed /v1/harness/* and /v1/agents/{id} as bare 404s under the teardown-era carve-out.
 
+<!-- oracle-packs:end -->
 ## RULE FXS — Fixed-size scan buffers are security bypasses
 
 **Rule:** Scan security-relevant input in overlapping chunks; never silently truncate at a fixed buffer size.
@@ -420,7 +445,10 @@ a rename of the first would have disabled the account purge with no failing test
 
 ## RULE OBS — Every observable state must have a log/event entry
 
-**Rule:** Every branch that changes how an external party perceives the system MUST emit a structured log line. "External party" includes operators reading dashboards, callers receiving an HTTP response, downstream consumers of a queue, end-users running `agentsfleet`, and incident responders running `journalctl`. If a code path can be read as "we decided to do something different here," it is observable, and it MUST be logged. **Applies to every Zig source file under `src/` and every JS source file under `agentsfleet/src/`** — handler code, middleware, workers, CLI commands, lifecycle code, retries, fallbacks, all of it.
+**Rule:** Every branch that changes externally observable behavior emits a
+structured event for operators, callers or downstream consumers.
+Apply this across the repository's runtime source paths: handlers, middleware,
+workers, commands, lifecycle code, retries and fallbacks.
 
 **Why:** Silent state transitions are invisible in dashboards and incident response. The code can be 100% correct on the wire and 100% opaque to the operator at the same time. A dropped GitHub webhook the user can't explain, an `agentsfleet` command that exited 0 with no output, a worker that silently skipped a job — same root cause, same fix: log the branch.
 
@@ -436,30 +464,32 @@ a rename of the first would have disabled the account purge with no failing test
 
 ### Per-stack convention
 
-#### Zig — `std.log.scoped(.module_name)`
+#### Zig — the repository's structured logger
 
 Every Zig source file that emits any log MUST declare a file-scoped logger with a snake_case scope tag derived from the module's job:
 
 ```zig
-const log = std.log.scoped(.<module_name>);
+const logging = @import("log");
+const log = logging.scoped(.module_name);
 ```
 
 Picking the scope name:
 - The scope IS the module identity in operator-facing logs. Choose specifically (`.webhook_sig_lookup`, `.agent_event_loop`, `.firewall`, `.clerk_webhook`) rather than generically (`.agentsfleetd`, `.utils`).
 - One scope per file is the default. Sibling files in the same package use the same scope only if they're a single logical module split across files for length-gate reasons.
-- Existing scopes already cover most subsystems — grep `std.log.scoped\(\.` before inventing a new one. Consistency with neighbors beats novelty.
+- Read the repository's logger exports and existing scopes before choosing a new one. For `agentsfleet`, use the named `log` module's `logging.scoped` as `docs/LOGGING_STANDARD.md` §7 specifies.
 
-Format the message body as `<scope>.<state> <key>=<value> <key>=<value>`:
+Emit an event name and structured fields through that logger:
 - **state** is a short snake_case noun phrase naming the branch — `parse_failed`, `dedup_replay`, `ignored_event`, `metering_debit`, `claim_skipped`. Operators grep on `<scope>.<state>`; make it unique and stable.
 - **key=value** pairs carry correlation IDs needed to join with downstream traces. Always include `req_id` for request-scoped paths. Add `agent_id` / `workspace_id` / `tenant_id` / `delivery` / `reason` / `err` where relevant.
-- Severity: `log.info` for routine non-default branches (ignores, dedupes, retries), `log.warn` for malformed input / fail-closed / unexpected-but-recoverable, `log.err` for internal failures and contract violations.
+- Severity and operation pairs follow `docs/LOGGING_STANDARD.md` §4, including `debug` for per-row and hot-poll events.
 
 ```zig
-const log = std.log.scoped(.http_webhook_github);
+const logging = @import("log");
+const log = logging.scoped(.http_webhook_github);
 // ...
-log.info("github_webhook.ignored_event agent_id={s} delivery={s} event={s}", .{ agent_id, delivery, event });
-log.warn("github_webhook.parse_failed agent_id={s} delivery={s} err={s}", .{ agent_id, delivery, @errorName(err) });
-log.err("github_webhook.enqueue_failed agent_id={s} delivery={s} err={s}", .{ agent_id, delivery, @errorName(err) });
+log.debug("github_webhook_ignored_event", .{ .agent_id = agent_id, .delivery = delivery, .kind = event });
+log.warn("github_webhook_parse_failed", .{ .reason = @errorName(err) });
+log.err("github_webhook_enqueue_failed", .{ .error_code = code, .reason = @errorName(err) });
 ```
 
 #### JS CLI (`agentsfleet`) — structured stderr via `writeError` + diagnostic JSON in `--json` mode
@@ -593,12 +623,21 @@ This is intentionally manual — the structural diversity of "function body" acr
 **Tags:** security, architecture, multi-tenancy, confused-deputy
 **Example:** design review — original draft proposed SQLite on a persistent host volume; rejected because agent shell tools could read sibling agents' directories. Storage moved to a dedicated Postgres database with a scoped `memory_runtime` role. The rule generalizes: it applies to any future cross-tenant data (per-workspace caches, per-customer artifacts, per-agent workspaces).
 
-## RULE WAUTH — Every workspace-scoped handler must call authorizeWorkspace after authenticate
-
-**Rule:** Any handler that takes a `workspace_id` URL parameter must (1) capture the principal from `common.authenticate` — never discard with `_ =` — and (2) call `common.authorizeWorkspace(conn, principal, workspace_id)` immediately after acquiring a DB connection. A 403 must be returned before any data is read or written.
+## RULE WAUTH — Authenticate and authorize workspace access before data access
+
+**Rule:** Every workspace-scoped operation authenticates the caller and proves
+workspace ownership before reading or writing data. Use the repository's
+canonical guard mechanism; mounted guards count only when the route declares
+both checks and tests prove unauthenticated and wrong-workspace callers fail.
+<!-- oracle-packs:start product.agentsfleet -->
+The current `agentsfleet` route row and mount perform these checks, as
+`docs/REST_API_DESIGN_GUIDELINES.md` §7–§8 specifies; handlers do not duplicate them.
+The former Zig `common.authenticate` and `common.authorizeWorkspace` call shape
+below records the original finding, not the current handler API.
+<!-- oracle-packs:end -->
 **Why:** External agents handlers discarded the principal with `_ = common.authenticate(...)`, so any authenticated workspace owner could enumerate, create, or delete agents in a different workspace just by substituting the workspace_id in the path. Caught by greptile on PR #205 (P0).
-**Do:** `const principal = common.authenticate(...) catch |err| { ... }; ... if (!common.authorizeWorkspace(conn, principal, workspace_id)) { return 403; }`
-**Don't:** `_ = common.authenticate(...) catch |err| { ... };`
+**Do:** Test the served route's unauthenticated and wrong-workspace requests.
+**Don't:** Discard the principal or rely on an unmounted guard.
 **Tags:** zig, security, IDOR, auth
 **Example:** Zig — external_agents.zig — all 3 handlers missing workspace check. Fixed PR #205.
 
@@ -650,7 +689,9 @@ return switch (resp) { .integer => |n| n == 1, else => false };
 
 ## RULE SGR — SQL migrations must include GRANT statements for all created tables
 
-**Rule:** Every `CREATE TABLE` migration must end with `GRANT` statements for every role that will query the table. Check which operations the application performs (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) against this table and grant exactly those to `api_runtime` and/or `worker_runtime` as appropriate.
+**Rule:** Every `CREATE TABLE` migration grants exactly the operations its
+runtime callers need to the repository's actual roles; identify those roles
+from the connection configuration rather than another product's names.
 **Why:** PostgreSQL denies all access by default. Without grants, every query against the table fails with `permission denied` in production. This is invisible at migration time and only fails at first runtime use.
 **Do:** Follow every `CREATE TABLE` + indices block with grants mirroring the table's callers.
 **Don't:** Ship a migration without grants on the assumption that a superuser connection is used in production.
@@ -841,13 +882,19 @@ const handleConfirm = useCallback(async () => {
 
 ## RULE ITF — Integration tests use real schema via `test_fixtures_<name>.zig`
 
-**Rule:** An integration test that exercises any production SQL table must seed rows in the real schema through a shared `src/db/test_fixtures_<testname>.zig` module and assert against the real table. Do **not** create a session-local `CREATE TEMP TABLE` that mocks a production table's shape — the mock drifts from reality, hides schema changes, and lets tests pass against signatures the real query would reject.
+**Rule:** An integration test exercising a production table seeds the real
+schema through shared repository fixture helpers and asserts against that table.
+Never mock its shape with a session-local temporary table: the mock can hide
+schema changes that the production query would reject.
 **Why:** Every workspace-column migration in M11 broke TEMP-TABLE-based tests silently because the temp shape still matched the old column set. Real-schema fixtures fail loudly when a NOT NULL column is added, which is the correct failure mode. Fixtures also keep auth/scope UUIDs out of production source files so `src/http/**` stays free of test scaffolding.
-**Do:**
+**Do:** Name fixture helpers by behavior and keep them outside production modules.
+Use the repository's actual language, registration and cleanup conventions.
+<!-- oracle-packs:start product.agentsfleet -->
 - One fixture module per test scope, named `src/db/test_fixtures_<scope>.zig` with a **semantic** scope name — e.g. `test_fixtures_prompt_events.zig`, `test_fixtures_http_auth.zig`, `test_fixtures_workspace_credit.zig`. Do **not** use milestone-numbered names (`test_fixtures_uc1.zig`, `test_fixtures_m18.zig`, etc.); those rot as milestones churn and the filename stops describing the scope. Aliases inside test files should also be semantic (`credit_fx`, `billing_fx`, `proposal_fx`), never `uc1`/`uc3`.
 - Module exports: `TENANT_ID`/`WORKSPACE_ID` constants, `seed(conn)` / `seedXxx(conn, ...)`, and an idempotent `cleanup(conn)` that deletes in FK-safe order. Reference production seed helpers (`base.seedTenantById`, `base.seedWorkspaceWithTenant`, `base.seedWorkspaceWithCreator`) rather than re-rolling INSERT SQL.
 - Tests: `cleanup(conn)` as both pre-seed reset and `defer` bookend, then `seed(conn)` and run assertions against schema-qualified table names (`core.workspaces`, `core.prompt_lifecycle_events`, …).
 - Tables with append-only triggers: cleanup wraps DELETEs in `SET session_replication_role = 'replica'` / `origin` (superuser-only; test DB runs as superuser via docker-compose).
+<!-- oracle-packs:end -->
 **Don't:**
 - `CREATE TEMP TABLE <real_table_name>` that shadows a real table. `rls_probe`-style probe tables with no production counterpart are fine; naming an existing table is not.
 - Inline test-fixture constants (`GUARD_TENANT_ID`, `SCOPE_WS_PRIMARY`, …) or `cleanupXxxFixtures` helpers inside production source files. Move them to the fixture module.
@@ -939,7 +986,14 @@ const handleConfirm = useCallback(async () => {
 **Tags:** cli, error-messages, ux, refactor
 **Example:** Zig — pR #258. Greptile P1 finding `3145406909`: UZ-ZMB-008 hint still said `Run 'agentsfleet install <template>'` after the legacy positional form was removed in §1 of the same PR. Sweep also caught a stale `// agentsfleet up sends both files raw` comment in `config.zig` header. Fix in commit (this commit).
 
-## RULE NLG — No legacy compat shims pre-v0.30.0
+## RULE NLG — No speculative compatibility shims
+
+**Rule:** Update the existing interface and its callers together when the
+repository's deployment policy permits it. Do not add compatibility aliases
+without an explicit owner decision naming the external caller and migration.
+Never infer the absence of deployed clients from another product's version.
+
+<!-- oracle-packs:start product.agentsfleet -->
 
 **Rule:** Until `VERSION` reaches `0.30.0`, no deployment we owe compatibility to is running: the datastore is rebuilt from empty and every caller of every interface is in this tree. Every interface change therefore extends the existing surface in place — never via a `V2`-suffixed twin, parallel "legacy" path, `if (legacy_caller)` branch, command-line alias for an old verb or flag, or backward-compat fallback. When an RPC, route, struct, table, command, flag, or config key changes, edit the existing one and update every caller in the same commit. When a behavior is replaced, delete the old code path, do not leave it `orelse` reachable. The Schema Table Removal Guard's "teardown-rebuild era" framing applies to every interface, not just SQL. `0.30.0` is the release that ends it: from there the deployment is in production, a caller can be outside this tree, and a compatibility surface is a design decision with a migration behind it — proposed to the owner, never added as a hedge. Compare the version field by field, never as a string.
 
@@ -959,6 +1013,7 @@ const handleConfirm = useCallback(async () => {
 **Tags:** architecture, refactor, versioning, plan, execute
 **Example:** PLAN, Apr 29, 2026. The temptation to introduce `CreateExecutionV2` to avoid editing the existing RPC and its callers came up during spec audit — rejected because (a) the executor RPC has a single in-tree caller (the worker) and (b) the release that puts us in production had not shipped, so no external compatibility was owed. Rule generalizes the call: in-place extension is the only sanctioned path until VERSION crosses 0.30.0.
 
+<!-- oracle-packs:end -->
 ## RULE RTM — Route matchers segment-based, never substring-based
 
 **Rule:** All HTTP path matchers (in projects with a custom dispatch layer) operate on a canonical `Path` view — a stack-allocated array of segments parsed once at the dispatch boundary. Matchers compare by **segment count + segment[i] equality**. Do not use `startsWith` / `endsWith` / `indexOf` against the raw path. Do not encode disambiguation as call-site ordering. Reservations of literal segments live as explicit `if (p.eq(i, RESERVED)) return null` predicates inside the matchers, so any two matchers in a family are mutually exclusive by structure.

package/llms.txt

@@ -10,7 +10,13 @@ ignored. Hosts supported: Claude Code, Codex, OpenCode, Amp.
 
 Package: `@agentsfleet/orly` (npm)
 Source: https://github.com/agentsfleet/orly
-License: MIT
+License: Massachusetts Institute of Technology (MIT)
+
+This checkout prepares the unpublished 0.12.0 candidate. Published 0.11.0 already
+contains the same runtime commands and `.orly/` layout. The `bunx` commands below
+fetch the published package. Use the installed local tarball for candidate checks.
+The comparison evaluator is parked for proposed 0.13 work; do not claim measured
+judgment improvement or enable new questions from its unfinished results.
 
 ---
 
@@ -36,19 +42,17 @@ Run from the repository root. Execute these in order and stop at the first
 non-zero exit.
 
 ```bash
-# 1. install the executable used by Git hooks
-bun add -g @agentsfleet/orly
-
-# 2. preview, then initialize
-orly init --dry-run
-orly init
+# 1. preview, then initialize through Bun's package runner
+bunx --bun @agentsfleet/orly init --dry-run
+bunx --bun @agentsfleet/orly init
 
 # 3. complete any reported setup items, then check configuration and files
-orly doctor
+bunx --bun @agentsfleet/orly doctor
 ```
 
 Then commit the result. Teammates receive the rules on clone.
-Keep `orly` on `PATH`; hooks use the installed executable.
+Generated hooks invoke the package version pinned in `.orly/orly.json` through
+`bunx`; they do not require a global executable.
 
 IMPORTANT: git does not clone hooks. Each checkout must run `orly init` once.
 If a human reports that gates are not firing, this is the first thing to check.
@@ -60,15 +64,15 @@ If a human reports that gates are not firing, this is the first thing to check.
 | Path | Contents | Owner |
 |---|---|---|
 | `AGENTS.md` | your host auto-loads this | the user — never rewrite it |
-| `AGENTS.orly.md` | generated rules: safety, dispatch router, lifecycle | orly — rewritten on update |
-| `dispatch/*.md` | one rule page per kind of work | orly |
-| `audits/*.sh` | the deterministic gates | orly |
-| `docs/*.md` | the standards those rules cite | orly |
+| `.orly/AGENTS.md` | generated rules: safety, dispatch router, lifecycle | orly — rewritten on update |
+| `.orly/dispatch/*.md` | one rule page per kind of work | orly |
+| `.orly/audits/*.sh` | the deterministic gates | orly |
+| `.orly/docs/*.md` | the standards those rules cite | orly |
 | `.claude/skills/`, `.agents/skills/`, `.opencode/skills/` | skills materialised per host | orly |
-| `.githooks/` | pre-commit and pre-push, wired to `orly gate` | orly |
-| `.oracle/orly.json` | packs, gate commands, install record | shared — edit the commands |
+| `.orly/hooks/` | pre-commit and pre-push, wired to pinned `orly gate` | orly |
+| `.orly/orly.json` | packs, gate commands, install record | shared — edit the commands |
 
-`orly init` seeds `.oracle/orly.json` with gate commands found in `Makefile` or
+`orly init` seeds `.orly/orly.json` with gate commands found in `Makefile` or
 `package.json`. Read the repository's build files to complete missing commands;
 ask only when the repository does not define a check. Do not invent commands.
 Declare `conform` and at least one named `verify.*` command. Documentation
@@ -77,12 +81,19 @@ suites. `init` reports missing configuration; `doctor` rejects it.
 
 ---
 
+For a 0.10.x consumer with repository-owned hooks, run `orly update --no-hooks`
+using the intended installed version. Change repository callers from
+`.oracle/orly.json` to `.orly/orly.json` and shared rule/audit paths to `.orly/`.
+Keep repository-owned scripts and documents in place. Run `orly doctor` and the
+declared checks before accepting the migration; doctor alone does not run checks.
+Empty old directories may remain, but contain no tracked managed files.
+
 ## 4. Read order before you edit anything
 
 1. `AGENTS.md` — the user's own rules. **These win on any conflict.**
-2. `AGENTS.orly.md` — the generated rules and the dispatch router.
-3. The `dispatch/*.md` page that matches the kind of file you are about to edit.
-4. Any `docs/*.md` standard those pages cite.
+2. `.orly/AGENTS.md` — the generated rules and the dispatch router.
+3. The `.orly/dispatch/*.md` page that matches the kind of file you are about to edit.
+4. Any `.orly/docs/*.md` standard those pages cite.
 
 Re-read step 3 for each new file kind you touch in the same task.
 
@@ -94,7 +105,7 @@ The spec is a file on disk. Its directory is the status. Only the named stages
 move it. `orly gate pr` reads where it ended up.
 
 ```
-docs/v1/pending/   spec written, committed on main
+docs/v1/pending/   spec written, committed on the detected default branch
       │
       │  CHORE(open)   branch cut, comparison revision recorded, baseline measurement pending
       ▼
@@ -107,7 +118,7 @@ docs/v1/done/      orly gate pr green → Pull Request opens
 
 Rules for you:
 
-- Write the spec yourself before any code exists.
+- Invoke `orly-spec-new` before any code exists; it uses the canonical template body.
 - Do not write code before `CHORE(open)` has committed.
 - Do not skip a stage. The hooks run gates on every commit and push.
 - A red gate returns you to EXECUTE. Fix the cause; do not retry unchanged.
@@ -122,9 +133,9 @@ Rules for you:
 | same gate fails twice on the same cause | stop, report the gate name and output to the user |
 | `orly init` refuses a file | orly did not write that file. Report it. Do **not** pass `--force` on your own initiative |
 | hooks not firing | run `git config core.hooksPath` and confirm `orly init` was run in this checkout |
-| gate command missing from `.oracle/orly.json` | read the build files and declare the existing check; ask only if none exists |
+| gate command missing from `.orly/orly.json` | read the build files and declare the existing check; ask only if none exists |
 | `orly gate pr` red and the failure is genuinely inapplicable | ask the user; only they authorise `orly override` |
-| gstack `/review` unavailable | continue; orly records the skipped review in the PR notes |
+| gstack `/review` unavailable | record the reason and time in Pull Request Session notes; rerun before merge |
 
 Overrides are recorded as an empty commit that rides into the Pull Request:
 
@@ -141,11 +152,13 @@ never with a placeholder reason.
 
 - Never rewrite `AGENTS.md`. orly adds one delimited pointer block; leave the
   rest alone.
-- Never edit or delete files under `.githooks/` or `audits/` to make a gate pass.
+- Never edit or delete repository or installed hook and audit scripts to evade a finding.
 - Never pass `--force` or `--no-hooks` unless the user asks for it by name.
-- Never disable a check in `.oracle/orly.json` to get green.
+- Never disable a check in `.orly/orly.json` to get green.
 - When the user's `AGENTS.md` and orly's rules disagree, the user's file wins.
-- A refused run changes nothing. Report the refusal; do not retry with flags.
+- A preflight ownership refusal preserves owner bytes. An interrupted installation
+  can leave intended new files and a recovery journal; resume with the same package
+  version after resolving the reported conflict. Do not retry with bypass flags.
 
 ---
 
@@ -166,7 +179,7 @@ never with a placeholder reason.
 
 ## 9. Packs
 
-Nine language packs are selected from file extensions in the user's source.
+Language and SQL packs are selected from file extensions in the user's source.
 orly scans four directories deep and skips `node_modules`, `target`, `.venv`,
 and other dependency trees.
 
@@ -179,9 +192,9 @@ Seven install in every repository: `universal.authoring`, `domain.http`,
 `domain.auth`, `domain.documentation`, `domain.changelog`,
 `workflow.specifications`, `workflow.skills`.
 
-Three install only when `.oracle/orly.json` names them: `workflow.governance`
-(editing orly's own rules), `product.agentsfleet` (agentsfleet-specific audits
-and docs), `persona.indy` (tone and address handles only, no files).
+Three install only when `.orly/orly.json` names them: `workflow.governance`
+(editing orly's own rules), `product.agentsfleet` (audits and docs for
+`agentsfleet`), `persona.indy` (tone and address handles only, no files).
 
 Skills provided by `workflow.skills`, per repository: `orly-spec-new`,
 `orly-babysit-prs`, `orly-write-unit-test`, `orly-write-integration-test`.
@@ -203,10 +216,9 @@ make audit
 
 - `make audit` is the bar: typecheck and unit tests, render determinism, and
   gate fixtures (each gate proved against one passing and one failing case).
-  Runs in parallel, under half a minute.
-- Coverage floor is 90% lines. Below it, the workflow fails.
+  Runs in parallel and retains full command output.
 - `make install-evals` runs real installs into throwaway repositories. Run on
-  demand; CI runs them on every pull request and release.
+  demand; Continuous Integration (CI) runs them on every Pull Request and release.
 - Render orly's own rules with `bin/orly update --no-hooks`. The `--no-hooks`
   flag is required here because this checkout hand-wrote its `.githooks/`.
 - Release: merge to `main` with a new `package.json` version. That publishes,
@@ -220,7 +232,7 @@ After install, verify your own understanding by answering this from the
 repository, without guessing:
 
 ```
-Read AGENTS.orly.md. Name which of the last ten commits would have tripped a
+Read .orly/AGENTS.md. Name which of the last ten commits would have tripped a
 gate, and the rule that caught each one.
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.10.14",
+  "version": "0.12.0",
   "description": "Repository-scoped engineering harness: renders agent rules, materialises the gates that enforce them, and proves the PR boundary \u2014 for any coding agent.",
   "license": "MIT",
   "type": "module",
@@ -60,5 +60,10 @@
   "devDependencies": {
     "@types/bun": "1.4.0",
     "typescript": "7.0.2"
+  },
+  "dependencies": {
+    "@babel/parser": "7.29.9",
+    "@babel/types": "7.29.8",
+    "zod": "4.6.5"
   }
 }

package/packs/language/go/rules.md

@@ -31,4 +31,4 @@ Both are carve-outs for what the *language* makes unfixable, not permission —
 a flag name or a label spelled inline twice is still the rule.
 
 The repository owns formatting, vet, lint, build, and test commands — it
-declares them in `.oracle/orly.json`.
+declares them in `.orly/orly.json`.

package/packs/language/python/rules.md

@@ -7,4 +7,4 @@ 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`.
+them in `.orly/orly.json`.

package/packs/language/rust/rules.md

@@ -10,10 +10,26 @@ 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`.
+commands — it declares them in `.orly/orly.json`.
 
 ## Reference guideline (mandatory in review)
 
+Before designing Rust modules, read the relevant implementation in Exonum,
+Apache Arrow's Rust implementation, or the local `agentsfleet` Rust workspace.
+Indy's checkouts are `~/Projects/oss/rs/exonum`,
+`~/Projects/oss/rs/arrow-rs`, `~/Projects/agentsfleet/rustd/`, and
+`~/Projects/oss/rs/builder/components/builder-core/`.
+Use Exonum for state and API boundaries and Arrow for typed data and workspace
+structure. Use `agentsfleet/rustd/crates/agentsfleetd/` specifically for errors
+and the command-line interface (CLI); inspect its actual call sites before designing.
+Use `afd_core::env::EnvSource` for injected process and test environments.
+Builder's `ConfigFile` trait supplies prior art for composable file loading and
+cause-preserving parsing. Read its call sites; retain current edition safety and
+library logging rather than copying its older global environment mutation or logger.
+Read only relevant modules and name the pattern applied or the reason to diverge.
+These are read-only references; consumer changes require their own authorization.
+Other machines locate the equivalent checkout before asking to clone one.
+
 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:

package/packs/language/shell/rules.md

@@ -7,4 +7,4 @@ every exit path. Avoid `eval` for external input. Match the repository's require
 shell and macOS Bash compatibility level.
 
 The repository owns ShellCheck and executable tests — it declares them in
-`.oracle/orly.json`.
+`.orly/orly.json`.