runops 2.4.0__tar.gz → 2.6.0__tar.gz

{runops-2.4.0 → runops-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runops
-Version: 2.4.0
+Version: 2.6.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
@@ -76,6 +76,7 @@ runo init
 | 資源を変えて作り直す | R20261015-0003 を 256 並列・72 時間で作り直して（case はそのまま） |
 | 片付ける | 古い run を整理して。消すものと archive するものを先に見せて |
 | 作り直した旧系列を片付ける | 旧系列は新系列で置き換えたので、対応を記録して archive して |
+| 解析する | この系列の速度を比較して。図とスクリプト、調査メモを系列の `_analysis/` にまとめて |
 | simulator を足す | パッチを当てた ~/BEACH-dev をビルドして、別の simulator として登録して |
 | 更新する | runops と simulator を最新にして |
 | v1 から移る | この project を runops v2 に移行して（`runo migrate-v1` を dry-run で確認してから） |
@@ -100,15 +101,19 @@ lunar-sheath/
 │   │   │   ├── work/            Slurm のログと出力
 │   │   │   └── analysis/
 │   │   └── wc-phiz-scan/        sweep はまとめて 1 階層
+│   │       └── _analysis/      系列・sweep の比較調査（topic ごと）
 │   ├── _scratch/                smoke / debug（期限付き）
 │   └── _archive/                archive した run
 ├── LOG.md                       run をまたぐ結論と次の判断
 ├── notes/                       再利用する知見
+├── analysis/                    複数系列にまたがる調査。共通コードは lib/
 └── AGENTS.md, .agents/skills/, .claude/skills/
 ```
 
 run は ID が変わらないので、directory を移動してもエージェントは見つけられます。
 `work/` は Git の対象外で、`manifest.toml`、`input/`、`job.sh` は Git で追えます。
+解析は依存する run の範囲で置き場所を選び、調査ごとに `README.md`、`scripts/`、`out/`、
+`logs/` をまとめます。判断は `LOG.md` からリンクし、古い解析 job の log は整理候補になります。
 
 ## 対応 simulator
 

{runops-2.4.0 → runops-2.6.0}/README.md

@@ -45,6 +45,7 @@ runo init
 | 資源を変えて作り直す | R20261015-0003 を 256 並列・72 時間で作り直して（case はそのまま） |
 | 片付ける | 古い run を整理して。消すものと archive するものを先に見せて |
 | 作り直した旧系列を片付ける | 旧系列は新系列で置き換えたので、対応を記録して archive して |
+| 解析する | この系列の速度を比較して。図とスクリプト、調査メモを系列の `_analysis/` にまとめて |
 | simulator を足す | パッチを当てた ~/BEACH-dev をビルドして、別の simulator として登録して |
 | 更新する | runops と simulator を最新にして |
 | v1 から移る | この project を runops v2 に移行して（`runo migrate-v1` を dry-run で確認してから） |
@@ -69,15 +70,19 @@ lunar-sheath/
 │   │   │   ├── work/            Slurm のログと出力
 │   │   │   └── analysis/
 │   │   └── wc-phiz-scan/        sweep はまとめて 1 階層
+│   │       └── _analysis/      系列・sweep の比較調査（topic ごと）
 │   ├── _scratch/                smoke / debug（期限付き）
 │   └── _archive/                archive した run
 ├── LOG.md                       run をまたぐ結論と次の判断
 ├── notes/                       再利用する知見
+├── analysis/                    複数系列にまたがる調査。共通コードは lib/
 └── AGENTS.md, .agents/skills/, .claude/skills/
 ```
 
 run は ID が変わらないので、directory を移動してもエージェントは見つけられます。
 `work/` は Git の対象外で、`manifest.toml`、`input/`、`job.sh` は Git で追えます。
+解析は依存する run の範囲で置き場所を選び、調査ごとに `README.md`、`scripts/`、`out/`、
+`logs/` をまとめます。判断は `LOG.md` からリンクし、古い解析 job の log は整理候補になります。
 
 ## 対応 simulator
 

{runops-2.4.0 → runops-2.6.0}/SPEC.md

@@ -119,12 +119,14 @@ v1 で運用した 2 つの project（`project_dust_release`: BEACH、run 120、
       <run_id>--<label>/           # 単発 run
       <sweep_label>/
         <run_id>--<label>/         # sweep で生成された run
+        _analysis/<topic>/        # この group に依存する調査（§9.1）
     _scratch/
       <run_id>--<label>/           # scratch run
     _archive/
       <case_name>/...              # archive された run（元の相対 path を保つ）
   adapters/                # 任意。project ローカル adapter `<name>.py`（§8.1）
   notes/                   # 永続的な知見。1 topic 1 file。runops は管理しない（§9）
+  analysis/<topic>/        # 複数 group にまたがる調査。共通コードは analysis/lib/（§9.1）
   LOG.md                   # project 全体の追記専用ログ（§9）
   AGENTS.md                # agent 向け入口（§10）
   CLAUDE.md                # `@AGENTS.md` のみ
@@ -147,7 +149,8 @@ v1 で運用した 2 つの project（`project_dust_release`: BEACH、run 120、
   `runs/` 配下の任意の場所に移動してよい。runops は manifest の `run.id` で run を
   見つける（§7.2）。
 - 既定の配置先は `runs/<case_name>/`。`--dest` で上書きできる。`_` で始まる
-  directory（`_scratch`、`_archive`）は runops が予約する。
+  directory（`_scratch`、`_archive`、`_analysis`）は runops が予約する。
+  `_analysis` は group の調査用で、run の発見・作成先から除く。
 - run directory の中（自身と子孫）には run を置けない。`--dest` が既存 run の中なら拒否し、
   `delete` は中に別の run があれば拒否する（§7.2 の走査は manifest のある directory で止まる）。
 - run id は `R<YYYYMMDD>-<NNNN>`。その日の既存 run と `.runops/last_run_id` の大きい方に 1 を足す。
@@ -160,7 +163,8 @@ v1 で運用した 2 つの project（`project_dust_release`: BEACH、run 120、
 - `materials/`、`refs/`、`scripts/` などユーザーが置く directory は runops の関知外。
   runops は `runs/`、`cases/`、`.runops/`、`.agents/skills/`、`.claude/skills/`、
   `AGENTS.md`、`CLAUDE.md`、`runops.toml` 以外を作成・変更しない（`LOG.md`、`notes/`
-  は `init` の雛形生成のみ）。
+  は `init` の雛形生成のみ）。例外として `tidy --apply --only analysis-logs` は
+  §7.5 の解析 log を削除できる。解析のスクリプト・結果・README は agent が書く。
 
 ---
 
@@ -460,6 +464,22 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 
 ---
 
+### 6.4 進捗
+
+adapter が `progress(run_dir)` を持つとき、`sync` は running の run と、queue を離れた
+直後の run について呼び、`{done, total, unit, start}` を受け取る。`done` は今の到達点、
+`total` は目標（不明なら省略）、`unit` は数える単位（`batch`、`step` など）、`start` は
+この attempt を始めた地点（resume した run の再開点。新規なら 0）。
+
+- 観測は `submit/progress.<job_id>.jsonl` に `{at, done}` として追記する（attempt ごと、
+  上限 1000 件程度）。queue を離れたときの観測は終了時刻で記録し、終了後の待ち時間を速度に含めない。
+- 要約を `[[job.attempts]].progress` に置く: `done`、`total`、`unit`、`start`、`fraction`、
+  `rate_recent_per_hour`（直近 10 分）、`rate_attempt_per_hour`（program 開始から。起点は
+  `start`）、`eta_hours`（running のみ）。program 開始時刻は job.sh が stdout に出す
+  `runops: start` 行から取り、`started_at` に入れる。
+- `status` / `list` は要約だけを読む（file を開かない）。read-only command は観測を足さない。
+- 解析は adapter が行い、runops は保存と表示だけを持つ（§1.2 #4）。
+
 ## 7. CLI
 
 ### 7.1 共通規則
@@ -487,7 +507,7 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 - `runs/` 配下（`_archive/` を含む）を再帰的に走査し `manifest.toml` を集める。
   `.runops/index.toml` に `run_id -> run_dir` の cache を持ち、manifest が cache の
   path に無ければ再走査して cache を更新する。cache は常に再生成可能で、
-  壊れていても動作に影響しない。
+  壊れていても動作に影響しない。`_analysis/` は走査せず、そこにある manifest は run と扱わない。
 - 走査対象は `runs/` のみ。project 外や `runs/` 外の run は扱わない。
 
 ### 7.3 command 一覧
@@ -498,11 +518,11 @@ 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 行。配置した runops skill が install 済みの runops より古ければ `runo update --skills-only` を促す warning |
+| `runo context [--json]` | agent 向け現在地。project 名、simulator、active run 数、直近 run 5 件、scratch 期限切れ数、`LOG.md` 末尾 20 行、現用 group の解析 topic 名（§9.1）。配置した 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]... [--job k=v]... [--tag T]... [--scratch] [--dest DIR] [--submit] [--created-by WHO] [--json]` | 単発 run を作る |
-| `runo new --from RUN [--why] [--set k=v]... [--job k=v]... [--job-from-case] [--continue] [--submit]` | 既存 run の params と `[job]` から派生 run を作る（§5）。`--continue` は adapter が `extend_inputs()` を実装する場合のみ有効（§8.1） |
+| `runo new --from RUN [--why] [--set k=v]... [--job k=v]... [--job-from-case] [--continue] [--submit]` | 既存 run の params と `[job]` から派生 run を作る（§5）。置き場所の既定は元 run と同じ directory（元 run が archive / scratch なら `runs/<case>/`）。`--continue` は adapter が `extend_inputs()` を実装する場合のみ有効（§8.1） |
 | `runo sweep CASE --set k=v1,v2,... [--set ...] [--names KEY=n1,n2,...]... [--job k=v]... [--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 を表示して確認 |
@@ -536,7 +556,7 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 
 ### 7.5 `tidy` の規則
 
-`tidy` は候補を 4 種に分けて表示する。`--apply` はすべてを実行し、
+`tidy` は候補を 6 種に分けて表示する。`--apply` はすべてを実行し、
 `--apply --only KIND` で絞れる。
 
 | kind | 条件 | 動作 |
@@ -546,8 +566,14 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 | `old-completed` | `completed` で `defaults.tidy_archive_days`（既定 90）日より古く、`pinned = false` | archive |
 | `orphan-job` | `submitted`/`running` だが squeue/sacct に job が無い | sync（state 確定） |
 | `unused-build` | `.runops/build/*` のうち、非 archived run の manifest から参照されないもの | delete |
+| `analysis-logs` | §9.1 の解析 directory 配下の `logs/` にある `*.<jobid>.out/err`。組の最終更新が `tidy_failed_days` より古く、同じ log directory・job 名の最新の組ではない | log file のみ delete |
 
 - `--older-than AGE`（例 `14d`）はその回だけ、上の 2 つの日数をどちらもこの値で置き換える。
+- `analysis-logs` は project の `analysis/`、group の `_analysis/`、run の `analysis/`
+  （topic の下も含む）を対象にする。stdout/stderr は同じ job id の組として更新時刻を比較し、
+  最新の組は常に残す。同時刻なら job id が大きい組を最新とする。片方だけの log も同じ扱い。
+  archived / pinned / submitted / running run の解析と、symlink は対象外。
+  適用直前にも対象範囲・更新時刻・最新組を再確認し、条件が変われば削除せず止まる。
 - `--purge-work RUN...` は指定 run の `work/` の中身を削除し `work_purged_at` を記録する。
   adapter が `keep_patterns()` を返す場合、一致するファイルは残す。`completed` 以外は拒否。
   adapter を読み込めない（残すファイルを判定できない）ときは何も消さずにエラーにする。
@@ -621,6 +647,7 @@ class SimulatorAdapter(ABC):
     def agent_context_dir(self) -> Path | None: return None      # §8.2
     def configure(self, sim_config: dict) -> None: ...           # runops.toml の [simulators.X] を受け取る
     def job_prelude(self, run_dir: Path) -> list[str]: return [] # job.sh で実行直前に置く shell 行
+    def progress(self, run_dir: Path) -> dict | None: return None  # §6.4。{done, total, unit, start}
 ```
 
 - job.sh は run_dir へ `cd` してから実行する（v1 と同じ。v1 adapter の path 規約
@@ -675,8 +702,9 @@ runops は `init` と `update` で次を行う。
    （例: `mpiemses3d-input-review`）。`runops-` で始まる名前は予約されており展開しない。
 2. `references/` を `.agents/skills/<adapter>-references/` にコピーし、
    `SKILL.md` が無ければ reference 一覧を列挙した `SKILL.md` を生成する。
-   展開した skill の `../../references/`（package 内の配置での参照）は
-   `../<adapter>-references/` に書き換える。
+   `docs/` があれば同じく `.agents/skills/<adapter>-docs/` に置く。展開した skill の
+   `../../references/`、`../../docs/`（package 内の配置での参照）は `../<adapter>-references/`、
+   `../<adapter>-docs/` に書き換える。
 3. 展開先には `.managed-by-runops` marker を置く。marker のある directory は
    `update` 時に **無条件で上書き** する。marker の無い同名 directory は触らず warning。
 4. `.runops/skills.lock` に adapter 名、package version、展開した directory、content hash を記録する。
@@ -692,7 +720,7 @@ runops は `init` と `update` で次を行う。
 
 ### 8.3 runops 自身の skill
 
-runops は次の 5 skill だけを同梱し、simulator skill と同じ仕組みで展開する。
+runops は次の 6 skill だけを同梱し、simulator skill と同じ仕組みで展開する。
 利用者が覚えるコマンドは `runo init` だけとし、それ以外（simulator の追加、更新、v1 移行を含む）は
 エージェントへの依頼で行う。
 各 SKILL.md は 60 行以内に収める。
@@ -702,6 +730,7 @@ runops は次の 5 skill だけを同梱し、simulator skill と同じ仕組み
 | `runops-create-run` | `new` / `sweep` の使い方。`--why` を必ず書く、scratch の使い分け |
 | `runops-check-status` | `sync` → `list` → `log` の順。失敗時の `retry` と `tidy --purge-work` |
 | `runops-tidy` | `tidy` を定期的に実行する判断基準。pin の使い方 |
+| `runops-analyze` | 依存する run の範囲で調査の置き場所を決め、script・結果・log・README をまとめる |
 | `runops-reference` | command 一覧（§7.3 の表をそのまま載せる） |
 | `runops-maintain` | simulator の追加、runops と simulator package の更新、`migrate-v1`、`doctor` の読み方 |
 
@@ -730,7 +759,7 @@ v1 の `emses` / `beach` adapter は次の順で runops 本体から出す。
    見つかると使われなくなる（解決順 1 が優先）ので、ユーザーが消せばよい。
 ---
 
-## 9. ノート
+## 9. ノートと解析
 
 置き場所は 3 つに固定し、runops はどれも「管理」しない（schema、budget、rotation、
 seal、index を持たない）。
@@ -748,10 +777,33 @@ seal、index を持たない）。
   - 複数 run にまたがる結論と次の判断は `LOG.md` に日付付きで追記する
   - 再利用する式・手法・環境の落とし穴は `notes/<topic>.md` に書く。既存 file があれば追記し、
     似た topic の file を増やさない
-  - それ以外の場所（`research/`、`analysis/*.md`、`runs/` 直下など）に note file を作らない
+  - 調査の詳細は §9.1 の README にまとめ、LOG.md からリンクする
 - v1 の `research/results/`、`.runops/insights/`、`research/archive/legacy/` は移行時に
   `notes/legacy/` 配下へ **移動せず** そのまま残し、`notes/README.md` から path を案内する（§11）。
 
+### 9.1 解析の置き場所
+
+| 結果が依存する範囲 | 置き場所 |
+|---|---|
+| 1 run | `runs/.../<RUN>/analysis/`（必要なら `<topic>/`） |
+| 1 group（同じ directory に並ぶ系列・sweep） | `runs/<group>/_analysis/<topic>/` |
+| 複数 group・case または project 全体 | `analysis/<topic>/` |
+| 共通コード | `analysis/lib/` |
+
+- group は directory であり、新しい entity / ID / ledger を持たない。
+- 調査 directory は `README.md`（問い・対象 run id・方法・結果・制約）、`scripts/`
+  （Python、sbatch）、`out/`（図・JSON・CSV）、`logs/`（job の stdout/stderr）からなる。
+  topic は内容で名付け、同じ問いは README に日付付きで追記する。
+- `init` の `.gitignore` は `**/logs/`、`__pycache__/`、`.runops/analysis-env/` を含む。
+  既存 project のファイルは自動で再配置しない。
+- `context` は現用 group の `_analysis/*/README.md` がある topic 名を表示し、
+  `--json` では `group_analysis` に project 相対の group path → topic 名一覧を返す。
+  README 本文や `out/`、simulator の `work/` は読まない。
+- `archive DIR` が group 配下の全 run を移す場合、その group と配下の group の
+  `_analysis/` も同じ相対 path の `runs/_archive/` に移す。run が残る group の解析は残す。
+  確認表示に解析の移動先を含め、移動前に run と解析の全移動先を検査し、既存なら上書きしない。
+  `archive RUN...` / `--older-than` は group の解析を動かさず、`restore RUN` は run のみを戻す。
+
 ---
 
 ## 10. harness 生成
@@ -898,7 +950,7 @@ src/runops/
 | 項目 | 目標 |
 |---|---|
 | `src/runops/` の行数（skill の md を除く） | 8,000 行以下 |
-| CLI command 数（`case new` / `case list` を含む。同じ command の option 違いは数えない） | 25 以下。§7.3 の表の distinct command は 24 |
+| CLI command 数（`case new` / `case list` を含む。同じ command の option 違いは数えない） | 25 以下。§7.3 の表の distinct command は 25 |
 | ユーザーが編集する 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` を外す） |
@@ -936,6 +988,9 @@ src/runops/
 9b. 同名 adapter が entry point と `adapters/X.py` の両方にあるとき entry point が優先される。
    どちらも無く `generic` でもなければ exit code 2 で案内が出る。
 10. `manifest.toml` の書き込み途中で例外が起きても元のファイルが壊れない。
+11. 解析 log の tidy は最新組・新しい組・対象外ファイルを残し、確認後の更新も削除しない。
+    group の archive は全 run が対象のときだけ解析も移し、衝突時は何も動かさない。
+    context は調査の名前だけを読み、解析内の manifest を run と誤認しない。
 
 ### 13.3 ドキュメント
 
@@ -956,6 +1011,7 @@ v2 の文書は次の 4 ファイルだけにする。
 
 | 項目 | 決定 | 理由 |
 |---|---|---|
+| 解析の配置 2.6.0（2026-10-23） | 依存する run の範囲に応じて run 内 `analysis/`、group の `_analysis/<topic>/`、project の `analysis/<topic>/` にまとめる。skill、log の tidy、group archive、context を対応させる（§9.1） | 報告・図・script・job log が分散・混在していた。group は既存の directory として扱い、新しい entity や command は足さない。既存ファイルの整理は移動一覧を提示してから行う |
 | job の cwd | run_dir（v1 と同じ）。Slurm log は `work/` | v1 adapter の path 規約と実 project の job.sh をそのまま使える |
 | 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 用 |
@@ -981,5 +1037,6 @@ v2 の文書は次の 4 ファイルだけにする。
 | 置き換えた系列の整理（2026-10-21） | `archive` が DIR（系列）を受け、`--superseded-by` で置き換え先を manifest に記録する。新しい command と tidy の種別は足さない。skill は新系列を作ったら旧系列の要否を確かめ、不要なら archive して現用系列・archive 先・件数を報告する | 修正版を作った後に旧系列が作業領域に残り、毎回ユーザーが整理を頼んでいた。`parent_run` だけでは比較用の派生と置き換えを区別できないので、置き換えは明示操作で記録する。旧 `archive` は 1 件ずつ検査していて、途中の running run で一部だけ移動していた（#113） |
 | 生成ハーネスの書き方（2026-10-21） | AGENTS.md の Rules を「作業の進め方」5 項目に絞り、各項目を「何をするか」と短い理由で書く。skill は手順に専念し、AGENTS.md の方針（manifest を手で編集しない等）を繰り返さない | #112・#113 で規則が増え、禁止形（never / do not）が並んでいた。現行の Claude の prompting 指針は、しないことより何をするかを、理由と共に書くことを勧め、強い禁止語は過剰反応を招くとしている |
 | 複数 run の mv / archive（2026-10-22） | 1 回の `run.lock` の下で全対象を読み直して検査し、通ってから移す。途中の filesystem error では移し終えた run id を示して止まる | `mv A B C --dest X` は 1 件ずつ検査して移していたので、途中の submitted run で一部だけ移動していた。archive は表示の後で lock を取り直していて、その間に再投入された run で同じことが起き得た |
+| 進捗と系列配置 2.5.0（2026-10-23） | adapter に任意の `progress()`、`sync` が時刻付き観測を保存し速度・残り時間を要約（§6.4）。`new --from` の既定置き場所を元 run と同じ directory に。agent context の `docs/` も展開 | 速度比較のために agent が時刻付き batch 観測を手で保存し、再開点や終了後の待ちを毎回補正していた（4 回）。継続世代が case 直下に並び、同じ計算の系列を見分けにくかった。skill が package の `docs/` を参照していたが展開されていなかった。進捗の解析は simulator 固有なので adapter が持ち、runops は保存と表示だけにする |
 | FEEDBACK 棚卸し 2.4.0（2026-10-23） | `--job k=v` と `new --from` の `[job]` 継承、created の archive / restore、archived scratch を期限削除しない、展開 skill の references 参照の書き換えと `doctor` のリンク検査、adapter warning への版の併記、生成 AGENTS.md に解析環境の置き場所 | hub の FEEDBACK で、資源変更のための case 編集（3 回）、置換済み draft を archive できず helper で迂回（2 回）、保管目的の archive が期限削除される、skill から reference に辿れない、新版の正規キーが誤記に見える、解析依存の置き場所が project ごとに違う、が記録された。いずれも既存 command の拡張で、command 数は増やさない |
 | 使い方ガイド | `docs/guide.md` を追加し、文書を 4 ファイルにする（§13.3） | README の依頼例の表と command 一覧の間を埋める、場面ごとの流れ（case と run の分け方、smoke から本計算、状態の決まり方、整理）の置き場所が無かった |

{runops-2.4.0 → runops-2.6.0}/docs/adapter.md

@@ -49,6 +49,7 @@ class Adapter:
 | `keep_patterns() -> list[str]` | `tidy --purge-work` で残す glob |
 | `extend_inputs(src_run, run_dir, params) -> list[str]` | `runo new --from RUN --continue` の restart 設定 |
 | `agent_context_dir() -> Path | None` | 同梱 skill と reference の場所 |
+| `progress(run_dir) -> dict | None` | 進捗 `{"done", "total", "unit", "start"}`。`runo sync` が時刻付きで保存し、速度と残り時間を出す |
 
 `runtime` は `executable`、`package_version`、`exe_hash`、`git_commit`、`git_dirty`、
 `env`、`resolver_mode`、`build_dir` を持ちます。
@@ -76,14 +77,15 @@ project の `adapters/mysim.py` に `Adapter` という名前で置けば使え
 <dir>/
   skills/<skill-name>/SKILL.md
   references/*.md
+  docs/*.md          # 任意。references と同じく展開する
 ```
 
 `runo init` と `runo update` は `skills/*` を project の `.agents/skills/` と
 `.claude/skills/` に同名でコピーし、`references/` を `<adapter>-references` として置きます。
 skill 名は package 側で名前空間を付けてください（例: `mysim-input-review`）。
 `runops-` で始まる名前は予約されています。skill から reference へは
-`../<adapter>-references/X.md` と書いてください。package 内の配置どおりの
-`../../references/X.md` は展開時にこの形へ書き換えます。`runo doctor` は展開済み skill の
+`../<adapter>-references/X.md`（`docs/` なら `../<adapter>-docs/X.md`）と書いてください。
+package 内の配置どおりの `../../references/X.md`、`../../docs/X.md` は展開時にこの形へ書き換えます。`runo doctor` は展開済み skill の
 相対リンク切れを報告します。展開した directory には
 `.managed-by-runops` が置かれ、更新時に上書きされます。利用者が作った同名 directory は
 上書きしません。

{runops-2.4.0 → runops-2.6.0}/docs/guide.md

@@ -131,6 +131,11 @@ walltime は、同じ case・同じ資源で終わった run の実時間を元
 `runo sync` は、active な run が何件あっても `squeue` と `sacct` を 1 回ずつしか呼びません。
 エージェントには `squeue` を直接叩かせず、`runo sync` を使わせてください。
 
+adapter が進捗に対応していれば（BEACH の batch、MPIEMSES3D の step）、`sync` のたびに時刻付きの
+観測を残し、`runo list` / `status` に `62% 0.198 s/batch eta 3.1h` のように進み具合、直近 10 分の
+速度、残り時間を出します。resume した run は再開点から数え、終わった run は終了時刻までで速度を出すので、
+版を切り替えた前後の比較にそのまま使えます（`--json` の `progress`）。
+
 ### 状態の決まり方
 
 run の状態は `created → submitted → running → completed | failed | cancelled` と進みます。
@@ -180,13 +185,14 @@ project の run だけが対象です。同じアカウントの別 project の
 > R20261015-0003 の続きを 2 倍の step で。
 
 `runo new --from RUN --continue` で、終わった run の出力から再開する run を作ります。
+`--from` で作る run は元 run と同じ directory に置かれるので、同じ計算の継続は 1 つの directory に並びます。
 再開の方法は simulator ごとに違い、adapter が対応している場合だけ使えます
 （現在は MPIEMSES3D が対応し、`SNAPSHOT1` から再開します）。新しい run は元の run を `parent_run` として記録します。
 
 前の job が終わるのを待って投入したいときは、「R20261016-0005 が成功したら投げて」と頼めば
 `runo submit RUN --afterok <job_id>` になります。
 
-## 6. 記録を残す
+## 6. 解析して記録を残す
 
 記録の置き場所は 3 つに決まっています。
 
@@ -196,10 +202,40 @@ project の run だけが対象です。同じアカウントの別 project の
 | 複数の 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 名を表示します。エージェントは作業の始めに
+調査の詳細と図・スクリプトは、結果が依存する run の範囲に合わせてまとめます。
+
+> この系列の速度を比較して。図とスクリプト、調査メモを系列の `_analysis/` にまとめて。
+
+| 依存する範囲 | 置き場所 |
+|---|---|
+| 1 run | `<run_dir>/analysis/`（必要なら topic を切る） |
+| 1 系列・sweep | `runs/<group>/_analysis/<topic>/` |
+| 複数系列・case、project 全体 | `analysis/<topic>/` |
+| 共通コードとそのテスト | `analysis/lib/` |
+
+group は run が並ぶ directory です。登録や新しい ID は要りません。
+topic は `speed-by-version` のように問いの内容で名付け、同じ問いをやり直すときは
+同じ directory の結果を更新し、README に日付付きで追記します。
+
+```text
+<topic>/
+  README.md   問い・対象 run id と path・方法・結果・制約
+  scripts/    Python と sbatch
+  out/        図、JSON、CSV、HTML
+  logs/       解析 job の stdout/stderr（Git 管理外）
+```
+
+エージェントは `runops-analyze` skill を使い、調査の README と、そこへのリンクを含む
+`LOG.md` の判断を更新します。`notes/` は run に依存しない知見に使います。
+解析の追加依存は `.runops/analysis-env/` に置き、重い読み込みや作図はサイトの規則に従って
+計算ノードで実行します。sbatch は調査 directory から投入し、事前に `logs/` を作って
+`#SBATCH -o logs/%x.%j.out` と `#SBATCH -e logs/%x.%j.err` を指定します。
+既存 project のファイルは自動で移動しません。整理を頼むと、移動前に一覧を提示します。
+
+`runo context` は `LOG.md` の末尾、`notes/` の file 名、現用 group の
+`_analysis/*/README.md` がある topic 名を表示します。エージェントは作業の始めに
 これを読むので、前回の続きから話を始められます。
 
 ## 7. 整理する
@@ -215,6 +251,7 @@ run は消さなくても `runo list` が古いものを隠しますが、direct
 | `expired-scratch` | 期限切れの scratch run（archive したものは除く） | 削除 |
 | `stale-failed` | 30 日より古い failed / cancelled で、`why` もノートも無い | 削除 |
 | `old-completed` | 90 日より古い completed | archive |
+| `analysis-logs` | 30 日より古い解析 job の log（各 job 名の最新組は保持） | log のみ削除 |
 | `orphan-job` | 投入済みなのに Slurm が知らない | `sync` で状態を確定 |
 | `unused-build` | どの run も使っていない build cache | 削除 |
 
@@ -233,6 +270,14 @@ run id で引き続き見つかり、`runo restore` で戻せます。
 記録され、理由はノートに残ります。比較用に派生しただけの run は置き換えとは扱わないので、
 旧系列が不要かどうかは毎回確かめます。
 
+directory 指定で group の全 run を archive すると、その `_analysis/` も同じ相対 path で
+移動します。run が残る group の解析は元の場所に残り、移動先に既存の解析があれば、run を
+動かす前に停止します。`archive RUN...` と `restore RUN` は run だけを移動します。
+
+解析 log だけの整理は「古い解析 log を整理して」で `runo tidy --only analysis-logs` に
+なります。各 `logs/` の `*.<jobid>.out/err` を組で比較し、job 名ごとに最新の組を残します。
+片方が新しければ両方とも残し、README、script、結果は削除しません。
+
 論文の図に使う run や基準にする run は pin しておくと、`list` に常に表示され、`tidy` や `delete`
 の対象になりません。
 

{runops-2.4.0 → runops-2.6.0}/docs/reference.md

@@ -6,7 +6,7 @@
 ## runops.toml
 
 project root にあり、`runo` はここを上方向に探して project を特定します。
-command はこの project の `runs/` 配下だけを扱い、別 project の run directory や
+run を対象にする command はこの project の `runs/` 配下だけを扱い、別 project の run directory や
 directory を path で渡すとエラーになります。run id は project ごとなので、同じ id が
 別 project にあっても cwd の project の run を指します。
 
@@ -110,7 +110,7 @@ runops だけが書きます。手で編集しないでください。主な fie
 | `[path]` | `run_dir`（project 相対）、`archived_from`、`archived_at` |
 | `[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`、`elapsed`、`cancel --why` の `cancel_reason`） |
+| `[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`、`cancel --why` の `cancel_reason`、`runo sync` が付ける `progress`（§進捗）） |
 | `[params]` | case の params に `--set` を適用した最終値 |
 | `[variation]` | `changed_keys`、`job_changed_keys`（case の `[job]` と違う key） |
 | `[identity]` | `input_hash` |
@@ -139,7 +139,9 @@ run id は削除後も再利用しません。`--dest` に既存 run の中は
 ## command
 
 `list --json` と `status --json` は、walltime の根拠として `walltime`、最新 attempt の `elapsed`、
-`walltime_used`（elapsed / walltime）、`slurm_state` も返します。表では `TIMEOUT` などを
+`walltime_used`（elapsed / walltime）、`slurm_state` も返します。adapter が `progress()` を持てば
+`progress`（`done`、`total`、`unit`、`fraction`、`rate_recent_per_hour`、`rate_attempt_per_hour`、
+`eta_hours`）も返し、表の `progress` 列に `62% 0.198 s/batch eta 3.1h` と出します。表では `TIMEOUT` などを
 `failed (TIMEOUT)` と示します。
 
 全 command は `--help` で option を確認できます。`RUN` には run id、run directory、
@@ -151,10 +153,10 @@ run id は削除後も再利用しません。`--dest` に既存 run の中は
 | `runo doctor [--json]` | 設定、adapter の解決経路、executable、sbatch、skill の鮮度とリンク切れを点検 |
 | `runo update [--skills-only] [-y]` | simulator package を更新し skill と AGENTS.md の管理 block を再生成 |
 | `runo build SIM [--force]` | `local_source` の simulator を build |
-| `runo context [--json]` | agent 向けの現在地 |
+| `runo context [--json]` | agent 向けの現在地と現用 group の解析 topic 名（JSON の `group_analysis` は group path → topic 名一覧） |
 | `runo case new NAME [-s SIM] [--from CASE]` / `runo case list` | case の作成と一覧 |
 | `runo new CASE [--why] [--label] [--set k=v]... [--job k=v]... [--tag] [--scratch] [--dest DIR] [--submit] [--json]` | run を 1 つ作る。`--job` はこの run の `[job]` の値 |
-| `runo new --from RUN [--set k=v]... [--job k=v]... [--job-from-case] [--continue]` | 既存 run の params と `[job]` から派生（`--job-from-case` で `[job]` は case から）。`--continue` は adapter の restart 対応が必要 |
+| `runo new --from RUN [--set k=v]... [--job k=v]... [--job-from-case] [--continue]` | 既存 run の params と `[job]` から派生（`--job-from-case` で `[job]` は case から）。置き場所の既定は元 run と同じ directory。`--continue` は adapter の restart 対応が必要 |
 | `runo sweep CASE --set k=v1,v2 ... [--names k=n1,n2...] [--job k=v]... [--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... [--why TEXT] [-y]` / `runo retry RUN [--submit] [-y]` | scancel（`--why` は note に残る）/ failed・cancelled を created に戻す（理由付きで cancel された run は確認を取る） |
@@ -171,7 +173,11 @@ run id は削除後も再利用しません。`--dest` に既存 run の中は
 `list` は既定で active、created、直近 `list_since_days` 日、pinned の run を表示し、
 scratch と archived は表示しません。
 
-`tidy` の候補は次の 5 種類です。
+`archive DIR` が group 配下の全 run を移すときは、group の `_analysis/` も同じ相対 path で
+移動します。run が残る group の解析は残し、移動先が存在すれば全 run の移動前に拒否します。
+`archive RUN...` / `--older-than` と `restore RUN` は group の解析を移動しません。
+
+`tidy` の候補は次の 6 種類です。
 
 | kind | 条件 | 動作 |
 |---|---|---|
@@ -180,9 +186,17 @@ scratch と archived は表示しません。
 | `old-completed` | `tidy_archive_days`（既定 90）日より古い completed | archive |
 | `orphan-job` | Slurm が知らない submitted / running | sync |
 | `unused-build` | 非 archived run が参照しない `.runops/build/*` | delete |
+| `analysis-logs` | `tidy_failed_days` より古い解析 log。各 log directory・job 名の最新組は保持 | log のみ delete |
 
 日数は `runops.toml` の `[defaults]` で変えられます。`--older-than 14d` のように指定すると、
 その回だけ両方の日数をその値で置き換えます。pinned の run は `tidy` と `delete` の対象になりません。
 `--purge-work` は adapter を読み込めないと何も消さずにエラーにします。
 
+`analysis-logs` は project の `analysis/`、group の `_analysis/`、run の `analysis/` 配下の
+`logs/*.<jobid>.out/err`（topic の下も含む）に限定します。組の新しい方の更新時刻で年齢を判定し、
+最新組を残します。同時刻なら job id が大きい組を最新とします。片方だけの log も同じ扱いです。
+archived / pinned / submitted / running run の解析と symlink は対象外で、適用直前にも条件を
+確認します。`--json` の解析 log 候補は `files`（削除する project 相対 path）と `cutoff`
+（ISO 日時）も持ちます。確認後に条件が変われば削除せず、再度 tidy を実行するよう案内します。
+
 exit code は 0 が成功、1 が実行時エラー（sbatch 失敗など）、2 が使い方や設定のエラーです。

{runops-2.4.0 → runops-2.6.0}/pyproject.toml

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

{runops-2.4.0 → runops-2.6.0}/src/runops/__init__.py

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

{runops-2.4.0 → runops-2.6.0}/src/runops/cli.py

@@ -263,6 +263,8 @@ def context(as_json: bool = typer.Option(False, "--json")) -> None:
         )
     if data["notes_files"]:
         out.print("notes/: " + ", ".join(data["notes_files"]))
+    for group, topics in data["group_analysis"].items():
+        out.print(f"{group}/_analysis/: {', '.join(topics)}", markup=False)
     if data["log_tail"]:
         out.print("--- LOG.md (tail) ---")
         out.print(data["log_tail"], markup=False)
@@ -592,9 +594,20 @@ def retry(
 
 def _status_table(project: Project, manifests: list[Manifest]) -> Table:
     from runops.ops.listing import relative_age
+    from runops.ops.progress import format_progress
 
     table = Table(
-        "id", "status", "label", "case", "sweep", "created", "elapsed", "note", "why", box=None
+        "id",
+        "status",
+        "label",
+        "case",
+        "sweep",
+        "created",
+        "elapsed",
+        "progress",
+        "note",
+        "why",
+        box=None,
     )
     for m in manifests:
         s = m.to_summary(project.root)
@@ -625,6 +638,7 @@ def _status_table(project: Project, manifests: list[Manifest]) -> Table:
             s["sweep"],
             relative_age(s["created_at"]),
             elapsed,
+            format_progress(s["progress"]),
             s["last_note"][:60],
             s["why"][:60],
         )
@@ -857,12 +871,22 @@ def archive(
         if m.id in plan.superseded_by:
             line += f"  -> {', '.join(plan.superseded_by[m.id])}"
         out.print(line)
+    for directory in plan.analysis_dirs:
+        dest = project.runs_dir / "_archive" / directory.relative_to(project.runs_dir)
+        out.print(f"  analysis {project.rel(directory)} -> {project.rel(dest)}", markup=False)
     _confirm(f"Archive {len(plan.targets)} runs?", yes)
     archived = archive_runs(
-        project, plan.targets, superseded_by=plan.superseded_by, why=why, by=_actor()
+        project,
+        plan.targets,
+        superseded_by=plan.superseded_by,
+        why=why,
+        by=_actor(),
+        analysis_dirs=plan.analysis_dirs,
     )
     for run_id, dst in archived:
         out.print(f"archived {run_id} -> {project.rel(dst)}")
+    for directory in plan.analysis_dirs:
+        out.print(f"archived analysis {project.rel(directory)}", markup=False)
 
 
 @app.command("mv")

{runops-2.4.0 → runops-2.6.0}/src/runops/harness.py

@@ -12,7 +12,7 @@ END = "<!-- runops:end -->"
 COMMANDS = """\
 | command | effect |
 |---|---|
-| `runo context --json` | where the project stands: active runs, recent runs, LOG.md tail |
+| `runo context --json` | active runs, recent runs, group analysis topics, LOG.md tail |
 | `runo case list` / `runo case new NAME --simulator SIM [--from CASE]` | list / scaffold cases |
 | `runo new CASE --why TEXT [--set k=v]... [--job k=v]... [--scratch] [--submit]` | create one run |
 | `runo new --from RUN --why TEXT [--set k=v]... [--job k=v]... [--continue]` | derive a run (keeps its params and [job]) |
@@ -23,7 +23,7 @@ COMMANDS = """\
 | `runo cancel RUN [--why T]` / `runo retry RUN` | stop a job / reset failed or cancelled to created |
 | `runo note RUN "text"` / `runo pin RUN --reason TEXT` | append an observation / protect a key run |
 | `runo summarize RUN` | adapter summary into analysis/summary.json |
-| `runo tidy` / `runo tidy --apply` | list / apply cleanup (expired scratch, stale failures, old runs) |
+| `runo tidy` / `runo tidy --apply` | list / apply cleanup (runs, builds, old analysis logs) |
 | `runo mv RUN... [--dest DIR] [--label L] --why TEXT` | rename / move runs, keeping ids and inputs |
 | `runo archive RUN\\|DIR... [--superseded-by RUN\\|DIR --why T]` | move created or finished runs (or a series) to runs/_archive |
 | `runo restore RUN` / `runo delete RUN` | move back / remove |
@@ -78,7 +78,7 @@ the project found from the current directory.
   stopped. When a new series replaces an old one, ask whether the old one is still
   needed and archive it with `--superseded-by`.
 
-## Notes
+## Notes and analysis
 
 Notes live in three places, where `runo context` and the next session find them:
 - one run: `runo note RUN "..."`;
@@ -86,6 +86,18 @@ Notes live in three places, where `runo context` and the next session find them:
 - reusable knowledge (formulas, methods, pitfalls): `notes/<topic>.md`, extending the
   existing file for a topic.
 
+Place analysis by the runs its results depend on:
+
+| Scope | Location |
+|---|---|
+| One run | `runs/.../<RUN>/analysis/` |
+| One group (series or sweep directory) | `runs/<group>/_analysis/<topic>/` |
+| Multiple groups or the project | `analysis/<topic>/`; shared code in `analysis/lib/` |
+
+Keep each investigation's question, run ids, method, results and limits in its
+`README.md`, with `scripts/`, `out/` and `logs/` beside it. Link it from `LOG.md`.
+Use `runops-analyze` for this workflow; `runo context` lists group topics with a README.
+
 Analysis tools the simulator package does not bring go in `.runops/analysis-env/`
 (`uv venv .runops/analysis-env`), so `.venv` stays as `runo update` manages it. Run heavy
 reading and plotting where the site allows compute jobs.

{runops-2.4.0 → runops-2.6.0}/src/runops/manifest.py

@@ -220,8 +220,16 @@ class Manifest:
             "input_hash": str(self.section("identity").get("input_hash", "")),
             # Walltime evidence for the next run: elapsed of the latest attempt.
             **self.timing(),
+            "progress": self.progress,
         }
 
+    @property
+    def progress(self) -> dict[str, Any] | None:
+        """Progress of the latest attempt as `runo sync` last saw it (adapter ``progress()``)."""
+        attempts = self.job.get("attempts") or []
+        value = attempts[-1].get("progress") if attempts else None
+        return dict(value) if isinstance(value, dict) else None
+
     def timing(self) -> dict[str, Any]:
         """Walltime, latest attempt elapsed, the fraction used, and the last Slurm state."""
         walltime = str(self.job.get("walltime", ""))