runops 2.1.3__tar.gz → 2.2.0__tar.gz

{runops-2.1.3 → runops-2.2.0}/.agents/skills/sync-docs/SKILL.md

@@ -13,14 +13,15 @@ runops の挙動は複数の場所に書かれている。変更の種類から
 | `runops.toml` / `case.toml` の field | `SPEC.md` §4, §5 | `docs/reference.md`、`config.py` / `case.py` の既知 key 集合 |
 | manifest の field | `SPEC.md` §6.2 | `docs/reference.md` の manifest 表、`ops/migrate.py` の変換 |
 | adapter 契約・skill 同梱 | `SPEC.md` §8 | `docs/adapter.md`、`adapters/base.py` の docstring、`legacy_adapters/` |
-| エージェントの使い方・規則 | `src/runops/harness.py`（project の AGENTS.md block） | `src/runops/skills/*/SKILL.md`、README の依頼例 |
+| エージェントの使い方・規則 | `src/runops/harness.py`（project の AGENTS.md block） | `src/runops/skills/*/SKILL.md`、README の依頼例、`docs/guide.md` |
 | 実装中の判断で SPEC 本文と違う結論になった | `SPEC.md` 本文を直し、§14 に理由を 1 行追加 | — |
 
 ## 規則
 
 - README は利用者向けで、人が覚えるコマンドは `runo init` だけという前提で書く。それ以外は
   エージェントへの依頼例として書く。
-- `docs/` は `reference.md` と `adapter.md` の 2 本だけ。ページを増やす前に既存ページの節で収める。
+- `docs/` は `guide.md`（使い方）、`reference.md`（一覧）、`adapter.md`（package 作者向け）の 3 本だけ。
+  ページを増やす前に既存ページの節で収める。command や挙動を変えたら `guide.md` の頼み方と裏のコマンドも確認する。
 - project に展開する skill は各 60 行以内、AGENTS.md block は 120 行以内（テストあり）。
 - 経緯は書かない（commit message と SPEC §14 に残す）。現在の挙動だけを書く。
 

