Reefine: close the loop with the person who asked

AGENTS.md

@@ -181,6 +181,21 @@ Prefer concrete alternatives such as:
 
 When adding new concepts, reuse existing repository vocabulary before inventing new terminology.
 
+Prefer concrete names over metaphors in code, UI text, logs, and documentation:
+
+- Use `check` for a condition, `validation` for checking validity, and
+  `evaluation` for running and scoring tasks instead of `gate`.
+- Use `result` for an outcome, `selection_result` for a candidate selection,
+  and `review_result` for a review instead of `verdict`.
+- Name the actual operation or quantity: `evaluation_score`, `evaluation_tasks`,
+  `result_html`, and "passed the checks" are clearer than metaphorical names.
+- Apply terminology changes to identifiers, serialized keys, producers, consumers,
+  tests, and documentation. New records should use the preferred keys. Preserve
+  older records and callers with targeted fallback reads or API aliases where
+  compatibility is needed; keep those legacy names at the boundary rather than
+  spreading them through new code or displayed labels.
+- Keep standard technical names such as neural-network gates and third-party identifiers.
+
 ## Tests and checks
 
 Start with the smallest existing suite that exercises the changed behavior.

README.i18n.yaml

@@ -1,5 +1,5 @@
 # Last human-confirmed consistent README pair.
 # After updating and reviewing both files, run:
 #   python .github/scripts/check_readme_i18n.py --write
-README.md: c2f923dbf4b5583172912b90217939b868bcf9d7
-README.zh.md: 046451c97c9b4480eafc7cb8e1b0b894daa9c86b
+README.md: 43c21af1ce43a95949a7e308618a26b68458b60e
+README.zh.md: 32c53b40bdc8fc935314e463bdbf585f2e6a7a0d

README.md

@@ -199,47 +199,51 @@ current version without restarting Reef.
 
 ### Harness-evolving deployment
 
-Improve harness skills using a model API instead of GPUs.
+Refine a coding harness from plain-language asks, using a model API instead of GPUs.
 
-The harness evolve recipe includes a deployment configuration; specify the provider URL
-and model. From your Reef checkout and activated Python environment:
+Reefine is the built-in harness-refinement recipe and includes a deployment
+configuration; specify the provider URL and model. From your Reef checkout and
+activated Python environment:
 
 ```bash
-reef serve --recipe harness-evolve \
+reef serve --recipe reefine \
   --inference.upstream-url http://127.0.0.1:11434 \
   --inference.upstream-model gemma4:26b
 ```
 
 The example connects to a local Ollama server. For another provider, change
 `--inference.upstream-url` and `--inference.upstream-model`, and set
