feat: MVP closed loop — observer, scope, hard stops, ledger (PR #2)

Squash-merge of hitome0123's MVP implementation. Includes complete ledger on all paths (including scope-violation), strict scope matching with boundary tests, Observer, YAML config, hard stops, and stub role examples. Selected over PR #3 due to stricter audit coverage and adversarial self-review.

Author: hitome0123

.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: tests
+
+on:
+  push:
+    branches: [main, "feat/**", "fix/**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Configure git identity
+        # `_commit_candidate` injects per-commit identity, but a couple of
+        # tests still call `git commit` against a fresh tempdir directly.
+        run: |
+          git config --global user.email "ci@evolution-kernel.local"
+          git config --global user.name  "evolution-kernel-ci"
+
+      - name: Install package (PyYAML is the only runtime dep)
+        run: python -m pip install -e .
+
+      - name: Run unit + acceptance + scope tests
+        run: python -m unittest discover -s tests -v
+
+      - name: Run token-ignition golden cases
+        run: python adapters/token_ignition/evaluate_golden_cases.py

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cara Lai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -13,6 +13,7 @@
 </p>
 
 <p align="center">
+  <a href="https://github.com/hitome0123/evolution-kernel/actions/workflows/tests.yml"><img src="https://github.com/hitome0123/evolution-kernel/actions/workflows/tests.yml/badge.svg?branch=feat/mvp-observer-scope-hardstops" alt="tests"></a>
   <img src="https://img.shields.io/badge/status-v0%20prototype-orange" alt="Status: v0 prototype">
   <img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python >= 3.10">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
@@ -101,6 +102,17 @@ python3 adapters/token_ignition/evaluate_golden_cases.py
 
 ## CLI Shape
 
+YAML-config mode (the primary MVP entry point — observer + scope + hard stops):
+
+```bash
+python3 -m evolution_kernel.cli \
+  --config /path/to/evolution.yml \
+  --repo /path/to/target-repo \
+  --ledger /path/to/evolution-ledger
+```
+
+Legacy direct-flags mode (still supported for the original golden-case tests):
+
 ```bash
 python3 -m evolution_kernel.cli \
   --repo /path/to/target-repo \
@@ -111,10 +123,120 @@ python3 -m evolution_kernel.cli \
   --evaluator python3 /path/to/evaluator.py
 ```
 
+Reset the persistent hard-stop state (after a halt) without running a loop:
+
+```bash
+python3 -m evolution_kernel.cli --reset --ledger /path/to/evolution-ledger
+```
+
 Each role command receives:
 
 ```text
 --input <json>
 --output <json>
 --worktree <sandbox path>
 ```
+
+## MVP Usage (closed loop with observer, scope, hard stops)
+
+This MVP wires the full closed loop described in the protocol:
+`config -> observe -> plan/execute -> evaluate -> accept/reject -> ledger`.
+
+### 1. Author an `evolution.yml`
+
+```yaml
+mission: "Add a minimal in-scope mutation so the evaluator accepts."
+
+evidence_sources:
+  - type: file
+    path: metrics.json
+  - type: shell
+    command: "bash scripts/status.sh"
+
+mutation_scope:
+  allowed_paths:
+    - "src/"
+
+hard_stops:
+  max_iterations: 3
+  max_consecutive_failures: 2
+
+roles:
+  planner:   ["python3", "bots/planner.py"]
+  executor:  ["python3", "bots/executor.py"]
+  evaluator: ["python3", "bots/evaluator.py"]
+```
+
+`evidence_sources` are read into `observation.json` before the planner runs.
+`mutation_scope.allowed_paths` are enforced after the executor commits — anything
+outside the scope is auto-rejected with `decision.reason = "scope_violation: ..."`.
+`hard_stops` persist across runs in `<ledger>/.evolution_state.json` so a stuck
+loop halts even across CLI invocations.
+
+### 2. Run a single iteration
+
+```bash
+# one-time: install the package (pulls PyYAML, the only runtime dep)
+python3 -m pip install -e .
+
+# one-time: prepare a target repo
+bash examples/demo_target/setup.sh
+
+python3 -m evolution_kernel.cli \
+  --config examples/evolution.yml \
+  --repo  examples/demo_target \
+  --ledger /tmp/ek-ledger
+```
+
+> The `pip install -e .` step is only needed once per environment — it pulls
+> `PyYAML>=6.0` (declared in `pyproject.toml`). After that the three-line
+> command above is reproducible from a clean checkout.
+
+Reset the persistent hard-stop counters when you want to start fresh:
+
+```bash
+python3 -m evolution_kernel.cli --reset --ledger /tmp/ek-ledger
+```
+
+### 3. Inspect the ledger
+
+Every run produces a directory under `<ledger>/runs/<run_id>/` containing the
+full evidence trail:
+
+```text
+goal.json              # legacy mode only
+config.json            # full snapshot of the YAML config (full mode)
+observation.json       # what the observer collected before planning
+plan.json              # planner output
+patch.diff             # diff between baseline and candidate commit
+candidate_commit.txt   # the candidate commit hash inside the sandbox
+evaluation.json        # evaluator output (synthesised on scope_violation)
+decision.json          # accept / reject + reason
+reflection.json        # post-decision summary
+```
+
+### 4. Acceptance criteria -> tests
+
+The six acceptance bullets from issue #1 each map to a test in
+`tests/test_acceptance.py`:
+
+| # | Acceptance bullet | Test |
+| - | --- | --- |
+| 1 | Accept advances `evolution/accepted` | `test_accept_advances_accepted_branch` |
+| 2 | Reject does not advance it | `test_reject_does_not_advance_accepted_branch` |
+| 3 | Mutation scope enforced + violation logged | `test_scope_violation_is_rejected_and_logged` |
+| 4 | Observer writes `observation.json` (file + shell) | `test_observer_writes_observation_with_file_and_shell` |
+| 5 | Hard stops halt then `reset` re-enables | `test_hard_stop_blocks_then_reset_allows_via_cli` |
+| 6 | Ledger contains all required artifacts | `test_ledger_contains_all_required_artifacts` |
+
+### What this MVP intentionally does **not** do
+
+In line with the issue's "out of scope" list:
+
+- No LLM / agent-swarm / dashboard.
+- No PR router and no auto-merge to upstream `main`.
+- No multi-target adapter framework — the only example target is
+  `examples/demo_target/`.
+- No container/process sandbox beyond git worktrees.
+
+These are the natural next steps once the kernel itself is trusted.

README.zh.md

@@ -13,6 +13,7 @@
 </p>
 
 <p align="center">
+  <a href="https://github.com/hitome0123/evolution-kernel/actions/workflows/tests.yml"><img src="https://github.com/hitome0123/evolution-kernel/actions/workflows/tests.yml/badge.svg?branch=feat/mvp-observer-scope-hardstops" alt="tests"></a>
   <img src="https://img.shields.io/badge/status-v0%20prototype-orange" alt="状态：v0 原型">
   <img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python >= 3.10">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
@@ -101,6 +102,17 @@ python3 adapters/token_ignition/evaluate_golden_cases.py
 
 ## CLI 形状
 
+YAML 配置模式（MVP 主入口 — 包含 observer + scope + hard stops）：
+
+```bash
+python3 -m evolution_kernel.cli \
+  --config /path/to/evolution.yml \
+  --repo /path/to/target-repo \
+  --ledger /path/to/evolution-ledger
+```
+
+旧版直接传参模式（保留以兼容原始的 golden-case 测试）：
+
 ```bash
 python3 -m evolution_kernel.cli \
   --repo /path/to/target-repo \
@@ -111,10 +123,119 @@ python3 -m evolution_kernel.cli \
   --evaluator python3 /path/to/evaluator.py
 ```
 
+熔断后清空持久化的 hard-stop 状态（不会触发一次 run）：
+
+```bash
+python3 -m evolution_kernel.cli --reset --ledger /path/to/evolution-ledger
+```
+
 每个角色命令都会收到：
 
 ```text
 --input <json>
 --output <json>
 --worktree <sandbox path>
 ```
+
+## MVP 使用方式（observer + scope + hard stops 闭环）
+
+本 MVP 串起协议描述的完整闭环：
+`config -> observe -> plan/execute -> evaluate -> accept/reject -> ledger`。
+
+### 1. 编写 `evolution.yml`
+
+```yaml
+mission: "Add a minimal in-scope mutation so the evaluator accepts."
+
+evidence_sources:
+  - type: file
+    path: metrics.json
+  - type: shell
+    command: "bash scripts/status.sh"
+
+mutation_scope:
+  allowed_paths:
+    - "src/"
+
+hard_stops:
+  max_iterations: 3
+  max_consecutive_failures: 2
+
+roles:
+  planner:   ["python3", "bots/planner.py"]
+  executor:  ["python3", "bots/executor.py"]
+  evaluator: ["python3", "bots/evaluator.py"]
+```
+
+`evidence_sources` 在 planner 运行前被读入 `observation.json`。
+`mutation_scope.allowed_paths` 在 executor 提交后被强制校验 —— 范围之外
+的任何改动都会被自动 reject，`decision.reason` 写为 `scope_violation: ...`。
+`hard_stops` 通过 `<ledger>/.evolution_state.json` 跨 run 持久化，循环卡死
+时即使重启 CLI 也会被拦截。
+
+### 2. 跑一次实验
+
+```bash
+# 一次性：安装包（PyYAML 是唯一运行时依赖，已在 pyproject.toml 声明）
+python3 -m pip install -e .
+
+# 一次性：准备目标仓库
+bash examples/demo_target/setup.sh
+
+python3 -m evolution_kernel.cli \
+  --config examples/evolution.yml \
+  --repo  examples/demo_target \
+  --ledger /tmp/ek-ledger
+```
+
+> 上面 `pip install -e .` 每个环境只需要做一次。之后那三行 CLI 命令是
+> 干净 checkout 下可复现的。
+
+需要重置熔断器从头来过：
+
+```bash
+python3 -m evolution_kernel.cli --reset --ledger /tmp/ek-ledger
+```
+
+### 3. 检查 ledger
+
+每一次 run 都会在 `<ledger>/runs/<run_id>/` 下产出完整的证据链：
+
+```text
+goal.json              # 仅 legacy 模式
+config.json            # 完整 YAML 配置快照（full 模式）
+observation.json       # planning 之前 observer 收集到的证据
+plan.json              # planner 输出
+patch.diff             # baseline 与 candidate commit 之间的 diff
+candidate_commit.txt   # sandbox 中 candidate commit 的 hash
+evaluation.json        # evaluator 输出（scope_violation 时由 Governor 合成）
+decision.json          # accept / reject + 原因
+reflection.json        # 决策后的总结
+```
+
+### 4. 验收标准 → 测试映射
+
+issue #1 中六条验收标准在 `tests/test_acceptance.py` 中各对应一个测试：
+
+| # | 验收要求 | 测试 |
+| - | --- | --- |
+| 1 | accept 推进 `evolution/accepted` | `test_accept_advances_accepted_branch` |
+| 2 | reject 不推进 | `test_reject_does_not_advance_accepted_branch` |
+| 3 | 强制 mutation scope + 记录违规 | `test_scope_violation_is_rejected_and_logged` |
+| 4 | observer 写出 `observation.json`（file + shell） | `test_observer_writes_observation_with_file_and_shell` |
+| 5 | hard stops 触发熔断后 `--reset` 恢复 | `test_hard_stop_blocks_then_reset_allows_via_cli` |
+| 6 | ledger 包含全部必需 artifact | `test_ledger_contains_all_required_artifacts` |
+
+此外 `tests/test_scope.py` 单独钉死了 `allowed_paths` matcher 的边界语义
+（递归 / 精确匹配 / 兄弟名碰撞 / `..` 逃逸 / 空作用域 等）。
+
+### 本 MVP 有意**不做**的内容
+
+按照 issue 的“不要做”清单：
+
+- 不做 LLM / agent-swarm / dashboard。
+- 不做 PR router，不做自动 merge 到上游 `main`。
+- 不做多目标适配器框架 —— 唯一示例目标是 `examples/demo_target/`。
+- 不做超出 git worktree 的容器/进程级沙箱。
+
+这些都是在内核本身被信任之后才适合做的下一步。