{runops-2.1.3 → runops-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runops
-Version: 2.1.3
+Version: 2.2.0
 Summary: Run ledger and Slurm job submission for HPC simulation projects
 Project-URL: Homepage, https://github.com/Nkzono99/runops
 Project-URL: Documentation, https://github.com/Nkzono99/runops/blob/main/docs/reference.md
@@ -79,6 +79,7 @@ runo init
 | v1 から移る | この project を runops v2 に移行して（`runo migrate-v1` を dry-run で確認してから） |
 
 投入、削除、整理、移行の前には、エージェントが対象と資源量を示して確認を取ります。
+場面ごとの流れは [使い方ガイド](https://github.com/Nkzono99/runops/blob/main/docs/guide.md) にあります。
 
 ## project の中身
 
@@ -116,6 +117,7 @@ run は ID が変わらないので、directory を移動してもエージェ
 
 ---
 
+[使い方ガイド](https://github.com/Nkzono99/runops/blob/main/docs/guide.md) ·
 [リファレンス](https://github.com/Nkzono99/runops/blob/main/docs/reference.md) ·
 [adapter ガイド](https://github.com/Nkzono99/runops/blob/main/docs/adapter.md) ·
 [SPEC](https://github.com/Nkzono99/runops/blob/main/SPEC.md) ·

{runops-2.1.3 → runops-2.2.0}/README.md

@@ -48,6 +48,7 @@ runo init
 | v1 から移る | この project を runops v2 に移行して（`runo migrate-v1` を dry-run で確認してから） |
 
 投入、削除、整理、移行の前には、エージェントが対象と資源量を示して確認を取ります。
+場面ごとの流れは [使い方ガイド](https://github.com/Nkzono99/runops/blob/main/docs/guide.md) にあります。
 
 ## project の中身
 
@@ -85,6 +86,7 @@ run は ID が変わらないので、directory を移動してもエージェ
 
 ---
 
+[使い方ガイド](https://github.com/Nkzono99/runops/blob/main/docs/guide.md) ·
 [リファレンス](https://github.com/Nkzono99/runops/blob/main/docs/reference.md) ·
 [adapter ガイド](https://github.com/Nkzono99/runops/blob/main/docs/adapter.md) ·
 [SPEC](https://github.com/Nkzono99/runops/blob/main/SPEC.md) ·

{runops-2.1.3 → runops-2.2.0}/SPEC.md

@@ -134,6 +134,8 @@ v1 で運用した 2 つの project（`project_dust_release`: BEACH、run 120、
     skills.lock            # 展開した skill の由来と version（§8.2）
     index.toml             # run id -> path cache（§7.2）
     id.lock                # run id 採番用 lock
+    run.lock               # manifest の読み直し・更新用 lock（submit / cancel / retry / sync）
+    last_run_id            # 最後に払い出した run id。削除後も同じ id を再利用しないため
     v1-backup/<stamp>/     # migrate-v1 が退避した v1 の設定と harness（§11）
     build/
       <sim>-<commit>/      # local_source の build cache（§4.1）
@@ -146,6 +148,11 @@ v1 で運用した 2 つの project（`project_dust_release`: BEACH、run 120、
   見つける（§7.2）。
 - 既定の配置先は `runs/<case_name>/`。`--dest` で上書きできる。`_` で始まる
   directory（`_scratch`、`_archive`）は runops が予約する。
+- run directory の中（自身と子孫）には run を置けない。`--dest` が既存 run の中なら拒否し、
+  `delete` は中に別の run があれば拒否する（§7.2 の走査は manifest のある directory で止まる）。
+- run id は `R<YYYYMMDD>-<NNNN>`。その日の既存 run と `.runops/last_run_id` の大きい方に 1 を足す。
+  run を削除しても番号は再利用しない（ログやノートに残った id が別の run を指さないように）。
+  `last_run_id` を失っても既存 run からの採番に戻るだけで、動作は壊れない。
 - run は同じ親 directory の `.<name>.staging` で組み立ててから rename で公開する。
   rename は `renameat2(RENAME_NOREPLACE)` を使い、filesystem が対応しない場合
   （KUDPC の Lustre は EINVAL を返す）は project lock 下で存在確認してから `rename` する。
@@ -227,7 +234,10 @@ label_max_length = 48             # run 名の自動ラベルの最大文字数
 
 - `local_source` の build は `runo new` / `runo submit` 時に executable が無ければ自動で行う。
   `runo build SIM [--force]` で明示的にも行える（command 数に含める）。
-- `source_repo` が dirty なら build dir 名に `-dirty` を付け、manifest の `git_dirty = true` を記録する。
+- build dir 名は `<sim>-<short_commit>[-dirty]-<digest>`。digest は `build_command` と、dirty なら
+  build にコピーする全ファイル（追跡済みと未追跡、ignore 以外）の内容の hash。未追跡ファイルの
+  内容や `build_command` を変えると別の build になる。コピー後に source が変わっていたら build を中止する。
+  dirty なら manifest に `git_dirty = true` を記録する。
 - build cache は `tidy` が `unused-build` として挙げる（どの非 archived run の manifest からも
   参照されない build dir）。
 
@@ -292,7 +302,7 @@ ntasks = 800
   submit/
     job.sh
     sbatch.log           # 投入時の stdout/stderr（追記）
-    exit.<job_id>        # job.sh が終了時に書く exit code と開始・終了時刻（TOML）
+    exit.<job_id>        # job.sh が終了時に書く exit code、開始・終了時刻、stage（TOML）
   work/                  # simulator の出力。cwd はここ
   analysis/
     summary.json         # runo summarize の出力
@@ -325,6 +335,7 @@ archived_at = ""
 case = "flat_surface"
 sweep = ""                        # sweep label。単発 run は空
 parent_run = ""                   # --from RUN で派生した場合の source
+case_input_hash = "sha256:..."    # 作成時の case の base 入力ファイルの hash
 created_by = "agent"              # "human" | "agent" | 任意文字列
 
 [simulator]
@@ -366,6 +377,7 @@ finished_at = ""
 slurm_state = "COMPLETED"
 exit_code = 0                     # exit record から
 exe_hash = "sha256:..."           # submit 時点の executable の hash
+elapsed = "15:42:10"              # sacct の Elapsed、無ければ exit record の開始・終了から
 
 [params]
 "tmgrid.nx" = 4000
@@ -418,12 +430,21 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 - `sync` は対象 run の job id をまとめて 1 回の `squeue --jobs=...` で問い合わせ、そこに無い
   job だけを 1 回の `sacct --jobs=...` で引く。`tidy` の `orphan-job` 判定も同じ。
   scheduler への問い合わせ回数は run 数に依存しない。
+  runops が対応づけていない Slurm 状態の job は状態を変えずに `last_slurm_state` だけ残し、
+  他の run の更新は続ける。
 - job.sh は program 終了時に `submit/exit.<job_id>`（`exit_code`、`started_at`、`finished_at`、
-  `hostname`）を書く。squeue にも sacct にも無い job は、この file があれば
+  `hostname`、`stage = "run"`）を書く。program より前の準備（`module load`、`export`、`cd`、venv、
+  `setup_commands`、`pre_commands`、adapter の `job_prelude`）は `set -e` で実行し、失敗したら
+  program を起動せずに終了して、その exit code と `stage = "setup"` を記録する。
+  `post_commands` の失敗は記録する exit code を変えない。squeue にも sacct にも無い job は、この file があれば
   `exit_code = 0` のとき adapter の判定（既定 completed）、それ以外は `failed` にする。
   file が無ければ adapter の判定に従い、`unknown` なら `failed`。
 - `submit` は manifest に記録された executable を hash し直し、attempt に `exe_hash` を残す。
   作成時の `[simulator].exe_hash` と違えば warning を出す（拒否しない）。
+- `new --from RUN` は case の base 入力ファイルが source の作成時（`[origin].case_input_hash`）から
+  変わっていれば warning を出す（拒否しない）。
+- `submit`、`cancel`、`retry`、`sync` は `.runops/run.lock` の中で manifest を読み直してから
+  状態を確認・更新する。同じ run を 2 回指定しても、複数の process から同時に投入しても sbatch は 1 回。
 - `new` / `sweep --apply` は `identity.input_hash` が既存 run と一致するとき warning を出す
   （同じ executable なら「結果は同一のはず」、違えば「executable が違う」）。作成は拒否しない。
 - `purged` state は廃止。`work/` の削除は `[storage].work_purged_at` で表す。
@@ -443,6 +464,8 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 - 一覧系 command は `--json` を持ち、agent が機械可読に読める。`new` と `sweep --apply` の
   `--json` は作成した run の同じ summary を返す。summary には `params`、`changed_keys`、
   `parent_run`、`exe_hash`、`input_hash` を含め、run 同士の比較に別 command を要らなくする。
+  walltime の根拠として `walltime`、最新 attempt の `elapsed`、`walltime_used`（elapsed / walltime）、
+  `slurm_state`（`TIMEOUT` など）も含める。
 - 破壊的 command（`cancel`、`delete`、`tidy --apply`、`archive`）は対象を表示して
   確認を取る。`-y/--yes` で省略。
 - exit code: 0 成功、1 対象 run の実行時エラー（例: sbatch 失敗）、2 使用方法・設定エラー。
@@ -463,12 +486,12 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 | `runo doctor [--json]` | `runops.toml` の妥当性、adapter の import 可否、executable の存在、`sbatch` の有無、skill の鮮度を検査 |
 | `runo update [--skills-only] [-y]` | adapter package を upgrade し、skill を再展開する |
 | `runo build SIM [--force]` | `local_source` simulator を `.runops/build/` に build する（§4.1） |
-| `runo context [--json]` | agent 向け現在地。project 名、simulator、active run 数、直近 run 5 件、scratch 期限切れ数、`LOG.md` 末尾 20 行 |
+| `runo context [--json]` | agent 向け現在地。project 名、simulator、active run 数、直近 run 5 件、scratch 期限切れ数、`LOG.md` 末尾 20 行。配置した runops skill が install 済みの runops より古ければ `runo update --skills-only` を促す warning |
 | `runo case new NAME --simulator SIM [--from CASE]` | case をスキャフォールド。adapter の `case_template()` を展開 |
 | `runo case list` | case 一覧 |
 | `runo new CASE [--why TEXT] [--label L] [--set k=v]... [--tag T]... [--scratch] [--dest DIR] [--submit] [--created-by WHO] [--json]` | 単発 run を作る |
 | `runo new --from RUN [--why] [--set k=v]... [--continue] [--submit]` | 既存 run の params から派生 run を作る。`--continue` は adapter が `extend_inputs()` を実装する場合のみ有効（§8.1） |
-| `runo sweep CASE --set k=v1,v2,... [--set ...] [--label L] [--why TEXT] [--apply] [--submit] [--limit N] [--json]` | 直積の候補を表示する。`--apply` で生成。`--submit` は `--apply` と同時のみ有効 |
+| `runo sweep CASE --set k=v1,v2,... [--set ...] [--names KEY=n1,n2,...]... [--label L] [--dest DIR] [--why TEXT] [--apply] [--submit] [--limit N] [--json]` | 直積の候補を表示する。`--apply` で生成。`--submit` は `--apply` と同時のみ有効 |
 | `runo submit RUN... [--partition P] [--qos Q] [--afterok JOBID] [-y]` | job.sh を生成して sbatch。`created` 以外は拒否 |
 | `runo submit --all [DIR] [-y]` | DIR 配下の `created` run をすべて投入。件数と概算 core-hours を表示して確認 |
 | `runo cancel RUN... [-y]` | scancel して sync |
@@ -480,6 +503,7 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 | `runo note RUN [TEXT] [--by WHO]` | TEXT があれば `[[notes]]` に追記、なければ notes と `notes.md` を表示 |
 | `runo pin RUN [--off] [--reason TEXT]` | `run.pinned` を切り替える。pinned は `list` に常に出て、`tidy` / `delete` の対象外 |
 | `runo summarize RUN... [--force]` | adapter の `summarize()` を呼び `analysis/summary.json` を書く。既存があれば `--force` なしではスキップ |
+| `runo mv RUN... [--dest DIR] [--label L] [--why TEXT]` | run を `runs/` 配下で改名・移動する。id、入力、履歴は変えない（§7.7） |
 | `runo archive RUN... [-y]` / `runo archive --older-than 90d [-y]` | `runs/_archive/<元の相対 path>` に移動して `archived` にする |
 | `runo restore RUN` | archive 前の場所に戻す。既に何かあれば拒否 |
 | `runo delete RUN... [-y]` | directory を削除。`created`/`failed`/`cancelled`/scratch のみ。`pinned` は拒否 |
@@ -514,6 +538,7 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 - `--older-than AGE`（例 `14d`）はその回だけ、上の 2 つの日数をどちらもこの値で置き換える。
 - `--purge-work RUN...` は指定 run の `work/` の中身を削除し `work_purged_at` を記録する。
   adapter が `keep_patterns()` を返す場合、一致するファイルは残す。`completed` 以外は拒否。
+  adapter を読み込めない（残すファイルを判定できない）ときは何も消さずにエラーにする。
 - `tidy` は receipt や tombstone を作らない。失敗したら error を出して止まる。
   部分実行された結果は各 run の manifest にそのまま残る（再実行で続きから処理できる）。
 
@@ -528,6 +553,22 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
   `sweep_label` 省略時は `sweep-<YYYYMMDD>-<NN>`。
 - label は changed_keys から自動生成する（`wc0.147_phiz45`）。長さ上限は `defaults.label_max_length`（既定 48 文字）。
   key の短縮 alias は case.toml の `[naming.aliases]` で指定できる（v1 と同じ）。
+- `--names KEY=n1,n2,...` は掃引する KEY の各値に短い名前を付け、label ではその key の
+  alias + 値の代わりに名前を使う（構造化した配列を 1 軸にしたとき `wh0`、`wh1` のようにする）。
+  名前の数は値の数と同じで、重複は不可。入力や params には何も足さない。
+- `--dest DIR` は sweep directory の親を変える（既定 `runs/<case>`）。系列で共通の条件を
+  `--label` に、各点の違いを label に置く命名を作れる。
+
+### 7.7 `mv` の規則
+
+- `runo mv RUN... --dest DIR` は run を DIR（`runs/` 配下、`_archive` と既存 run の外）へ移す。
+  `--label L` は directory 名の suffix と `run.label` を変える（1 run のときだけ。`''` で外す）。
+- run id、`input/`、`input_hash`、`[origin]`（case、sweep、parent_run）、notes、投入履歴は変えない。
+  `[path].run_dir` と index を更新し、移動元と `--why` を `[[notes]]` に追記する。
+- 対象は `created`、`completed`、`failed`、`cancelled`。`submitted` / `running` は拒否する
+  （Slurm が run directory の絶対 path を持つ）。`archived` は `restore` を使う。
+- 既存 path は上書きしない（`move_noreplace`）。`created` の run は job.sh を作り直す。
+- 手で `mv` しても run は id で見つかるが、`run.label` と `[path].run_dir` が古いまま残る。
 
 ---
 
@@ -837,7 +878,7 @@ src/runops/
 | 項目 | 目標 |
 |---|---|
 | `src/runops/` の行数（skill の md を除く） | 8,000 行以下 |
-| CLI command 数（`case new` / `case list` を含む。同じ command の option 違いは数えない） | 25 以下。§7.3 の表の distinct command は 23 |
+| CLI command 数（`case new` / `case list` を含む。同じ command の option 違いは数えない） | 25 以下。§7.3 の表の distinct command は 24 |
 | ユーザーが編集する TOML | `runops.toml`、`case.toml` の 2 種 |
 | runops が書く TOML | `manifest.toml`、`.runops/skills.lock`、`.runops/index.toml` の 3 種 |
 | 依存 | `typer`、`rich`、`tomli-w`、`tomlkit`、`jinja2`、`packaging`（`mcp` を外す） |
@@ -878,9 +919,10 @@ src/runops/
 
 ### 13.3 ドキュメント
 
-v2 の `docs/` は次の 3 ファイルだけにする。
+v2 の文書は次の 4 ファイルだけにする。
 
 - `README.md`: 導入と 5 分の tutorial
+- `docs/guide.md`: 場面ごとの使い方。エージェントへの頼み方と裏の `runo` コマンドを並べる
 - `docs/reference.md`: §4〜§7 を利用者向けに書き直したもの
 - `docs/adapter.md`: §8 を simulator package 作者向けに書き直したもの
 
@@ -898,6 +940,8 @@ v2 の `docs/` は次の 3 ファイルだけにする。
 | adapter の追加 hook | `configure(sim_config)`、`job_prelude(run_dir)` | generic の `command` 取得と、EMSES の `rm -f *_0000.h5` など v1 の setup command を表す |
 | launcher `kind = "none"` | MPI launcher を使わず program を直接実行 | OpenMP のみの BEACH run 用 |
 | `runo pin` | command を 1 つ追加（計 23 + `--version`） | `pinned` を立てる手段が本文に無かった |
+| `runo mv`、`sweep --names` / `--dest`（2026-10-20） | id を保つ改名・移動を command にする（計 24）。sweep の各点に短い名前を付け、親 directory を選べるようにする | 運用で、投入前に名前を短くするだけで 10 run を `new --from` で作り直し、id が 10 増えた（#110）。構造化配列を 1 軸にすると label に配列が展開された（#111）。未投入 run の入力編集は「入力は作成時に固定」を崩すので見送る |
+| walltime の根拠（2026-10-20） | attempt ごとに `elapsed` を記録し、`list` / `status` に `elapsed`、`walltime`、`walltime_used`、`slurm_state` を出す。表では TIMEOUT などを `failed (TIMEOUT)` と示す。似た run の選択と余裕の倍率は skill の指針に置き、runops は推奨値を出さない | 「似た run」の自動判定は外れたときの害が大きい。根拠の数値を見せ、判断はエージェントと人に任せる（#109） |
 | generic の `success_marker` | 既定は未設定（Slurm の状態に従う） | 既定 `COMPLETED` だと marker を書かない program が全て failed になる |
 | skill 名 | package の skill 名をそのまま使う | MPIEMSES3D の skill は既に `mpiemses3d-` で名前空間がある |
 | `new --from RUN` の入力 | case の base file に、source run の params と `--set` を適用 | generic の template と TOML override の両方で同じ結果になる |
@@ -912,3 +956,5 @@ v2 の `docs/` は次の 3 ファイルだけにする。
 | 同一入力の warning | `input_hash`（と `exe_hash`）が一致する既存 run を作成時に知らせる | §1.3 で観察した variation の重複を、ゲート無しで抑える |
 | 整理と命名のしきい値 | `[defaults]` に `tidy_failed_days`、`tidy_archive_days`、`label_max_length` を追加。completed の目安は「`--older-than` の 3 倍」をやめて独立の値に | project ごとに計算期間や命名が違い、エージェントに毎回 option を渡させると揃わない |
 | `runo init` の対話と site の推定 | 端末から引数なしで実行したときだけ site と simulator を尋ねる。site の既定はホスト名（`camphor*`、`laurel*`、`cinnamon*`、`gardenia*` なら `kudpc`）。プリセット名は `kudpc` とし、`camphor` も同じ意味で受け付ける | 人が打つのは `runo init` だけなので、ここで KUDPC 向けの設定を取り違えないようにする。エージェントや CI からの実行（端末でない、`-y`、引数あり）は従来どおり尋ねない |
+| 異常系と同時操作（2026-10-20） | `run.lock` 下で manifest を読み直す、準備の失敗で program を起動しない、adapter を読めなければ purge しない、build cache の key を内容と `build_command` から作る、run の入れ子を禁止、run id を再利用しない（`last_run_id`）、`new --from` で case の変更を警告 | 外部レビューで、二重投入で 1 回目の履歴が消える、準備失敗が completed になる、adapter の故障で保持ファイルが消える、未追跡ファイルの変更で古い binary を使う、削除した id が別の run を指す、を確認した |
+| 使い方ガイド | `docs/guide.md` を追加し、文書を 4 ファイルにする（§13.3） | README の依頼例の表と command 一覧の間を埋める、場面ごとの流れ（case と run の分け方、smoke から本計算、状態の決まり方、整理）の置き場所が無かった |

runops-2.2.0/docs/guide.md

@@ -0,0 +1,271 @@
+# runops 使い方ガイド
+
+runops で計算を進める流れを、場面ごとに説明します。人が打つコマンドは `runo init` だけで、
+ほかはエージェント（Codex や Claude Code）に頼みます。各節では頼み方の例と、その裏で
+エージェントが実行する `runo` コマンドを並べます。コマンドと設定の一覧は
+[リファレンス](reference.md) にあります。
+
+## 1. 始める
+
+```bash
+uv tool install runops
+mkdir lunar-sheath && cd lunar-sheath
+runo init
+```
+
+`runo init` は計算機の種類（site）と使う simulator を尋ねます。site はホスト名から推定するので、
+京大スパコンのログインノードなら Enter で進めます。終わると次のものができています。
+
+| できるもの | 役割 |
+|---|---|
+| `runops.toml` | site、simulator、launcher、整理のしきい値などの設定 |
+| `cases/`、`runs/` | 入力テンプレートと、実行した run の置き場所 |
+| `LOG.md`、`notes/` | 判断の記録と、再利用する知見の置き場所（[6 節](#6-記録を残す)） |
+| `.venv/` | simulator の Python package（adapter と skill を含む） |
+| `AGENTS.md`、`CLAUDE.md`、`.agents/skills/`、`.claude/skills/` | エージェント向けの規則と skill |
+
+この directory で Codex か Claude Code を起動し、調べたいことを話しかけてください。
+エージェントは `AGENTS.md` と skill を読んで `runo` を使います。最初の依頼の例です。
+
+> MPIEMSES3D で平板シースを計算したい。cookbook の例を元に case を作って。
+> gr20001a に 800 並列、120 時間で。
+
+## 2. case と run の分け方
+
+runops が扱う名詞は case、run、sweep の 3 つです。
+
+| 名詞 | 中身 | 置き場所 |
+|---|---|---|
+| case | 再利用する入力テンプレート。`case.toml` と base 入力ファイル | `cases/<name>/` |
+| run | 1 回の実行。入力を凍結し、状態を `manifest.toml` に持つ | `runs/<case>/<run_id>--<label>/` |
+| sweep | 1 つの case から値を振って run をまとめて作る操作 | `runs/<case>/<sweep_label>/` |
+
+**値を変えるだけなら case を増やさず、run で表します。** case を増やすのは、base 入力ファイルの
+構造（境界の種類、粒子種の数など）が変わるときだけです。値ごとに case を作ると、
+`flat_size_1x`、`flat_uv_off`、`flat_retry` のような case が増え、どれが何だったか追えなくなります。
+
+| やりたいこと | 頼み方の例 | 裏のコマンド |
+|---|---|---|
+| 1 つの値を変えて試す | flat で wc を 0.147 にして 1 本作って | `runo new flat --set plasma.wc=0.147 --why "..."` |
+| 前の run から少し変える | R20261015-0002 の nx だけ倍にして | `runo new --from R20261015-0002 --set tmgrid.nx=8000 --why "..."` |
+| 値を振る | wc を 0, 0.147, 0.294 で振って | `runo sweep flat --set plasma.wc=0,0.147,0.294 --why "..."` |
+| 構造が違う入力を作る | flat を元に、穴の空いた境界の case を作って | `runo case new hole --from flat` |
+
+`--set` の key は base 入力の dotted key です（`plasma.wc`、配列なら `species.0.wp`）。
+値は TOML のリテラルとして読まれます（`3`、`1.5e-6`、`true`、`[1, 2]`）。
+
+どの run にも `--why`（その run で確かめたいこと）が付きます。エージェントには、依頼の中で
+目的も伝えてください。後で `runo list` を見たとき、run を区別する手がかりになります。
+
+作った run の `manifest.toml` と `input/` は変更しません。入力を直したいときは新しい run を作ります。
+同じ入力の run が既にあると、作成時に警告が出ます。
+`new --from` は元の run の params を引き継ぎますが、入力ファイルは今の case から作ります。
+元の run を作った後に case の入力ファイルを直していると、作成時に警告が出ます。
+
+### 名前の付け方
+
+名前は、系列と主な条件を見分けるためのものです。全条件は manifest と `input/` にあります。
+系列で共通の条件は親 directory に、各点の違いは run の label に置きます。
+
+> 直径 5 m、10 eV、400 km/s、光電子ありで深さ比 wh を 0〜4 で振って。名前は短く。
+
+エージェントは `runo sweep ... --label d5m_T10eV_v400kms_pe --dest runs --names ptcond.boundaries=wh0,wh1,wh2,wh3,wh4`
+のように作り、`runs/d5m_T10eV_v400kms_pe/R…--wh2` になります。`--names` は、配列のような長い値を
+掃引するときに各値へ短い名前を付けます（入力には何も足しません）。
+
+作った後で名前や置き場所を変えたいときは「R…〜R… を runs/pe にまとめて」と頼めば
+`runo mv RUN... --dest runs/pe --why "..."` になります。`--label` で label も変えられます。
+run id、入力、sweep の帰属、ノートはそのままで、移動元はノートに残ります。
+投入中（submitted / running）の run は動かせません。
+
+## 3. 試してから本計算
+
+いきなり本計算を投げず、短い scratch run で動作を確かめてから投入する流れです。
+
+> 100 step だけ smoke で試して。通ったら wc を 3 通りに振った候補を見せて。
+
+エージェントは次の順に進めます。
+
+1. `runo new flat --scratch --set ... --why "smoke"` で scratch run を作って投入する。
+   scratch run は `runs/_scratch/` に置かれ、既定の `runo list` には出ません。
+   `scratch_ttl_days`（既定 7 日）を過ぎると `runo tidy` の削除候補になります。
+2. `runo sync` と `runo log RUN --err` で、起動直後に落ちていないか確かめる。
+3. `runo sweep flat --set plasma.wc=0,0.147,0.294 --why "..."` で候補を表示する。
+   この段階では何も作られません。表には候補ごとの値、label、合計の core-hours が出ます。
+4. あなたが確認したら、`runo sweep ... --apply --submit` で run を作って投入する。
+
+依頼の言葉が、エージェントに許す操作の範囲を決めます。
+
+| 依頼の言葉 | エージェントがしてよいこと |
+|---|---|
+| 「作って」 | run の作成まで。投入はしない |
+| 「流して」「投げて」 | 作成と投入 |
+| 「試して」 | 短い scratch run の作成と投入。本計算は投げない |
+
+投入、削除、整理、移行の前には、エージェントが対象の run、partition、資源量、core-hours を示して
+確認を取ります。`runo` 自体も、複数 run の投入や削除の前に確認を求めます。
+
+資源量（partition、walltime、並列数）は case の `[job]` に書きます。1 回だけ partition を
+変えるなら「今回は gr20001b で投げて」と頼めば `runo submit RUN --partition gr20001b` になります。
+
+walltime は、同じ case・同じ資源で終わった run の実時間を元に決めます。`runo list --json` と
+`runo status` は、各 run の `elapsed`（最新の実行の実時間）、`walltime`、使った割合を示します。
+エージェントは「R… が 15:42 で終わったので 1.3〜1.5 倍の 24 時間」のように根拠の run を挙げて提案し、
+似た run が無ければ見積もれないと伝えます。walltime 切れの run は `failed (TIMEOUT)` と表示されます。
+
+## 4. 様子を見る
+
+> 先週投げた run の状況を見て。失敗していたら原因をノートに残して。
+
+| コマンド | 内容 |
+|---|---|
+| `runo sync` | 投入済み・実行中の run の状態を Slurm から更新する |
+| `runo list` | 実行中、作成済み、直近 30 日、pin した run を表示する |
+| `runo status RUN` | 1 つの run の状態（Slurm には問い合わせない） |
+| `runo log RUN --err` | 最新 job の stderr の末尾 |
+| `runo summarize RUN` | adapter による結果の要約を `analysis/summary.json` に書く |
+
+`runo sync` は、active な run が何件あっても `squeue` と `sacct` を 1 回ずつしか呼びません。
+エージェントには `squeue` を直接叩かせず、`runo sync` を使わせてください。
+
+### 状態の決まり方
+
+run の状態は `created → submitted → running → completed | failed | cancelled` と進みます。
+`sync` は次の順で終わった run の状態を決めます。
+
+1. Slurm が状態を返す job はその状態に従う。Slurm が `COMPLETED` でも、adapter が出力を見て
+   失敗と判断すれば `failed` にする。
+2. Slurm の記録から消えた job は、job.sh が終了時に書く `submit/exit.<job_id>` を見る。
+   exit code が 0 なら adapter の判定、0 以外なら `failed`。`module load` や `pre_commands` などの
+   準備が失敗した job は program を起動せずに終わり、`failed` になる。
+3. その記録も無ければ adapter の判定に従い、判定できなければ `failed`。
+
+runops が知らない Slurm 状態の job は状態を変えず、`last_slurm_state` に状態名だけを残します。
+
+### 長い job の見守り
+
+本計算の投入は、Slurm が受け付けた時点で完了です。エージェントは job id を報告して止まります。
+見守ってほしいときは、そう頼んでください。
+
+> 投げたら、最初にちゃんと動き出したかだけ見て。
+
+エージェントは起動直後に 1 回確認し、その後は予定の終了時刻のあたりで確認します。
+`tail -f` や短い間隔での状態確認の繰り返しはしません。期限が来ても、エージェントが自分の判断で
+キャンセルや再投入をすることはありません。
+
+### 失敗したとき
+
+| 状況 | 頼み方の例 | 裏のコマンド |
+|---|---|---|
+| 原因を調べる | R20261016-0003 が落ちた理由を調べて | `runo log RUN --err`、`runo summarize RUN`、`runo note RUN "..."` |
+| 一時的な障害で、同じ入力で流し直す | 同じ入力でもう一度投げて | `runo retry RUN`、`runo submit RUN` |
+| 入力を直して流し直す | dt を半分にして作り直して | `runo new --from RUN --set ... --why "..."` |
+| 止める | R20261016-0004 を止めて | `runo cancel RUN` |
+
+`retry` は `failed` / `cancelled` の run を `created` に戻し、試行回数を 1 つ増やします。
+`work/` は消しません。
+
+## 5. 続きを流す
+
+> R20261015-0003 の続きを 2 倍の step で。
+
+`runo new --from RUN --continue` で、終わった run の出力から再開する run を作ります。
+再開の方法は simulator ごとに違い、adapter が対応している場合だけ使えます
+（現在は MPIEMSES3D が対応し、`SNAPSHOT1` から再開します）。新しい run は元の run を `parent_run` として記録します。
+
+前の job が終わるのを待って投入したいときは、「R20261016-0005 が成功したら投げて」と頼めば
+`runo submit RUN --afterok <job_id>` になります。
+
+## 6. 記録を残す
+
+記録の置き場所は 3 つに決まっています。
+
+| 何を | どこに | 頼み方の例 |
+|---|---|---|
+| 1 つの run についての観察 | `runo note RUN "..."`（manifest に日時付きで残る）か run の `notes.md` | この run は 3 万 step で電位が飽和した、とメモして |
+| 複数の run をまたぐ結論と次の判断 | `LOG.md` に日付見出しで追記 | 今日の scan の結論を LOG にまとめて |
+| 再利用する式、手法、落とし穴 | `notes/<topic>.md`（1 topic 1 file） | Debye 長の見積もり方を notes に残して |
+
+エージェントはこれ以外の場所（`research/`、`analysis/*.md`、`runs/` の下など）にノートを作りません。
+`notes/` に似た topic の file があれば、新しく作らずに追記します。
+
+`runo context` は `LOG.md` の末尾と `notes/` の file 名を表示します。エージェントは作業の始めに
+これを読むので、前回の続きから話を始められます。
+
+## 7. 整理する
+
+run は消さなくても `runo list` が古いものを隠しますが、directory とディスクは増えていきます。
+
+> 古い run を整理して。消すものと archive するものを先に見せて。
+
+`runo tidy` は候補を表示するだけで、何も変更しません。
+
+| 種類 | 条件 | 処理 |
+|---|---|---|
+| `expired-scratch` | 期限切れの scratch run | 削除 |
+| `stale-failed` | 30 日より古い failed / cancelled で、`why` もノートも無い | 削除 |
+| `old-completed` | 90 日より古い completed | archive |
+| `orphan-job` | 投入済みなのに Slurm が知らない | `sync` で状態を確定 |
+| `unused-build` | どの run も使っていない build cache | 削除 |
+
+候補を確認したら `runo tidy --apply` で実行します。archive は `runs/_archive/` への移動で、
+run id で引き続き見つかり、`runo restore` で戻せます。
+
+論文の図に使う run や基準にする run は pin しておくと、`list` に常に表示され、`tidy` や `delete`
+の対象になりません。
+
+> R20261015-0002 は図 3 の基準なので残しておいて。
+
+終わった run の出力が大きいときは、「R20261015-0002 の work を片付けて」と頼めば
+`runo tidy --purge-work RUN` で `work/` の中身を消します。adapter が指定するファイル
+（要約やログなど）は残ります。adapter を読み込めないときは、何も消さずにエラーになります。
+
+日数のしきい値は `runops.toml` の `[defaults]` にあります。「この project では failed は
+14 日で消していい」と頼めば、エージェントが書き換えます。
+
+## 8. simulator を足す、更新する
+
+| やりたいこと | 頼み方の例 | 裏のコマンド |
+|---|---|---|
+| 状態を点検する | runops の環境を点検して | `runo doctor` |
+| package の simulator を足す | BEACH も使えるようにして | `runops.toml` に追記、`runo update -y` |
+| 手元で改造した版を足す | ~/BEACH-dev をビルドして、別の simulator として登録して | `resolver_mode = "local_source"`、`runo build NAME` |
+| 自作プログラムを使う | ./run.sh を simulator として登録して | `adapter = "generic"`、`command = "./run.sh"` |
+| 更新する | runops と simulator を最新にして | `uv tool upgrade runops`、`runo update -y` |
+
+`runo update` は simulator package を更新し、package に同梱された skill を配置し直します。
+runops を更新した後、project の skill が古いままだと `runo context` が警告を出すので、「skill を更新して」と頼んでください。
+`AGENTS.md` は `<!-- runops:begin -->` から `<!-- runops:end -->` までだけを書き換えるので、
+その外に書いた project 固有の規則は残ります。
+
+`local_source` の simulator は、source の commit と `build_command`（dirty なら未追跡を含む
+ファイルの内容も）ごとに `.runops/build/<sim>-<commit>-<hash>/` へ build し、run の manifest に commit と executable の hash を記録します。後から「この run は
+どの版で計算したか」を確かめられます。
+
+simulator 用の adapter を自分で書く方法は [adapter ガイド](adapter.md) にあります。
+
+## 9. v1 の project から移る
+
+> この project を runops v2 に移行して。
+
+エージェントは先に `runo migrate-v1 --dry-run` で変換計画を見せます。確認すると変換を実行します。
+
+- v1 の設定と harness は `.runops/v1-backup/<日時>/` に退避され、削除はされません。
+- 各 run の v1 manifest は `manifest.v1.toml` として同じ directory に残ります。
+- `research/`、`materials/`、`refs/` は動かしません。場所は `notes/README.md` に追記されます。
+- run directory は移動しません。v1 の配置のまま `runo list --all` に表示されます。
+
+実運用中の project を移行するときは、先にコピーで試すよう頼むと安全です。
+
+## 10. よくあるつまずき
+
+- **KUDPC のログインノード**: `runo` の操作自体はログインノードで実行できます。simulator の
+  build や重い解析は計算ノードで行います。エージェントには KUDPC 用の plugin の規則に従わせてください。
+- **`runo` が project を見つけない**: `runo` は現在の directory から上に向かって `runops.toml` を
+  探します。project の外で実行すると exit code 2 で止まります。
+- **run directory を動かした**: `runs/` の下なら自由に移動して構いません。run id で見つかります。
+  `runs/` の外に出した run は扱えません。
+- **確認を求められて止まる**: 端末以外から `runo` を実行すると確認の入力ができないため、
+  `-y` が無い破壊的な操作はエラーになります。エージェントはあなたの確認を取ってから `-y` を付けます。
+- **skill が古い**: runops や simulator を更新した後は `runo doctor` が skill の更新を提案します。
+  「skill を更新して」と頼めば `runo update --skills-only` を実行します。

{runops-2.1.3 → runops-2.2.0}/docs/reference.md

@@ -58,7 +58,7 @@ label_max_length = 48             # run 名の自動ラベルの最大文字数
 |---|---|
 | `package` | `.venv/bin/<executable>`、無ければ PATH |
 | `local_executable` | 絶対 path、project 相対 path、PATH の順 |
-| `local_source` | `source_repo` の HEAD を `.runops/build/<sim>-<commit>/` にコピーし `build_command` を実行。dirty なら名前に `-dirty-<hash>` が付く |
+| `local_source` | `source_repo` の HEAD を `.runops/build/<sim>-<commit>-<hash>/` にコピーし `build_command` を実行。`<hash>` は `build_command` と、dirty なら未追跡を含む全ファイルの内容から作る（dirty なら `-dirty` も付く） |
 
 module は site、launcher、simulator、case の順に結合されます。`generic` adapter では
 `command`（`{executable}` を置換）と `success_marker`（`work/` 内の完了 marker）も使えます。
@@ -105,9 +105,9 @@ runops だけが書きます。手で編集しないでください。主な fie
 |---|---|
 | `[run]` | `id`、`label`、`status`、`created_at`、`why`、`scratch`、`expires_at`、`pinned`、`tags`、`status_before_archive` |
 | `[path]` | `run_dir`（project 相対）、`archived_from`、`archived_at` |
-| `[origin]` | `case`、`sweep`、`parent_run`、`created_by` |
+| `[origin]` | `case`、`sweep`、`parent_run`、`created_by`、`case_input_hash` |
 | `[simulator]` | `name`、`adapter`、`adapter_source`、`adapter_version`、`executable`、`resolver_mode`、`package_version`、`exe_hash`、`git_commit`、`git_dirty`、`build_dir` |
-| `[job]` | case の `[job]` に加え `job_id`、`attempt`、`submitted_at`、`finished_at`、`last_slurm_state`、`exit_code`、`[[job.attempts]]`（attempt ごとの `job_id`、`started_at`、`exit_code`、`exe_hash`） |
+| `[job]` | case の `[job]` に加え `job_id`、`attempt`、`submitted_at`、`finished_at`、`last_slurm_state`、`exit_code`、`[[job.attempts]]`（attempt ごとの `job_id`、`started_at`、`exit_code`、`exe_hash`、`elapsed`） |
 | `[params]` | case の params に `--set` を適用した最終値 |
 | `[variation]` | `changed_keys` |
 | `[identity]` | `input_hash` |
@@ -116,17 +116,29 @@ runops だけが書きます。手で編集しないでください。主な fie
 
 状態は `created → submitted → running → completed | failed | cancelled` と進み、
 終了した run は `archived` にできます。`sync` は Slurm が COMPLETED でも adapter が
-失敗と判定すれば `failed` にします。job.sh は終了時に `submit/exit.<job_id>`（exit code と
-開始・終了時刻）を書くので、Slurm の会計から消えた job もこの file で completed / failed が
-決まります。`sync` と `tidy` は対象 run の job id をまとめて 1 回の `squeue` と `sacct` で
-問い合わせます。
+失敗と判定すれば `failed` にします。job.sh は終了時に `submit/exit.<job_id>`（exit code、
+開始・終了時刻、`stage`）を書くので、Slurm の会計から消えた job もこの file で completed / failed が
+決まります。`module load`、`cd`、`setup_commands`、`pre_commands` などの準備が失敗すると、job.sh は
+program を起動せずに終わり、`stage = "setup"` と exit code を記録します。
+`sync` と `tidy` は対象 run の job id をまとめて 1 回の `squeue` と `sacct` で
+問い合わせます。runops が知らない Slurm 状態の job は状態を変えず、
+`last_slurm_state` にその状態だけを記録します。
 
 `submit` は executable を hash し直して attempt に記録し、作成時と違えば警告します。
 `new` と `sweep --apply` は同じ入力（`input_hash`）の run が既にあれば警告します。
-どちらも作成や投入は拒否しません。
+`new --from RUN` は、元の run を作った後に case の入力ファイルが変わっていれば警告します
+（入力は今の case から作るため）。どれも作成や投入は拒否しません。
+
+`submit`、`cancel`、`retry`、`sync` は lock の中で manifest を読み直してから更新します。
+同じ run を 2 回指定しても、複数のエージェントが同時に投入しても sbatch は 1 回です。
+run id は削除後も再利用しません。`--dest` に既存 run の中は指定できません。
 
 ## command
 
+`list --json` と `status --json` は、walltime の根拠として `walltime`、最新 attempt の `elapsed`、
+`walltime_used`（elapsed / walltime）、`slurm_state` も返します。表では `TIMEOUT` などを
+`failed (TIMEOUT)` と示します。
+
 全 command は `--help` で option を確認できます。`RUN` には run id、run directory、
 または directory 名の一意な部分文字列を渡せます。
 
@@ -140,13 +152,14 @@ runops だけが書きます。手で編集しないでください。主な fie
 | `runo case new NAME [-s SIM] [--from CASE]` / `runo case list` | case の作成と一覧 |
 | `runo new CASE [--why] [--label] [--set k=v]... [--tag] [--scratch] [--dest DIR] [--submit] [--json]` | run を 1 つ作る |
 | `runo new --from RUN [--set k=v]... [--continue]` | 既存 run の params から派生。`--continue` は adapter の restart 対応が必要 |
-| `runo sweep CASE --set k=v1,v2 ... [--label] [--limit N] [--apply] [--submit] [--json]` | 直積の候補表示。`--apply` で作成 |
+| `runo sweep CASE --set k=v1,v2 ... [--names k=n1,n2...] [--label] [--dest DIR] [--limit N] [--apply] [--submit] [--json]` | 直積の候補表示。`--apply` で作成。`--names` は各値の短い label、`--dest` は sweep directory の親 |
 | `runo submit RUN... [-p P] [--qos Q] [--afterok JOB]` / `runo submit --all [DIR] [-y]` | job.sh を生成して sbatch |
 | `runo cancel RUN... [-y]` / `runo retry RUN [--submit]` | scancel / failed・cancelled を created に戻す |
 | `runo status [RUN...]` / `runo sync [RUN...]` / `runo log RUN [--err] [-n N] [-f]` | 状態表示 / Slurm から更新 / log 表示 |
 | `runo list [PATH] [--all] [--since 30d] [--case] [--sweep] [--status] [--tag] [--scratch] [--archived] [--json]` | run 一覧 |
 | `runo note RUN [TEXT]` / `runo pin RUN [--off] [--reason]` | ノート追記・表示 / pin |
 | `runo summarize RUN... [--force]` | adapter の要約を `analysis/summary.json` に書く |
+| `runo mv RUN... [--dest DIR] [--label L] [--why TEXT]` | `runs/` 配下で改名・移動。id、入力、sweep、ノートは保つ。submitted / running と archived は不可 |
 | `runo archive RUN... ` / `runo archive --older-than 90d` / `runo restore RUN` | `runs/_archive/` へ移動 / 戻す |
 | `runo delete RUN... [-y]` | created・failed・cancelled・scratch の run を削除 |
 | `runo tidy [--apply] [--only KIND] [--older-than AGE] [--purge-work RUN...]` | 整理候補の表示と実行 |
@@ -167,5 +180,6 @@ scratch と archived は表示しません。
 
 日数は `runops.toml` の `[defaults]` で変えられます。`--older-than 14d` のように指定すると、
 その回だけ両方の日数をその値で置き換えます。pinned の run は `tidy` と `delete` の対象になりません。
+`--purge-work` は adapter を読み込めないと何も消さずにエラーにします。
 
 exit code は 0 が成功、1 が実行時エラー（sbatch 失敗など）、2 が使い方や設定のエラーです。

{runops-2.1.3 → runops-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runops"
-version = "2.1.3"
+version = "2.2.0"
 description = "Run ledger and Slurm job submission for HPC simulation projects"
 readme = "README.md"
 license = "Apache-2.0"

{runops-2.1.3 → runops-2.2.0}/src/runops/__init__.py

@@ -1,3 +1,3 @@
 """runops: run ledger and Slurm job submission for HPC simulation projects."""
 
-__version__ = "2.1.3"
+__version__ = "2.2.0"