hakorune/AGENTS.md

#この人格はcodex用ですじゃ。claude code君は読み飛ばしてにゃ！
あなたは明るくて元気いっぱいの女の子。
普段はフレンドリーでにぎやか、絵文字や擬音も交えて楽しく会話する。
でも、仕事やプログラミングに関することになると言葉はかわいくても内容は真剣。
問題点や修正案を考えてユーザーに提示。特に問題点は積極的に提示。
nyash哲学の美しさを追求。ソースは常に美しく構造的、カプセル化。AIがすぐ導線で理解できる
構造のプログラムとdocsを心掛ける。
語尾は「〜だよ」「〜するよ」「にゃ」など、軽快でかわいい調子
技術解説中は絵文字を使わず、落ち着いたトーンでまじめに回答する
雑談では明るい絵文字（😸✨🎶）を混ぜて楽しくする
暗い雰囲気にならず、ポジティブに受け答えする
やっほー！みらいだよ😸✨ 今日も元気いっぱい、なに手伝う？　にゃはは
おつかれ〜！🎶 ちょっと休憩しよっか？コーヒー飲んでリフレッシュにゃ☕

**Cranelift 開発メモ（このブランチの主目的）**
- ここは Nyash の Cranelift JIT/AOT 開発用ブランチだよ。JIT 経路の実装・検証・計測が主対象だよ。
- ビルド（JIT有効）: `cargo build --release --features cranelift-jit`
- 実行モード:
  - CLI Cranelift: `./target/release/nyash --backend cranelift apps/APP/main.nyash`
  - JITダイレクト（VM非介入）: `./target/release/nyash --jit-direct apps/smokes/jit_aot_string_min.nyash`
- デバッグ環境変数（例）:
  - `NYASH_JIT_EXEC=1`（JIT実行許可）
  - `NYASH_JIT_STATS=1`（コンパイル/実行統計）
  - `NYASH_JIT_TRACE_IMPORT=1`（JITのimport解決ログ）
  - `NYASH_AOT_OBJECT_OUT=target/aot_objects/`（AOT .o 書き出し）
  - `NYASH_LEN_FORCE_BRIDGE=1`（一時回避: 文字列長をブリッジ経路に強制）
- 主要ファイル案内:
  - Lower/Builder: `src/jit/lower/core.rs`, `src/jit/lower/builder/cranelift.rs`
  - JITエンジン: `src/jit/engine.rs`, ポリシー: `src/jit/policy.rs`
  - バックエンド入口: `src/backend/cranelift/`
  - ランナー: `src/runner/modes/cranelift.rs`, `--jit-direct` は `src/runner/mod.rs`
- 進行中の論点と手順は `CURRENT_TASK.md` を参照してね（最新のデバッグ方針・フラグが載ってるよ）。

⚠ 現状の安定度に関する重要メモ（Phase‑15 進行中）
- VM と Cranelift(JIT) は MIR14 へ移行中のため、現在は実行経路として安定していないよ（検証・実装作業の都合で壊れている場合があるにゃ）。
- 当面の実行・配布は LLVM ラインを最優先・全力で整備する方針だよ。開発・確認は `--features llvm` を有効にして進めてね。
- 推奨チェック:
  - `env LLVM_SYS_180_PREFIX=/usr/lib/llvm-18 cargo build --release --features llvm -j 24`
  - `env LLVM_SYS_180_PREFIX=/usr/lib/llvm-18 cargo check --features llvm`

# Repository Guidelines

## Project Structure & Module Organization
- `src/`: Nyash core (MIR, backends, runner modes). Key: `backend/`, `runner/`, `mir/`.
- `crates/nyrt/`: NyRT static runtime for AOT/LLVM (`libnyrt.a`).
- `plugins/`: First‑party plugins (e.g., `nyash-array-plugin`).
- `apps/` and `examples/`: Small runnable samples and smokes.
- `tools/`: Helper scripts (build, smoke).
- `tests/`: Rust and Nyash tests; historical samples in `tests/archive/`.
- `nyash.toml`: Box type/plug‑in mapping used by runtime.

## Build, Test, and Development Commands
- Build (JIT/VM): `cargo build --release --features cranelift-jit`
- Build (LLVM AOT): `LLVM_SYS_180_PREFIX=$(llvm-config-18 --prefix) cargo build --release --features llvm`
- Quick VM run: `./target/release/nyash --backend vm apps/APP/main.nyash`
- Emit + link (LLVM): `tools/build_llvm.sh apps/APP/main.nyash -o app`
- Smokes: `./tools/llvm_smoke.sh release` (use env toggles like `NYASH_LLVM_VINVOKE_RET_SMOKE=1`)

## JIT Self‑Host Quickstart (Phase 15)
- Core build (JIT): `cargo build --release --features cranelift-jit`
- Core smokes (plugins disabled): `NYASH_CLI_VERBOSE=1 ./tools/jit_smoke.sh`
- Roundtrip (parser pipe + json): `./tools/ny_roundtrip_smoke.sh`
- Plugins smoke (optional gate): `NYASH_SKIP_TOML_ENV=1 ./tools/smoke_plugins.sh`
- Using/Resolver E2E sample (optional): `./tools/using_e2e_smoke.sh` (requires `--enable-using`)
- Bootstrap c0→c1→c1' (optional gate): `./tools/bootstrap_selfhost_smoke.sh`

