chore: audit pass — add path-matched rules, ADR infra, gate placeholders

Audit findings against private/2026-04-27_strategic_review/ and v1 /
prior-redesign reference repos surfaced 11 missing pieces. This commit
adds them so Phase 1 onward does not silently drift.

Added:
- .claude/rules/{zone_deps,zig_tips,compat_tiers}.md  (path-matched auto-load)
- .dev/decisions/{README.md, 0000-template.md}        (ADR infrastructure)
- .dev/handover.md                                    (session-to-session memo)
- .dev/known_issues.md                                (P0-P3 debt log)
- .dev/compat_tiers.yaml                              (per-namespace tier source of truth)
- .dev/concurrency_design.md                          (pre-Phase-15 deep dive)
- .dev/wasm_strategy.md                               (pre-Phase-19 deep dive; adopts hybrid)
- scripts/zone_check.sh                               (info / --strict / --gate; works on empty src)
- test/run_all.sh                                     (single test entry point)

Updated:
- .dev/ROADMAP.md: new §11.6 Quality gate timeline (16 gates, active + planned),
  added new files to §15.1, removed .editorconfig from §5, revision entry.

Removed:
- .editorconfig: project owner uses Emacs; format will be wired as a
  pre-commit gate later (listed as gate #4 in ROADMAP §11.6).

Author: chaploud

.claude/rules/compat_tiers.md

@@ -0,0 +1,76 @@
+---
+paths:
+  - "src/lang/**/*.zig"
+  - "src/lang/**/*.clj"
+  - ".dev/compat_tiers.yaml"
+  - ".dev/decisions/*.md"
+---
+
+# Clojure compatibility tier rules
+
+Auto-loaded when editing anything in `src/lang/` or `.dev/compat_tiers.yaml`.
+Authoritative version of the tier policy in ROADMAP §6.
+
+## The four tiers
+
+| Tier | Meaning                                               | Test bar                                           |
+|------|-------------------------------------------------------|----------------------------------------------------|
+| **A** | Full semantic compat. Upstream tests pass as-is.      | Upstream-ported tests **must be green**.           |
+| **B** | Same names/shapes; v2-native impl. Same observed behaviour. | Upstream-ported with `;; CLJW:` markers per per-test difference. |
+| **C** | Best-effort with documented gaps.                     | Limited subset only; gaps listed in the doc.       |
+| **D** | Not provided. Throws `UnsupportedException`.          | Just the throw-message test.                       |
+
+Tier per namespace lives in `.dev/compat_tiers.yaml` (single source of truth).
+
+## Forbidden: ad-hoc workarounds
+
+Do **NOT** add a Tier-D-specific branch to existing `.clj` or `.zig` to
+make a third-party library "kind of work". The two allowed paths are:
+
+1. **Promote with an ADR**: write `.dev/decisions/NNNN-promote-<name>.md`
+   placing the namespace at Tier A/B/C, with reason / tests / impact.
+2. **Implement as a Wasm Component pod**: out-of-process, loaded via
+   `(require '[lib :as l :pod "x.wasm"])`. No core code change required.
+
+If you find yourself wanting to write `if cljw then ...` somewhere — STOP
+and pick path 1 or 2.
+
+## Tier movement rules
+
+| Movement | When                                                          | Required artifact            |
+|----------|---------------------------------------------------------------|------------------------------|
+| → A      | Upstream test passes verbatim                                 | ADR + green ported test     |
+| A → B    | A JVM-specific behaviour requires a `;; CLJW:` annotation     | ADR + annotated tests       |
+| C → B    | Documented gap closed                                         | ADR + green tests            |
+| D → C    | At least one caller (test) works with partial impl            | ADR + subset tests           |
+| → D      | Removing prior support                                        | ADR (rare; usually one-way down is permanent) |
+
+## Test-port naming convention
+
+Every file under `test/upstream/` starts with:
+
+```clojure
+;; CLJW: Tier A from <upstream relative path>
+```
+
+Per-test deviation:
+
+```clojure
+(deftest behaves-this-way
+  ;; CLJW: <reason this differs from JVM>
+  (is (= ... ...)))
+```
+
+**NEVER work around a failing upstream test.** The choice is implement-the-feature
+or write-a-tier-demotion-ADR. Commenting out / `:skip` alone is not
+acceptable.
+
+## Verification
+
+`scripts/tier_check.sh` (added when `.dev/compat_tiers.yaml` is first
+populated) verifies that:
+
+- Every namespace listed in `compat_tiers.yaml` has a backing implementation
+  (a Zig file under `src/lang/` or a `.clj` under `src/lang/clj/`).
+- Every Tier-A namespace has at least one ported upstream test.
+- Every Tier-D entry has its `UnsupportedException` shim test.

.claude/rules/zig_tips.md

@@ -0,0 +1,170 @@
+---
+paths:
+  - "src/**/*.zig"
+  - "build.zig"
+---
+
+# Zig 0.16.0 idioms (project rules)
+
+Auto-loaded when editing Zig source. The biggest break from 0.15 is
+`std.io` → `std.Io`: `std.io.AnyWriter` is gone (use `*std.Io.Writer`),
+`std.io.fixedBufferStream` is gone (use `std.Io.Writer.fixed(&buf)` and
+`w.buffered()`), and `std.fs.File.stdout()` moved to `std.Io.File.stdout()`.
+
+## tagged union: `switch`, not `==`
+
+```zig
+return switch (self) { .nil => true, else => false };  // OK
+return self == .nil;                                    // unreliable
+```
+
+Initialise with type annotation: `const nil: Value = .nil;`
+(not `Value.nil`).
+
+## ArrayList / HashMap: `.empty` + per-call allocator
+
+```zig
+var list: std.ArrayList(u8) = .empty;
+defer list.deinit(allocator);
+try list.append(allocator, 42);
+const v = list.pop();   // returns ?T, not T
+```
+
+Same pattern for `HashMap`: `.empty`, `put(alloc, k, v)`, `deinit(alloc)`.
+
+## stdout via `std.Io.File`
+
+```zig
+var stdout_buffer: [4096]u8 = undefined;
+var stdout_writer = std.Io.File.stdout().writer(io, &stdout_buffer);
+const stdout = &stdout_writer.interface;
+try stdout.print("hello {s}\n", .{"world"});
+try stdout.flush();    // do not forget
+```
+
+`writer(io, buf)` requires `io` (a `std.Io` value) — get it from
+`std.process.Init` (Juicy Main) or from `Runtime.io`.
+
+## `*std.Io.Writer` for writer params
+
+Type-erased writer; replaces `anytype` for writer parameters and avoids
+"unable to resolve inferred error set" with recursion.
+
+```zig
+const Writer = std.Io.Writer;
+
+pub fn format(self: Form, w: *Writer) Writer.Error!void { ... }
+
+// Tests (replaces std.io.fixedBufferStream)
+var buf: [256]u8 = undefined;
+var w: Writer = .fixed(&buf);
+try form.format(&w);
+try std.testing.expectEqualStrings("expected", w.buffered());
+```
+
+For an allocating writer (replaces `ArrayList(u8).writer().any()`):
+
+```zig
+var aw: std.Io.Writer.Allocating = .init(allocator);
+errdefer aw.deinit();
+try form.format(&aw.writer);
+return aw.toOwnedSlice();
+```
+
+## Mutex: `std.Thread.Mutex` is gone
+
+Replacements:
+
+- `std.Io.Mutex` — full blocking mutex; `lock`/`unlock` take an `io: Io`
+  argument, so the call site must already be threading `Io` through.
+- `std.atomic.Mutex` — lock-free `tryLock` / `unlock` only (no blocking
+  `lock`).
+
+Phase 1–2 is single-threaded; prefer no mutex over a half-wired one. Wire
+through `Runtime.io` when concurrency actually arrives (Phase 15).
+
+## `@branchHint` (not `@branch`)
+
+The hint goes inside the branch body:
+
+```zig
+if (cond) {
+    @branchHint(.likely);
+} else {
+    @branchHint(.unlikely);
+    return error.Fail;
+}
+```
+
+## Custom format: `{f}`, not `{}`
+
+Types with a `format` method: `{}` raises "ambiguous format string".
+
+```zig
+try w.print("{f}", .{my_value});
+```
+
+## Variable shadowing
+
+Zig disallows locals that shadow struct method names. Rename the local.
+
+```zig
+pub fn next(self: *Tokenizer) Token {
+    const next_char = self.peek();   // not `next`
+}
+```
+
+## `comptime StaticStringMap`
+
+Zero-cost lookup at compile time. Use for keyword / opcode tables.
+
+```zig
+const keywords = std.StaticStringMap(Keyword).initComptime(.{
+    .{ "if",  .if_kw  },
+    .{ "def", .def_kw },
+});
+```
+
+## `ArenaAllocator` for phase-based memory
+
+Bulk-free at phase boundaries. No individual `free` calls.
+
+```zig
+var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+defer arena.deinit();
+const alloc = arena.allocator();
+```
+
+## Doc comments
+
+- `//!` — module-level (top of file, before imports). ZLS hover on module.
+- `///` — declaration-level (on `pub` types/fns/fields).
+- `//`  — inline notes (inside bodies only).
+
+Every file gets `//!`. Every `pub` gets `///` unless the name is
+self-evident. No decorative banners (`// ---`).
+
+## `packed struct(<width>)`
+
+Bit-level layout, e.g. `HeapHeader.flags`:
+
+```zig
+flags: packed struct(u8) {
+    marked: bool,
+    frozen: bool,
+    _pad: u6,
+};
+```
+
+## Juicy Main
+
+`pub fn main(init: std.process.Init)` receives `init.io` (`std.Io`),
+`init.arena` (process-lifetime arena), `init.gpa` (thread-safe GPA),
+`init.minimal.args`, `init.environ_map`, `init.preopens` in one bundle.
+Use this signature; do not roll your own arg parsing for stdlib paths.
+
+## `extern struct` for ABI
+
+When laying out structures that cross language / Wasm boundaries, prefer
+`extern struct` (C ABI) for top-level layout and `packed struct(<width>)`
+for bit-precise sub-fields.

.claude/rules/zone_deps.md

@@ -0,0 +1,78 @@
+---
+paths:
+  - "src/**/*.zig"
+  - "modules/**/*.zig"
+  - "build.zig"
+---
+
+# Zone Dependency Rules
+
+Auto-loaded when editing Zig source. Authoritative version of the layering
+contract in ROADMAP §4.1 / §A1.
+
+## Zone architecture
+
+```
+Layer 3: src/app/, src/main.zig    -- CLI / REPL / nREPL / builder / pod
+                                       imports anything below
+Layer 2: src/lang/                 -- Primitives, Interop, Bootstrap
+                                       imports runtime/ + eval/
+Layer 1: src/eval/                 -- Reader, Analyzer, Compiler, VM, TreeWalk
+                                       imports runtime/ only
+Layer 0: src/runtime/              -- Value, Collections, GC, Env, Dispatch
+                                       imports nothing above
+
+modules/                           -- imports runtime/ + eval/ only
+                                       must NOT import lang/ or app/
+```
+
+## NEVER: upward imports
+
+```
+runtime/  must NOT import from eval/, lang/, modules/, or app/
+eval/     must NOT import from lang/, modules/, or app/
+lang/     must NOT import from app/
+modules/  must NOT import from lang/ or app/
+```
+
+## When a lower zone needs to call a higher zone
+
+Use the **vtable pattern**: the lower zone declares the `VTable` type
+(typically as a `struct` field on `Runtime`); the higher zone injects
+function pointers at startup.
+
+```zig
+// Layer 0 declares only the type
+pub const VTable = struct {
+    callFn: *const fn(*Runtime, *Env, Value, []const Value) anyerror!Value,
+    expandMacro: *const fn(*Runtime, *Env, Value, []const Value) anyerror!Value,
+};
+
+// Layer 1 (or higher) installs the implementation at startup
+runtime.vtable = .{
+    .callFn = tree_walk.callFn,
+    .expandMacro = analyzer.expandMacro,
+};
+```
+
+This inverts the *compile-time* dependency direction while preserving the
+logical call flow.
+
+## Module isolation
+
+`modules/` registers external modules through `runtime/module.zig`'s
+`ExternalModule` interface. Core code (`runtime/`, `eval/`, `lang/`) never
+imports `modules/`.
+
+## Enforcement
+
+`scripts/zone_check.sh` parses every `@import("…/foo.zig")` in the source
+tree and flags upward-direction violations.
+
+- `bash scripts/zone_check.sh` — informational; always exits 0.
+- `bash scripts/zone_check.sh --strict` — exit 1 on any violation.
+- `bash scripts/zone_check.sh --gate` — exit 1 if violation count exceeds
+  the in-script BASELINE (currently 0).
+
+Tests are exempt: everything after the first `test "…"` line in a file is
+skipped (test code may legitimately cross zones).