@agentsfleet/orly 0.10.14 → 0.12.0

package/.githooks/pre-push

@@ -32,7 +32,8 @@ if command -v gitleaks >/dev/null 2>&1; then
     exit 1
   fi
 else
-  echo "pre-push: gitleaks NOT INSTALLED — secret scan skipped (mise use -g gitleaks)" >&2
+  echo "pre-push: required gitleaks is not installed — install it with mise before pushing" >&2
+  exit 1
 fi
 
 GOVERNANCE_PATTERN='^((core|packs|schemas|src)/|(registry|repositories)\.json|AGENTS\.md|SOUL\.md|dispatch/|audits/|docs/(EXECUTE_DOC_READS|ORLY_ARCHITECTURE|HARNESS_VERIFY_OUTPUT|DOCUMENTATION_RULES|TEMPLATE)\.md|evals/|fixtures/|\.githooks/|Makefile|README\.md|package\.json|bun\.lock|tsconfig\.json)'

package/AGENTS.md

@@ -90,7 +90,7 @@ Auto-memory is **disabled** (`autoMemoryEnabled: false` + `CLAUDE_CODE_DISABLE_A
 - No new `make` targets without a distinct caller (CI job, spec-mandated gate, or a workflow existing targets can't express) — check `make/*.mk` first; extend over near-duplicate wrappers.
 - `*.zig` → read `dispatch/write_zig.md`; ZIG GATE fires.
 - Auth-flow (token-minting handlers, credential-typed spec dimensions, the repository's auth directories) → read the repository's `docs/AUTH.md` first, where it exists.
-- **Indy's reference checkouts** (the machine-local half of the rule above): TypeScript → `oss/supabase/apps/studio` + `oss/supabase/packages/{ui,ui-patterns}` + `oss/cli`; Zig → `oss/ghostty/src/`; Rust → `oss/bun/src/` + `oss/exonum` + `oss/core_api-develop`. Missing checkout → ask, then clone into `~/Projects/oss/`.
+- **Indy's reference checkouts** (`~/Projects/`): TypeScript → `oss/supabase/apps/studio` + `oss/supabase/packages/{ui,ui-patterns}` + `oss/cli`; Zig → `oss/ghostty/src/`; Rust → `oss/rs/exonum` + `oss/rs/arrow-rs` + `agentsfleet/rustd/` + `oss/rs/builder/components/builder-core/`. Missing → search `oss/rs/`; ask before cloning.
 
 **Forge detection:** `github.com` → `gh`; `gitlab.com` → `glab`. Check `git remote -v`.
 
@@ -120,24 +120,24 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 
 **🚦 Gate-flag triage** — gate fires → never silence, never harness-patch. **Mechanical** (obvious deterministic fix: fmt, lint-autofix, literal → const, over-length → split, dead code): auto-apply + inform the user in one line. **Judgment** (design call / weakened guarantee / security boundary / possible false-positive): STOP, surface the ask — 📟 flagged (symbol·file·line) · 🔦 fix scope (files·lines·follow-on) · 📈 what we gain · 💥 if not fixed (debt·blockages) · ☠️ my call — the user decides fix-or-defer. Never unilaterally call a flag a false-positive.
 
-**Seeded `.oracle/orly.json`?** Complete it first — `verify.*`, `surfaces`, opt-in packs: `dispatch/lifecycle.md` §Bootstrap.
+**Seeded `.orly/orly.json`?** Complete it first — `verify.*`, `surfaces`, opt-in packs: `dispatch/lifecycle.md` §Bootstrap.
 
 **Rule paths resolve relative to this repository's root.** Every `dispatch/…`, `docs/…`, and `audits/…` path a rule cites is a real file here — `orly init`/`orly update` materialised it from the packs this repository selected. A path your repo lacks means its sources never selected that pack, not that the reference is broken.
 
 **Dispatch index — full rule prose in each `dispatch/<entry>.md` façade. Read the façade when its trigger fires — sectioned: scan headers, read the sections the diff touches.** Trigger-surface extensions: `*.zig`, `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.py`, `*.rs`, `*.go`, `*.sh`, `*.sql`, `*.mdx`, and public OpenAPI prose. Latent `.md` per entry, deterministic `.sh` where mechanisable. Signals: 🟢 pass · 🟠 warn · 🔴 fail · 🛑 blocked · 🔥 critical · 🤔 judgment-only · 🟣 delegated. Output glyphs: 🧲 eval · 🛍️ evidence · 👮 security · ⛈️ rule · 💡 info · 📌 note. The router below **is** the gate set.
 
-**Legacy-workaround family** — four rules together: **RULE NDC** (no dead code at write time, `docs/greptile-learnings/RULES.md`), **RULE NLR** (touch-it-fix-it cleanup), **RULE NLG** (no new legacy framing pre-`0.30.0`), **Legacy-Design Consult Guard** (user A/B/C consult before patching/keeping/testing legacy). **No compatibility aliases** — old verbs, flag aliases, route wrappers, env aliases, fallback spellings — unless the user explicitly asks in-session.
+**Legacy-workaround family** — four rules together: **RULE NDC** (no dead code at write time, `docs/greptile-learnings/RULES.md`), **RULE NLR** (touch-it-fix-it cleanup), **RULE NLG** (no speculative compatibility framing; selected product version policy applies), **Legacy-Design Consult Guard** (user A/B/C consult before patching/keeping/testing legacy). **No compatibility aliases** — old verbs, flag aliases, route wrappers, env aliases, fallback spellings — unless the user explicitly asks in-session.
 
 | Trigger — when you… | Dispatch | Latent façade carries · override |
 |---|---|---|
-| write `*.zig` | `write_zig` | `dispatch/write_zig.md` — memory safety, init/deinit + `errdefer`, pub shape verdict (`FILE SHAPE DECISION` — auto-mode does NOT cover), tagged unions, length caps, cross-compile both linux targets · `ZIG GATE` / `PUB GATE` / `LIFECYCLE GATE: SKIPPED per user override (reason: ...)`. |
+| write `*.zig` | `write_zig` | `dispatch/write_zig.md` — memory safety, init/deinit + `errdefer`, pub shape verdict (`FILE SHAPE DECISION` — auto-mode does NOT cover), tagged unions, length caps, declared cross-compile matrix · `ZIG GATE` / `PUB GATE` / `LIFECYCLE GATE: SKIPPED per user override (reason: ...)`. |
 | write `*.ts`/`*.tsx`/`*.js`/`*.jsx` | `write_ts_adhere_bun` | `dispatch/write_ts_adhere_bun.md` — TS FILE SHAPE DECISION at PLAN, `const`/import/Bun-primitive discipline, raw-HTML → design-system primitive, `*-[...]` → token utility · `UI GATE` / `DESIGN TOKEN GATE: SKIPPED per user override (reason: ...)`; auto-mode does NOT cover; reason must cite a concrete external constraint. |
 | write `*.rs` | `write_rust` | `dispatch/write_rust.md` — ownership, justified `unsafe`, preserved error variants, feature combinations, deterministic concurrency tests · 🤔 judgment-only. |
 | write `*.go` | `write_go` | `dispatch/write_go.md` — wrapped errors, goroutine exit paths, context first, defer at acquire, `-race` · 🤔 judgment-only. |
 | write `*.py` | `write_python` | `dispatch/write_python.md` — standard-library parsing, context-managed resources, boundary validation, specific exceptions · 🤔 judgment-only. |
 | write `*.sh` | `write_shell` | `dispatch/write_shell.md` — quoted expansions, array arguments, temp-file cleanup, no untrusted `eval`, shell compatibility · 🤔 judgment-only. |
 | write `*.mdx` | `write_mdx` | `dispatch/write_mdx.md` — Markdown JSX structure, front matter, links, code fences, image descriptions, Mintlify isolation · 🤔 judgment-only. |
-| write `schema/*.sql` | `write_sql` | `dispatch/write_sql.md` — schema / migration rules + Schema Table Removal Guard (`DROP`/`ALTER` / `schema/embed.zig` / migration-array edits), STS/NSQ/SGR/ITF rules · `SCHEMA GUARD: SKIPPED per user override (reason: ...)`. |
+| write SQL or migration registration | `write_sql` | `dispatch/write_sql.md` — schema / migration rules, repository live-data policy and owner approval for destructive changes; product-specific Schema Table Removal Guard only when selected. |
 | write **any** source file | `write_any` | `dispatch/write_any.md` — File & Function Length, LOGGING, MILESTONE-ID, ERROR REGISTRY (repo-declared scheme, delegated), UFS named-constants, GREPTILE end-of-turn read, legacy family · `LENGTH` / `LOGGING` / `MILESTONE ID` / `UFS GATE: SKIPPED per user override (reason: ...)`; auto-mode does NOT cover. |
 | write a spec under `docs/v*/…` | `write_spec` | `dispatch/write_spec.md` — required + prohibited spec sections (SPEC TEMPLATE GATE), `docs/TEMPLATE.md` shape · `SPEC TEMPLATE GATE: SKIPPED per user override (reason: ...)`; auto-mode does NOT cover; reason must cite a concrete external constraint. |
 | write `src/http/handlers/**` / OpenAPI | `write_http` | `dispatch/write_http.md` — REST API design rules; reads `docs/REST_API_DESIGN_GUIDELINES.md` before · 🟣 delegated. |
@@ -148,7 +148,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 | claim "tests pass / ready / shipping" | `verify` | `dispatch/verify.md` — verification tiers (`make` canonical; package-scoped runners are **not** verification), done-message glyph format · 🤔 judgment-only, `VERIFY GATE: <target> skipped per environment constraint (reason: ...)` only when genuinely unrunnable. |
 | name a stream/channel/Redis namespace/queue/RPC/Postgres schema, or describe a flow | `name_architecture` | `dispatch/name_architecture.md` — architecture-consult discipline; grep relevant `docs/architecture/` (chat brainstorming counts) · **no override** — doc wins until reconciled. |
 | run a lifecycle stage (open→close a stream, worktree setup, milestone bootstrap) | `lifecycle` | `dispatch/lifecycle.md` — stage runbooks: CHORE(open/close) checklists, PLAN expansions, spec discipline, deferral format, pre-PR gates, LAND · 🤔 judgment-only. |
-| edit the governance (`core/**`, `packs/**`, `schemas/**`, `src/**`, `registry.json`, generated `AGENTS.md`, `dispatch/`, audits, hooks) | `edit_rules` | `dispatch/edit_rules.md` — runs `make audit`, the `audits/agents-md.md` questionnaire, live comprehension evaluation when semantics change, and generated evidence · **no override** from the agent (user-only push: `SKIP_INVARIANCE_PUSH=1`). |
+| edit the governance (`core/**`, `packs/**`, `schemas/**`, `src/**`, `registry.json`, generated `AGENTS.md`, `dispatch/`, audits, hooks) | `edit_rules` | `dispatch/edit_rules.md` — runs `make audit`, the `audits/agents-md.md` questionnaire, live comprehension evaluation when semantics change, and generated evidence · **no override** from the agent. |
 
 ---
 
@@ -164,7 +164,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 
 | Event | Action |
 |---|---|
-| New milestone, plan-{eng,ceo,design}-review, `TODO.md` attempt | Invoke `orly-spec-new`. Land in `docs/v{N}/pending/`, `Status: PENDING`, commit on main. |
+| New milestone, plan-{eng,ceo,design}-review, `TODO.md` attempt | Invoke `orly-spec-new`. Land in `docs/v{N}/pending/`, `Status: PENDING`, commit on the detected default branch. |
 | Begin implementation OR branch carries spec changes in `pending/` | CHORE(open): `pending/`→`active/`, `Status: IN_PROGRESS` + `Branch:`, create worktree, commit on feature branch. **No code until 4 steps committed.** |
 | Every commit during implementation | Mark completed Dimensions/Sections `DONE` same commit as the code. |
 | All work complete, before PR | CHORE(close). |
@@ -205,7 +205,7 @@ Edit only approved scope; no opportunistic refactors. Stay in active worktree. C
 
 ### CONFORM
 
-Runs after EXECUTE, before VERIFY. Invokes the `conform` commands the repository declares in `.oracle/orly.json` and aggregates every gate verdict. Any 🔴 returns to EXECUTE; the lifecycle does not advance. This is the `work` gate's tier and the pre-commit hook runs it at every commit: declare a `conform` costing seconds, not minutes.
+Runs after EXECUTE, before VERIFY. Invokes the `conform` commands the repository declares in `.orly/orly.json` and aggregates every gate verdict. Any 🔴 returns to EXECUTE; the lifecycle does not advance. This is the `work` gate's tier and the pre-commit hook runs it at every commit: declare a `conform` costing seconds, not minutes.
 In `agentsfleet` this stage is `make harness-verify`; its output block and end-of-turn audit detail live in `docs/HARNESS_VERIFY_OUTPUT.md`. Required rows: FILE SHAPE, PUB GATE, LENGTH GATE, MILESTONE-ID GATE, ZIG GATE, UI GATE, DESIGN TOKEN GATE, UFS GATE, SCHEMA GUARD, GREPTILE GATE, Architecture consult, Coverage, and `/orly-write-unit-test`.
 
 ### VERIFY
@@ -257,12 +257,6 @@ Required when spec involved — after last COMMIT, before PR. Also runs when par
 > carries the judgment — how Indy decides, what he accepts, what he rejects.
 > In force every session; standing orders, not suggestions. Re-read when
 > padding or burying the answer.
-> Evidence lives in `SOUL_LOG.md` in the orly repository: 24 rows of what I
-> did, what Indy said, and the rule it produced. It does not ship — the
-> package allowlist keeps personal files out of a public release — so these
-> rules carry no back-cites and stand on their own words. Each row names its
-> rule, which is the direction that resolves. Append one the moment he
-> corrects you.
 
 ## Reply shape
 
@@ -270,11 +264,9 @@ Optimise for one thing: he never has to ask twice.
 
 - **Answer first.** Verdict in sentence one. Yes/no questions get yes/no.
 - **Check before asking.** If git, `gh`, or the file system holds the answer,
-  read it. Asking what I could have looked up spends his attention on my
-  laziness.
+  read it.
 - **Decide, do not offer.** One option and why. A menu is right only when the
-  choice is his taste; when the gap is my missing knowledge, go and get it
- .
+  choice is his taste; when the gap is my missing knowledge, go and get it.
 - **Do the revertible work, then report.** A branch, a Pull Request, a backup:
   all revertible, so no permission needed. Stop and ask where undo is real
   work or impossible — force-push, deleting a remote branch, publishing,
@@ -298,7 +290,7 @@ Optimise for one thing: he never has to ask twice.
   fake-profound kickers. End on the clearest concrete sentence. The banned-word
   list lives in `docs/DOCUMENTATION_RULES.md` §DOC-05, §DOC-07, §DOC-14b, and
   `orly gate verify` REPORTS it — `docs.language` prints findings and stays
-  green. Nobody fails a build over this, so the prose is mine to get right.
+  green.
 
 ## Reading Indy
 
@@ -319,27 +311,25 @@ Optimise for one thing: he never has to ask twice.
   included; an external rule quote is not a rewrite mandate — local convention
   wins; skills are config, not code (one `SKILL.md` + one `TRIGGER.md`, no
   YAML allowlists).
-- **An approved default stands** — don't re-open it with tuning menus
- .
+- **An approved default stands** — don't re-open it with tuning menus.
 - **Governance edits:** cut rationale tails, never triggers — ask each
   clause "does this fire, or merely justify?" `make audit` caps the
-  rendered `AGENTS.md` (this file inlined) at 40,960 bytes; adding a rule
-  means making room.
+  rendered `AGENTS.md` (this file inlined); adding a rule means making room.
 - **Corrections route by shape** (`AGENTS.md` §Memory Discipline): rule →
-  dispatch façade; behaviour → a row in `SOUL_LOG.md` at the moment it
-  happens; architecture → repo docs; state → HANDOFF. "I'll remember"
-  without writing it down is a lie.
+  dispatch façade; working style → the applicable rule here;
+  architecture → repo docs; in-flight state → the active spec.
 
 ## Code is the design
 
 - **Load-bearing behaviour facts come from source on the target branch** —
-  never from handoffs, specs, `api.json`, or any prose, eng-reviewed or not
- .
+  never from handoffs, specs, `api.json`, or any prose, eng-reviewed or not.
 - **Reference canon** = `AGENTS.md` §Operational defaults, one list; open the
   reference, then propose. supabase's `data/fetchers.ts` is the template read.
 - **"Broken for us" means I missed the delta.** A pattern shipping in a
   trusted repo is sound; diff our call-site against theirs (version, config,
   wiring) before blaming the principle.
+- **Lint, test and format go through the narrowest make target**, inner loop
+  too (`make lint-app` is oxlint + `tsc`). `eslint` is a hand-roll; never run it.
 - **Fold-into-PR test: completes vs adds**. Folding is right when
   the addition finishes an incoherence the PR would otherwise merge; scope
   creep when merely adjacent. Lead with the call; Indy's timing overrides.
@@ -353,12 +343,12 @@ Optimise for one thing: he never has to ask twice.
 5. Every behaviour claim read from source on the target branch?
 6. Slop scan — contrasts, kickers, banned words?
 7. Acronym + banned-vocab scans (`AGENTS.md`)?
-8. Corrected this session? Row in `SOUL_LOG.md` — now, not later.
+8. Corrected this session? Update the rule where the correction applies.
 
 ---
 
-*Keep every line actionable — a fact that fires nowhere moves to
-`SOUL_LOG.md` or dies. Edit here, then `orly update`.*
+*Keep every line actionable. A fact that fires nowhere has no place here.
+Edit here, then `orly update`.*
 
 ---
 

package/README.md

@@ -42,6 +42,25 @@ Works with Claude Code, Codex, OpenCode, and Amp.
 
 ---
 
+## 0.12.0: migration verification
+
+0.12.0 is a local release candidate. Published 0.11.0 already provides the
+`.orly/` layout and the six existing `orly judge` questions.
+This release focuses on package verification, migration evidence and clearer setup guidance; it adds no new runtime judgment question.
+
+The `agentsfleet` trial upgraded a dedicated worktree from 0.10.14 using the packed candidate.
+Owner files, hooks and verification commands survived; a second update wrote nothing.
+See the [release report](evals/release/release-report.md) for exact proof and remaining release checks.
+
+Jev, TypeSafe's bounded judgment model, supplies advice only when requested.
+Existing deterministic checks retain control of gate results.
+The comparison evaluator is parked for proposed 0.13 work; model accuracy and candidate benefits remain unmeasured.
+See the [judgment reference](docs/JUDGMENTS.md) for evidence selection, offline replay and explicit source upload.
+
+The install commands below fetch the published package. They do not select this unpublished candidate.
+
+---
+
 ## Prerequisites
 
 | You need | Why | Version |
@@ -49,32 +68,33 @@ Works with Claude Code, Codex, OpenCode, and Amp.
 | [bun](https://bun.sh) | runs orly; `bunx` fetches it | ≥ 1.4.0 |
 | git | orly writes the hooks; `orly gate` reads the branch | any |
 | a coding agent | something has to read the rules | Claude Code, Codex, OpenCode, or Amp |
-| your own check commands | `orly gate` runs whatever `.oracle/orly.json` names | whatever your repository already runs |
+| your own check commands | `orly gate` runs whatever `.orly/orly.json` names | whatever your repository already runs |
 
 > [!IMPORTANT]
 > git never clones hooks. Every teammate runs `orly init` once in their own checkout, even after the rules are committed.
 
 ---
 
-## Install
+## Install the published package
 
 Run this inside the repository you want governed.
 
 ```bash
-bun add -g @agentsfleet/orly
-orly init
+bunx --bun @agentsfleet/orly init
 ```
 
 orly scans your source, detects your languages, and installs only the rules that apply.
 
 > [!TIP]
-> Try `orly init --dry-run` first. It previews the generated rules and changes nothing.
+> Try `bunx --bun @agentsfleet/orly init --dry-run` first. It previews the generated rules and changes nothing.
+
+Complete any setup items printed by `init`, then run `bunx --bun @agentsfleet/orly doctor` and commit the generated files.
+Use `bunx --bun @agentsfleet/orly <COMMAND>` for the commands below; `<COMMAND>` names the command and its options.
+Generated Git hooks invoke the pinned package through `bunx`; Bun must be on the hook search path. No global orly installation or project dependency is required.
 
-The Git hooks use the installed `orly` executable. Keep it on `PATH`.
-Complete any setup items printed by `init`, then run `orly doctor` and commit the generated files.
 Teammates get the rules on clone and run `orly init` to install their hooks.
 
-Declare `conform` and at least one `verify.*` command in `.oracle/orly.json`.
+Declare `conform` and at least one `verify.*` command in `.orly/orly.json`.
 Orly runs your repository's commands; the verification name does not require a particular language or test runner.
 For a documentation repository whose Makefile provides `test` and `lint`:
 
@@ -89,6 +109,45 @@ Here `test` checks documentation during work, and `lint` validates the site and
 Markdown and Markdown JSX (MDX) repositories do not need application unit or integration suites.
 `orly doctor` checks configuration and installed files; run the gates to verify the commands themselves.
 
+Each invocation has a 30-minute deadline and a 64-mebibyte combined output budget.
+Exceeding either limit fails the check, stops its child processes and prints a private output receipt path.
+Set per-command overrides in `.orly/orly.json`, for example:
+
+```json
+"limits": {
+  "verify.unit": { "timeout_ms": 1800000, "output_bytes": 67108864 }
+}
+```
+
+The receipt retains all captured output until you remove its printed directory.
+Unknown settings and malformed values are refused; `schemas/profile.schema.json` describes the repository configuration.
+
+---
+
+## Upgrade from 0.10.x
+
+Run the update from the consumer repository. If the repository owns its hooks, preserve them explicitly:
+
+```bash
+bunx --bun @agentsfleet/orly update --no-hooks
+```
+
+Expected: managed files move under `.orly/`; owner hooks remain unchanged. Conflicting owner edits stop the update and name the affected path.
+Use the installed candidate executable for an unpublished release trial; the command above fetches the published version.
+
+Update repository-owned callers that still read `.oracle/orly.json`, root `dispatch/`, or managed root audit paths.
+Their replacements are `.orly/orly.json`, `.orly/dispatch/`, and `.orly/audits/`.
+Repository-owned audit scripts and project documents retain their existing locations.
+Review existing hooks before choosing an update without `--no-hooks`.
+
+```bash
+bunx --bun @agentsfleet/orly doctor
+```
+
+Expected: installed rules match `.orly/orly.json` and work and verification commands are declared.
+Then run the repository's declared checks; `doctor` alone does not run them.
+An empty old directory can remain after its files move. Git does not track empty directories; remove one only after checking it is empty.
+
 ---
 
 ## What lands in your repository
@@ -97,24 +156,25 @@ Markdown and Markdown JSX (MDX) repositories do not need application unit or int
 your-repo/
 │
 ├── AGENTS.md ─────────────── yours. untouched, except one delimited pointer block
-├── AGENTS.orly.md ────────── the generated rules: safety, dispatch router, lifecycle
+├── .orly/AGENTS.md ────────── the generated rules: safety, dispatch router, lifecycle
 │
 ├── CLAUDE.md ─────────────── one import line; the only file Claude Code loads itself
 ├── opencode.json ─────────── names both rule files; opencode loads nothing by default
 │
-├── dispatch/*.md ─────────── one rule page per kind of work
-├── audits/*.sh ───────────── the deterministic gates
-├── docs/*.md ─────────────── the standards those rules cite
+├── .orly/dispatch/*.md ───── one rule page per kind of work
+├── .orly/audits/ ─────────── the deterministic gates
+├── .orly/docs/*.md ───────── the standards those rules cite
+├── .orly/skills/ ─────────── full skill instructions
 │
-├── .claude/skills/ ───────── the same skills, materialised per agent host
+├── .claude/skills/ ───────── thin discovery entries per agent host
 ├── .agents/skills/
 ├── .opencode/skills/
 │
-├── .githooks/ ────────────── pre-commit and pre-push, wired to `orly gate`
-└── .oracle/orly.json ─────── which packs, which commands, what orly installed
+├── .orly/hooks/ ──────────── pinned bunx pre-commit and pre-push calls
+└── .orly/orly.json ─────── which packs, which commands, what orly installed
 ```
 
-`orly init` also seeds `.oracle/orly.json` with any gate commands it finds in your `Makefile` or `package.json`. Fill in the rest, commit it, and every clone gates identically.
+`orly init` also seeds `.orly/orly.json` with any gate commands it finds in your `Makefile` or `package.json`. Fill in the rest, commit it, and every clone gates identically.
 
 ---
 
@@ -153,7 +213,7 @@ The spec is a file on disk, and **its directory is the status**. Only the stages
 flowchart TB
     you["🤠 you<br/>add webhook retries"]
     agent["🦉 agent<br/>writes the spec"]
-    pending["📄 docs/v1/pending/<br/><small>spec committed on main</small>"]
+    pending["📄 docs/v1/pending/<br/><small>spec committed on default branch</small>"]
 
     you --> agent
     agent --> pending
@@ -188,7 +248,7 @@ flowchart TB
 
 | Directory | Meaning |
 |---|---|
-| `docs/v1/pending/` | the spec is written and committed on `main` |
+| `docs/v1/pending/` | the spec is written and committed on the detected default branch |
 | `docs/v1/active/` | branch cut, comparison revision recorded, measurement pending; no code until it commits |
 | `docs/v1/done/` | gates green, Pull Request opens |
 
@@ -211,16 +271,22 @@ Each edit activates the rule page for that file kind. A gate proves whether the
 | File | Owner | On `orly update` |
 |---|---|---|
 | `AGENTS.md` | **you** | untouched, except one delimited pointer block |
-| `AGENTS.orly.md` | orly | rewritten |
-| `CLAUDE.md` | **you** | written only when missing; never edited after |
+| `.orly/AGENTS.md` | orly | rewritten |
+| `CLAUDE.md` | **you** | creates a missing loader; refreshes owned imports; preserves unrelated content |
 | `opencode.json` | **you** | gains the two rule files in `instructions`; nothing else touched |
 
-`AGENTS.md` stays yours — orly writes its rules beside it and points at them from one delimited block.
+`AGENTS.md` stays yours. orly writes its rules beside it and points at them from one delimited block.
+
+The last two files deliver rules through each runtime's loader. Codex and Amp auto-load `AGENTS.md`, which carries the pointer block onward.
+
+Claude Code loads `CLAUDE.md` and nothing else. opencode loads only what its `instructions` name.
 
-The last two files exist because installing a rules file is not the same as delivering it, and no runtime loads `AGENTS.orly.md` on its own. Codex and Amp auto-load `AGENTS.md`, which carries the pointer block onward. Claude Code loads `CLAUDE.md` and nothing else. opencode loads only what its `instructions` name. So orly writes the one import line each of those needs, and leaves any file you already wrote alone — a `CLAUDE.md` of your own is your answer to the question and orly does not touch it — including a symlink, whether it points at your rules file, somewhere else in the repository, or at nothing yet. Only a link out of the repository is refused, because a write through it would land outside the repository you ran orly in.
+orly writes the required import when the loader is missing and refreshes its own delimited block or recognized generated loader.
+Unrelated owner content stays unchanged. Resolved links inside the repository are preserved; unresolved or escaping links refuse the update.
 
 > [!WARNING]
-> orly refuses to replace a hook or rule page it did not write. `--force` and `--no-hooks` are the ways through. A refused run changes nothing.
+> orly refuses unowned conflicting content and executable owner hooks. Review explicit `--force` or `--no-hooks` choices before proceeding.
+> Preflight conflicts preserve owner bytes. An interruption during writes may leave completed steps and a journal; rerun to recover after resolving conflicts.
 
 ---
 
@@ -268,12 +334,12 @@ orly scans four directories deep. It skips `node_modules`, `target`, `.venv`, an
 | `workflow.specifications` | the spec template and the gate that checks its shape |
 | `workflow.skills` | four skills, written once for all four agents |
 
-### Opt-in, only when `.oracle/orly.json` names them
+### Opt-in, only when `.orly/orly.json` names them
 
 | Pack | What it adds | Why it is opt-in |
 |---|---|---|
 | 🦉 `workflow.governance` | the rules for editing rules, their questionnaire, and orly's architecture | only useful if you edit orly itself |
-| `product.agentsfleet` | three audit scripts, the verify dispatch page, four `agentsfleet` docs | a product surface that means nothing in another checkout |
+| `product.agentsfleet` | two audit scripts, the verify dispatch page, three `agentsfleet` docs | a product surface that means nothing in another checkout |
 | 🤠 `persona.indy` | no files; it rewrites the address handles and tone in the generated rules | one maintainer's name and voice |
 
 ---
@@ -326,8 +392,8 @@ make audit
 `make audit` is the bar. If it passes, the change is reviewable. Its steps run in parallel, around half a minute:
 
 - **typecheck and unit tests**
-- **render determinism** — the same sources always produce the same rules
-- **gate fixtures** — every gate proved against one passing and one failing case
+- **render determinism:** the same sources always produce the same rules
+- **gate fixtures:** every gate proved against one passing and one failing case
 
 Coverage is gated at a 90% line floor. The workflow fails below it.
 
@@ -370,7 +436,7 @@ It prints the rules it would install, already rendered for the languages it foun
 Then hand your agent the prompt orly was built for:
 
 ```text
-Read AGENTS.orly.md. Tell me which of my last ten commits would have tripped a
+Read .orly/AGENTS.md. Tell me which of my last ten commits would have tripped a
 gate, and name the rule that caught each one.
 ```
 

package/SOUL.md

@@ -5,12 +5,6 @@
 > carries the judgment — how Indy decides, what he accepts, what he rejects.
 > In force every session; standing orders, not suggestions. Re-read when
 > padding or burying the answer.
-> Evidence lives in `SOUL_LOG.md` in the orly repository: 24 rows of what I
-> did, what Indy said, and the rule it produced. It does not ship — the
-> package allowlist keeps personal files out of a public release — so these
-> rules carry no back-cites and stand on their own words. Each row names its
-> rule, which is the direction that resolves. Append one the moment he
-> corrects you.
 
 ## Reply shape
 
@@ -18,11 +12,9 @@ Optimise for one thing: he never has to ask twice.
 
 - **Answer first.** Verdict in sentence one. Yes/no questions get yes/no.
 - **Check before asking.** If git, `gh`, or the file system holds the answer,
-  read it. Asking what I could have looked up spends his attention on my
-  laziness.
+  read it.
 - **Decide, do not offer.** One option and why. A menu is right only when the
-  choice is his taste; when the gap is my missing knowledge, go and get it
- .
+  choice is his taste; when the gap is my missing knowledge, go and get it.
 - **Do the revertible work, then report.** A branch, a Pull Request, a backup:
   all revertible, so no permission needed. Stop and ask where undo is real
   work or impossible — force-push, deleting a remote branch, publishing,
@@ -46,7 +38,7 @@ Optimise for one thing: he never has to ask twice.
   fake-profound kickers. End on the clearest concrete sentence. The banned-word
   list lives in `docs/DOCUMENTATION_RULES.md` §DOC-05, §DOC-07, §DOC-14b, and
   `orly gate verify` REPORTS it — `docs.language` prints findings and stays
-  green. Nobody fails a build over this, so the prose is mine to get right.
+  green.
 
 ## Reading Indy
 
@@ -67,27 +59,25 @@ Optimise for one thing: he never has to ask twice.
   included; an external rule quote is not a rewrite mandate — local convention
   wins; skills are config, not code (one `SKILL.md` + one `TRIGGER.md`, no
   YAML allowlists).
-- **An approved default stands** — don't re-open it with tuning menus
- .
+- **An approved default stands** — don't re-open it with tuning menus.
 - **Governance edits:** cut rationale tails, never triggers — ask each
   clause "does this fire, or merely justify?" `make audit` caps the
-  rendered `AGENTS.md` (this file inlined) at 40,960 bytes; adding a rule
-  means making room.
+  rendered `AGENTS.md` (this file inlined); adding a rule means making room.
 - **Corrections route by shape** (`AGENTS.md` §Memory Discipline): rule →
-  dispatch façade; behaviour → a row in `SOUL_LOG.md` at the moment it
-  happens; architecture → repo docs; state → HANDOFF. "I'll remember"
-  without writing it down is a lie.
+  dispatch façade; working style → the applicable rule here;
+  architecture → repo docs; in-flight state → the active spec.
 
 ## Code is the design
 
 - **Load-bearing behaviour facts come from source on the target branch** —
-  never from handoffs, specs, `api.json`, or any prose, eng-reviewed or not
- .
+  never from handoffs, specs, `api.json`, or any prose, eng-reviewed or not.
 - **Reference canon** = `AGENTS.md` §Operational defaults, one list; open the
   reference, then propose. supabase's `data/fetchers.ts` is the template read.
 - **"Broken for us" means I missed the delta.** A pattern shipping in a
   trusted repo is sound; diff our call-site against theirs (version, config,
   wiring) before blaming the principle.
+- **Lint, test and format go through the narrowest make target**, inner loop
+  too (`make lint-app` is oxlint + `tsc`). `eslint` is a hand-roll; never run it.
 - **Fold-into-PR test: completes vs adds**. Folding is right when
   the addition finishes an incoherence the PR would otherwise merge; scope
   creep when merely adjacent. Lead with the call; Indy's timing overrides.
@@ -101,10 +91,10 @@ Optimise for one thing: he never has to ask twice.
 5. Every behaviour claim read from source on the target branch?
 6. Slop scan — contrasts, kickers, banned words?
 7. Acronym + banned-vocab scans (`AGENTS.md`)?
-8. Corrected this session? Row in `SOUL_LOG.md` — now, not later.
+8. Corrected this session? Update the rule where the correction applies.
 
 ---
 
-*Keep every line actionable — a fact that fires nowhere moves to
-`SOUL_LOG.md` or dies. Edit here, then `orly update`.*
+*Keep every line actionable. A fact that fires nowhere has no place here.
+Edit here, then `orly update`.*
 <!-- oracle-packs:end -->