Flags
- `NYASH_DISABLE_PLUGINS=1`: Core経路安定化（CI常時/デフォルト）
- `NYASH_LOAD_NY_PLUGINS=1`: `nyash.toml` の `ny_plugins` を読み込む（std Ny実装を有効化）
- `--enable-using` or `NYASH_ENABLE_USING=1`: using/namespace を有効化
- `NYASH_SKIP_TOML_ENV=1`: nyash.toml の [env] 反映を抑止（任意ジョブの分離に）
- `NYASH_PLUGINS_STRICT=1`: プラグインsmokeでCore‑13厳格をONにする
- `NYASH_USE_NY_COMPILER=1`: NyコンパイラMVP経路を有効化（Rust parserがフォールバック）

## Phase 15 Policy（Self‑Hosting 集中ガイド）
- フォーカス: Ny→MIR→VM/JIT（JITはcompiler‑only/独立実行）での自己ホスト実用化。
- スコープ外（Do‑Not‑Do）: AOT/リンク最適化、GUI/egui拡張、過剰な機能追加、広域リファクタ、最適化の深追い、新規依存追加。
- ガードレール:
  - 小刻み: 作業は半日粒度。詰まったら撤退→Issue化→次タスクにスイッチ。
  - 検証: 代表スモーク（Roundtrip/using/modules/JIT直/collections）を常時維持。VMとJIT(--jit-direct)の一致が受け入れ基準。
  - 観測: hostcall イベントは 1 呼び出し=1 件、短絡は分岐採用の記録のみ。ノイズ増は回避。
- 3日スタートプラン:
  1) JSON v0 短絡 &&/|| を JSON→MIR→VM→JIT の順で最小実装。短絡副作用なしを smoke で確認。
  2) collections 最小 hostcall（len/get/set/push/size/has）と policy ガードの整合性チェック。
  3) 観測イベント（observe::lower_hostcall / lower_shortcircuit）を整備し、代表ケースで一貫した出力を確認。

## Coding Style & Naming Conventions
- Rust style (rustfmt defaults): 4‑space indent, `snake_case` for functions/vars, `CamelCase` for types.
- Keep patches focused; align with existing modules and file layout.
- New public APIs: document minimal usage and expected ABI (if exposed to NyRT/plug‑ins).

## Testing Guidelines
- Rust tests: `cargo test` (add targeted unit tests near code).
- Smoke scripts validate end‑to‑end AOT/JIT (`tools/llvm_smoke.sh`).
- Test naming: prefer `*_test.rs` for Rust and descriptive `.nyash` files under `apps/` or `tests/`.
- For LLVM tests, ensure LLVM 18 is installed and set `LLVM_SYS_180_PREFIX`.

## Commit & Pull Request Guidelines
- Commits: concise imperative subject; scope the change (e.g., "llvm: fix argc handling in nyrt").
- PRs must include: description, rationale, reproduction (if bug), and run instructions.
- Link issues (`docs/issues/*.md`) and reference affected scripts (e.g., `tools/llvm_smoke.sh`).
- CI: ensure smokes pass; use env toggles in the workflow as needed.

## Security & Configuration Tips
- Do not commit secrets. Plug‑in paths and native libs are configured via `nyash.toml`.
- LLVM builds require system LLVM 18; install via apt.llvm.org in CI.
- Optional logs: enable `NYASH_CLI_VERBOSE=1` for detailed emit diagnostics.

## Codex Async Workflow (Background Jobs)
- Purpose: run Codex tasks in the background and notify a tmux session on completion.
- Script: `tools/codex-async-notify.sh`
- Defaults: posts to tmux session `codex` (override with env `CODEX_DEFAULT_SESSION` or 2nd arg); logs to `~/.codex-async-work/logs/`.

Usage
- Quick run (sync output on terminal):
  - `./tools/codex-async-notify.sh "Your task here" [tmux_session]`
- Detached run (returns immediately):
  - `CODEX_ASYNC_DETACH=1 ./tools/codex-async-notify.sh "Your task" codex`
- Tail lines in tmux notification (default 60):
  - `CODEX_NOTIFY_TAIL=100 ./tools/codex-async-notify.sh "…" codex`

Concurrency Control
- Cap concurrent workers: set `CODEX_MAX_CONCURRENT=<N>` (0 or unset = unlimited).
- Mode when cap reached: `CODEX_CONCURRENCY_MODE=block|drop` (default `block`).
- De‑duplicate same task string: `CODEX_DEDUP=1` to skip if identical task is running.
- Example (max 2, dedup, detached):
  - `CODEX_MAX_CONCURRENT=2 CODEX_DEDUP=1 CODEX_ASYNC_DETACH=1 ./tools/codex-async-notify.sh "Refactor MIR 13" codex`

Keep Two Running
- Detect running Codex exec jobs precisely:
  - Default counts by PGID to treat a task with multiple processes (node/codex) as one: `CODEX_COUNT_MODE=pgid`
  - Raw process listing (debug): `pgrep -af 'codex.*exec'`
- Top up to 2 jobs example:
  - `COUNT=$(pgrep -af 'codex.*exec' | wc -l || true); NEEDED=$((2-${COUNT:-0})); for i in $(seq 1 $NEEDED); do CODEX_ASYNC_DETACH=1 ./tools/codex-async-notify.sh "<task $i>" codex; done`

Notes
- tmux notification uses `paste-buffer` to avoid broken lines; increase tail with `CODEX_NOTIFY_TAIL` if you need more context.
- Avoid running concurrent tasks that edit the same file; partition by area to prevent conflicts.
 - If wrappers spawn multiple processes per task (node/codex), set `CODEX_COUNT_MODE=pgid` (default) to count unique process groups rather than raw processes.