Metadata-Version: 2.4
Name: elphos
Version: 0.2.0
Summary: ELPH OS - Essential Loop Portable Harness: a thin, agent-agnostic control plane for development loops (LoopSpec/journal/decide, zero dependencies)
Author: oudouusa
License: MIT
Project-URL: Repository, https://github.com/oudouusa/elphos
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ELPH OS — Essential Loop Portable Harness

**A thin, portable harness for every development loop.**

機械識別子は `elphos`(PyPI / npm 空き確認済み 2026-07-03)。ブランド・愛称は ELPH。
世界観 KB の ELPH(elph-vault、`/lore` スキル)とは無関係。

## これは何か

AI agent の進化速度に適応するための **thin control plane**。
agent(Claude Code / codex 等)を差し替え可能な実行器として扱い、
自分側に残すべきもの — ループ運用・実行台帳・証跡・予算・採否記録 — を
file-first で所有するための最小カーネル。

```text
Model      (交代前提 — Claude / codex / 将来の agent)
Harness    (Claude Code / codex CLI — 揮発層、wrap しない)
LoopOS     (LoopSpec / LoopRun / scheduler 接続 / 成熟度)   ← this repo
Meta       (HarnessRun / trace / budget / adapter)          ← this repo
```

## 名前 = 設計契約

- **Essential** — kernel への機能追加は、消費ループの evidence がある場合のみ(admission 規律)
- **Loop** — 対象は development loop の運用(turn/goal/time/proactive)
- **Portable** — agent 非依存。仕様は TOML、台帳は JSONL、依存ゼロの Python stdlib
- **Harness** — ハーネスの上の薄い層。ハーネス自体を再実装しない

機能追加の PR は「それは Essential か? Portable を壊さないか?」に答えること。

## Status

正本は [docs/spec-v0.md](docs/spec-v0.md)。
到達ゴール(完成の定義 G1-G6 とフェーズ O1-O3)は
[docs/end-state-goal-2026-07-04.md](docs/end-state-goal-2026-07-04.md)。
Step 3 受け入れ済み(2026-07-04): L2 = worktree + agent + gate + 採否分離
(`decide` → decision_record、実装 agent と採否の分離)。実 slice B001 を
codex2 で完走(tokens_est 51,368 自動記録、adopt)。adopt / revert /
二重判定ガードは local-shell スモークで検証済み。
Step 4(upstream-watch)稼働中: loop spec + journal は ~/.claude(claude-harness)
ホスト(owner decision 2026-07-04 — kernel repo は実行時状態を持たないため)、
oracle は本 repo 同梱(`--state-path` 必須)、weekly systemd user timer
(Mon 09:30、Persistent + linger)。**v0 ロードマップ(Step 1-4)完了。**

Usability 改定 v0.2.0(2026-07-07、初回 4 日運転の journal evidence 駆動):
E019 = L1/empty の oracle 報告を stdout に直接表示。E020 = budget は agent 起動
run のみカウント(L1 報告は無料 — cap 一時解除の儀式を廃止)。E021 =
`elphos finish` が adopt 後の機械的後処理(merge / gate 再実行 / 掃除)を実行
(採否分離は不変 — decide の adopt 記録が前提条件)。

```bash
uv tool install /path/to/elphos
elphos validate examples/c4-intake.toml   # => OK
elphos run c4-intake                      # L1: oracle 報告を表示 + journal 追記
elphos decide <run_id> adopt|revert       # L2: 採否を decision_record に記録
elphos finish <run_id>                    # L2: adopt 後の merge/gate/掃除(E021)
elphos report                             # (UTC date, loop) 日次集計
python3 -m unittest discover -s tests     # 114 tests
```

consumer registry: `~/.claude/loops.toml`(`ELPHOS_REGISTRY` で上書き可)。

### Harness skills(新しい端末での導入)

汎用 skill テンプレートは `integrations/`(Claude Code / Codex)。導入は 1 コマンド:

```bash
bash integrations/install-skills.sh   # checkout パスを埋め込んで各 harness へ配置
```

既定は非破壊(配置先に差分があれば保持、`--force` で上書き)。手順の正本は
`docs/operating.md` — skill はそこへの pointer + harness 固有メモのみ。

## Non-goals(恒久)

デーモン / UI / セッション管理 / 権限エンジン / メモリストア(dev-vault が正本)/
汎用 agent runtime / Omnigent・LangGraph 代替。

## Trust boundary

Consumer `.loops/*.toml` specs are trusted input: `oracle`, `gate`, and
`agent_command` execute as you. Never run loops from untrusted repos. Keeping
secrets out of oracle/agent/gate output is the producing side's responsibility;
artifacts are stored verbatim.

Development note: run `scripts/install-git-hooks.sh` once to install the local
pre-push gate (`python3 -m unittest discover -s tests`).
