Skip to content

Commit c772096

Browse files
tzhouamclaude
tzhouam
and
claude
committed
doc(spec): re-verify the specs the harness backend touches
check_spec_freshness --strict flagged 5 pages STALE: config, rebase_engine, engine/steps/rebase_v3, providers/cursor and tool_bridge all changed after they were last verified. Records the contracts rather than only bumping dates, including the three faults that only a live harness run exposed: build_backends(repo=) takes a repo ROOT PATH and not a name (a name makes the test tools fail closed while the module still reports done); the tier model must never be forwarded to a harness CLI; and generated MCP tool functions need keyword-only params with unset optionals dropped. Also records that cursor's registry capabilities lack builtin_tools_off, so its native tools bypass the bridge and are only RECORDED, not contained. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent e696998 commit c772096

5 files changed

Lines changed: 42 additions & 5 deletions

File tree

‎doc/architecture/SPEC/config.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# config.py —— 规范
22

3-
<!-- verified-against: 2026-09-08 -->
3+
<!-- verified-against: 2026-09-19 -->
44

55
`LOC ~658 · 配置 · refactor-status: oversized`
66

@@ -79,3 +79,13 @@ provider 的缺省模型必须在**这一处**解析，否则 `ResolvedTarget.mo
7979
如果再增长，请分组成嵌套 settings 模型（`LLMSettings` / `PushSettings` /
8080
`ReviewSettings` / `BackendSettings`），**而不是拆文件** —— 调用点依赖"一个 `Settings`
8181
对象到达每个 `StepContext`"。
82+
83+
## rebase 后端抽象（2026-09-19）
84+
85+
`rebase_backend`（默认 `api`）选择跑 rebase **module agent** 的 provider：
86+
`api` 为进程内 Anthropic tool-use 循环，其余为 harness provider id
87+
（`cursor` / `claude-code` / `codex`）。`rebase_backend_model` 是 harness
88+
**内部**的模型 id（如 `cursor-grok-4.6-high-fast`）。
89+
90+
注意：tier 模型名指向 RAW-API 模型，对 harness CLI 无意义，**绝不**转发过去；
91+
为空时回落到 `strict_backend_model`，再回落到 harness 自身默认值。

‎doc/architecture/SPEC/engine/steps/rebase_v3.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# engine/steps/rebase_v3.py —— 规范
22

3-
<!-- verified-against: 2026-09-06 -->
3+
<!-- verified-against: 2026-09-19 -->
44

55
`LOC ~2204 · step 库（v3 rebase 装配层） · refactor-status: oversized`
66

@@ -90,3 +90,11 @@ import（见重构备注）。
9090
违例；对 `.workspace._guard_clean_rebase` 的直接 import 是另一条。拆分时
9191
substate + `state_updates` 双写、模块短路/串行锁的 crash-window 契约**必须**
9292
原样保留（resume 完整性测试护住）。
93+
94+
## harness 后端派发（2026-09-19）
95+
96+
module agent 可派发到 harness provider（`settings.rebase_backend`）。
97+
harness 会话通过 MCP tool bridge 拿到同一套工具面，plan gate 在派发处强制。
98+
`build_backends(repo=)` 收的是仓库 **ROOT 路径**（→ `TestRunner(repo_root=)`），
99+
不是仓库名：传名字会让 run_pytest/run_precommit/reproduce 以
100+
`FileNotFoundError` 静默失效，module 却报告完成。

‎doc/architecture/SPEC/providers/cursor.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# providers/cursor.py —— 规范
22

3-
<!-- verified-against: 2026-08-18 -->
3+
<!-- verified-against: 2026-09-19 -->
44

55
`LOC ~207 · harness transport（Cursor 订阅） · refactor-status: ok`
66

@@ -38,3 +38,10 @@ stdlib + `.base` + `.registry` + `..agent_loop.AgentOutcome` + `..llm` 的类型
3838
## 重构备注
3939
这套调用形状是由 Composer 评测臂（`eval/dataset/run_cursor_arm.py`）验证出来的；
4040
**如果那个脚本和这个 transport 发生漂移，评测臂就不再是在测量产品了。**
41+
42+
## 作为 rebase module-agent 后端（2026-09-19）
43+
44+
`REBASE_BACKEND=cursor` 时，cursor-agent 承担 rebase module agent。
45+
registry 给 cursor 的能力是 `{mcp_tools, usage_reporting}`——**没有**
46+
`builtin_tools_off`，所以 cursor 自带工具会绕过 bridge：bridged 调用受
47+
scope 约束，native 调用只被**记录**。

‎doc/architecture/SPEC/rebase_engine.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# rebase_engine/ —— 规范
22

3-
<!-- verified-against: 2026-09-06 -->
3+
<!-- verified-against: 2026-09-19 -->
44

55
`LOC ~7500（26 个模块） · repo-rebase-v3 的原生 rebase 引擎 · refactor-status: ok`
66

@@ -132,3 +132,8 @@ worktree）、`test_assembly.py`（tools/loop/module/prompt/wheel）、
132132
是 PR4d 执行后的退役候补（"无永久双 store 世界"）。docstring 里的
133133
choke-point 编号（agent_loop/rebase_tools 写"C5"）落后于 `_CONSTRAINTS.md`
134134
目录（工具 choke point = C3）—— 值得统一，改注释不改行为。
135+
136+
## module_rebase 的 harness 路径（2026-09-19）
137+
138+
`module_rebase` 既可跑进程内 agent 循环，也可把一个 module 交给 harness
139+
provider；两条路径共用同一 prompt、同一工具面与同一 plan gate。

‎doc/architecture/SPEC/tool_bridge.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# tool_bridge.py —— 规范
22

3-
<!-- verified-against: 2026-08-18 -->
3+
<!-- verified-against: 2026-09-19 -->
44

55
`LOC ~308 · 面向 harness 会话的 scoped 工具 MCP server · refactor-status: ok`
66

@@ -48,3 +48,10 @@ knowledge/repo-map 工厂。
4848
因为它捆绑的运行时不带 MCP client，拿到无法履约的 spec 时会记一条 `capability_gap`。
4949
任何"这次 run 走了工具桥"的说法，都必须**对照那个标志核实**，
5050
而不是从"后端是 harness"推定。
51+
52+
## 向 harness 会话提供 rebase 工具面（2026-09-19）
53+
54+
bridge 把 run 的 20 工具面 + `doc_search`/`doc_read` 暴露给 harness 会话。
55+
生成的 MCP 工具函数必须是 **keyword-only**（schema 会交错 required/optional），
56+
零属性工具不能带裸 `*`，且必须**丢掉**未设置的 optional——传 None 会打断
57+
每一次 `read_file`。失败的 bridged 调用记录失败**原因**。

0 commit comments

Comments
 (0)