-`REEF_UPSTREAM_API_KEY` if authentication is required. With this configuration, Reef listens on
-`127.0.0.1:8900` with no token and keeps its state under `.reef/harness-evolve/`. To change anything
-else, copy [the deployment configuration](reef/service/profiles/harness-evolve.yaml) and pass
+`REEF_UPSTREAM_API_KEY` if authentication is required. With this configuration, Reef
+listens on `127.0.0.1:8901` with token `reef-local` and keeps its state under
+`.reef/reefine/` (`--recipe harness-evolve`, the former name, starts the same
+configuration). To change anything else, copy
+[the deployment configuration](reef/service/profiles/reefine.yaml) and pass
 your copy with `-c`.
 
 In another terminal with the same Python environment activated (the install
-bakes that terminal's `python3` into `reef-pi`), install the harness and run a task:
+bakes that terminal's `python3` into `reef-pi`), create a scenario, install the
+harness, and ask for a change:
 
 ```bash
-curl -fsS 'http://127.0.0.1:8900/reef/harness/install?adapter=pi' | bash
-reef-pi -p "fix the failing test in auth.py"
+export REEF_TOKEN=reef-local
+curl -fsS -H "Authorization: Bearer $REEF_TOKEN" -H "Content-Type: application/json" \
+  -d '{"name": "my-harness"}' http://127.0.0.1:8901/reef/scenarios
+curl -fsS -H "Authorization: Bearer $REEF_TOKEN" -H "x-reef-scenario: my-harness" \
+  'http://127.0.0.1:8901/reef/harness/install?adapter=pi' | bash
 
-# After running your tests, report the actual result:
-reef-pi report --score 0 --feedback "missed the empty-token case"
+reef-pi harness "when I ask you to fix a bug, reproduce it with a failing test first"
 ```
 
-To change the model, restart `reef serve` with another `--inference.upstream-model`
-and rerun the install command before `reef-pi`: installation writes the model ID into the
-local harness configuration.
-
-Failed reports trigger a candidate skill update. Reef evaluates it against the
-current harness on the tutorial's three coding tasks and publishes it only if
-it wins. See the [tutorial](tutorials/evolve-your-harness/README.md) to customize the
-tasks and evaluation.
-
-To ask for a harness change in plain words and see the whole path from the ask to the install, run the [Reefine tutorial](tutorials/reefine/README.md).
-
-Reefine ships with `reef-infra`: start it with `reef serve --recipe reefine --model ollama/gemma4:26b`.
+Inside a `reef-pi` session, `/reef-harness <text>` files the same ask. The served
+model writes the change as a skill, a rules entry, an agent command, or a pi
+extension, and the next session's update notice offers the install; review the
+versions with `/reef-versions`, and promote an extension with
+`/reef-versions <step> promote` before it is offered. To change the model, restart
+`reef serve` with another `--inference.upstream-model` and rerun the install
+command: installation writes the model ID into the local harness configuration.
+See the [Reefine tutorial](tutorials/reefine/README.md) for scripted bug-fix and
+research demos and the [Reefine guide](docs/user-guide/recipes/reefine.rst) for
+configuration.
 
 ## 📚 Recipes and examples
 

README.zh.md

@@ -191,43 +191,35 @@ reef.post(
 
 ### Harness 进化部署
 
-使用模型 API 改进 harness 技能，无需 GPU。
+用模型 API（而非 GPU）根据自然语言请求改进编码 harness。
 
-harness 进化 recipe 自带部署配置，只需指定 provider URL 和模型。在 Reef checkout 和已激活的 Python 环境中：
+Reefine 是内置的 harness 改进 recipe，自带部署配置；只需指定 provider URL 和模型。在 Reef checkout 和已激活的 Python 环境中：
 
 ```bash
-reef serve --recipe harness-evolve \
+reef serve --recipe reefine \
   --inference.upstream-url http://127.0.0.1:11434 \
   --inference.upstream-model gemma4:26b
 ```
 
 该示例连接本地 Ollama 服务。使用其他 provider 时，修改
 `--inference.upstream-url` 和 `--inference.upstream-model`；需要认证时设置
-`REEF_UPSTREAM_API_KEY`。
-使用此配置时，Reef 监听 `127.0.0.1:8900`，不设 token，状态保存在 `.reef/harness-evolve/`。
-需要修改其他内容时，复制[该部署配置](reef/service/profiles/harness-evolve.yaml) 并用 `-c` 传入你的副本。
+`REEF_UPSTREAM_API_KEY`。使用此配置时，Reef 监听 `127.0.0.1:8901`，token 为 `reef-local`，状态保存在
+`.reef/reefine/`（`--recipe harness-evolve` 是旧名称，启动的是同一个配置）。
+需要修改其他内容时，复制[该部署配置](reef/service/profiles/reefine.yaml) 并用 `-c` 传入你的副本。
 
-在另一个已激活同一 Python 环境的终端中（安装会把该终端的 `python3` 写入 `reef-pi`）安装 harness 并运行任务：
+在另一个已激活同一 Python 环境的终端中（安装会把该终端的 `python3` 写入 `reef-pi`），创建 scenario、安装 harness 并提出修改请求：
 
 ```bash
-curl -fsS 'http://127.0.0.1:8900/reef/harness/install?adapter=pi' | bash
-reef-pi -p "fix the failing test in auth.py"
+export REEF_TOKEN=reef-local
+curl -fsS -H "Authorization: Bearer $REEF_TOKEN" -H "Content-Type: application/json" \
+  -d '{"name": "my-harness"}' http://127.0.0.1:8901/reef/scenarios
+curl -fsS -H "Authorization: Bearer $REEF_TOKEN" -H "x-reef-scenario: my-harness" \
+  'http://127.0.0.1:8901/reef/harness/install?adapter=pi' | bash
 
-# After running your tests, report the actual result:
-reef-pi report --score 0 --feedback "missed the empty-token case"
+reef-pi harness "when I ask you to fix a bug, reproduce it with a failing test first"
 ```
 
-要更换模型，用另一个 `--inference.upstream-model` 重启 `reef serve`，并在 `reef-pi` 之前重新执行安装命令：
-安装过程会将模型 ID 写入本地 harness 配置。
-
-失败报告会触发候选技能更新。Reef 会在教程的三个编程任务上对候选技能和当前 harness
-进行评估，仅在候选胜出时才发布。如何自定义任务和评估方式，请参阅
-[教程](tutorials/evolve-your-harness/README.md)。
-
-要用一句话向 harness 提出修改需求，并看到从提出到安装的完整流程，请运行 [Reefine 教程](tutorials/reefine/README.md)。
-
-Reefine 随 `reef-infra` 内置提供：运行 `reef serve --recipe reefine --model ollama/gemma4:26b` 即可启动。
-
+在 `reef-pi` 会话内，`/reef-harness <text>` 提交同样的请求。所服务的模型把修改写成一个 skill、一条 rules 条目、一个 agent 命令或一个 pi extension，下一个会话启动时的更新提示会提供安装；用 `/reef-versions` 查看各版本，extension 需要先用 `/reef-versions <step> promote` 提升后才会被提供安装。要更换模型，用另一个 `--inference.upstream-model` 重启 `reef serve` 并重新执行安装命令：安装过程会将模型 ID 写入本地 harness 配置。脚本化的 bug 修复与研究演示见 [Reefine 教程](tutorials/reefine/README.md)，配置说明见 [Reefine 指南](docs/user-guide/recipes/reefine.rst)。
 
 ## 📚 Recipes 与示例