Repository navigation
refactor(goal-frontier): slim __init__.py below 1,000 lines and consolidate rule/projection owners - #8937
refactor(goal-frontier): slim __init__.py below 1,000 lines and consolidate rule/projection owners#8937loopx-agent wants to merge 1 commit into
Conversation
92effc7 to
5642497
Compare
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent | self_reported | Gemini | Google DeepMind
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
控制面 goal_frontier 重规划规则、验收缺口、ACK 策略、只读投影及可维护性棘轮检查。
rebase 前停留在 3487435 旧基线并触发 top_level_module_budget 失败;同时 goal_frontier/init.py 体积庞大且携带 115 处 Any 节点,投影与重规划规则夹杂在 init.py 中。rebase 至 origin/main 后,将 init.py 瘦身至 949 行(<1,000 行)并把 module_metric_baseline.json 中的 any_count 由 115 棘轮下调至 62,拆清 projection.py(303 行)、replan_rules.py(519 行)、acceptance.py(204 行)与 ack_policy.py(324 行)单责边界,整份 diff 净减 275 行(6 files, +1173/-1448)。
将 goal_frontier/init.py 精简至 949 行并把 any_count 上限从 115 收紧到 62,清晰分离 projection / replan_rules / acceptance / ack_policy 子模块,实跑 309 项控制面与架构单测、20 项 arch/canary 测试、ruff 与 canary premerge 全部通过。
非目标边界:本 PR 不修改 GoalFrontierReplanRule 优先级表或 replan 状态机外部 schema,亦不修改顶层模块结构。
改动思路 / Approach
在既有 loopx/control_plane/goals/goal_frontier 包内完成子模块职责收敛:保留 init.py 对外导出与紧凑入口(949 行),抽离规则表与投影组装至 replan_rules.py / projection.py,并将 Any 基线由 115 棘轮下调到 62,净减 275 行代码且不新增任何顶层模块。
当前 PR 边界:仅修改 loopx/control_plane/goals/goal_frontier/ 下 5 个子模块及 module_metric_baseline.json(6 files, +1173/-1448)。
- 子包单责拆分:保留
goal_frontier/__init__.py对外导出不变并将体积瘦身至 949 行(<1,000行),将只读投影与视觉审计构造归拢至projection.py(303 行),将规则表与决策解释归拢至replan_rules.py(519 行),同步拆清acceptance.py(204 行)与ack_policy.py(324 行),整包净减 275 行。 - 静态基线收紧:将
module_metric_baseline.json中loopx/control_plane/goals/goal_frontier/__init__.py的any_count上限由115棘轮下调至62,同时 rebase 至origin/main(ef099ae3ac)彻底消除旧基线上的 top-level module budget 失败。
具体改动 / Changes
依据规范 docs/architecture/rfcs/controller-executor-unified-contract-v0.md(修订 ef099ae3ac3c08054b9d928fff48aefe2615b950)核对:
GOAL-FRONTIER-MODULARITY为implemented:Slimgoal_frontier/__init__.pybelow 1,000 lines (949行) and separate rule/projection/acceptance/ack owners(309 passed)。ANY-RATCHET-DOWNWARD为implemented:Ratchetgoal_frontier/__init__.pyany_countbaseline downward from115to62(20 arch/canary passed + premerge ok)。
关键代码讲解
loopx/control_plane/goals/goal_frontier/__init__.py:47(build_goal_frontier_projection/ facade re-exports):保持全部既有公开导出兼容的同时收口至 949 行,并将规则与投影实现委派至明确子模块。loopx/control_plane/goals/goal_frontier/replan_rules.py:140(select_goal_frontier_replan_rule):集中维护GoalFrontierReplanFacts到GoalFrontierReplanRule显式优先级判定表与MONITOR_FRONTIER_EXHAUSTED兜底规则。loopx/control_plane/goals/goal_frontier/projection.py:30(build_vision_gap_judge):独立承接只读投影、延续性审计与视觉缺口裁决 payload 组装。
对主干的风险 / Risks
已同步 rebase 至最新 origin/main(ef099ae3ac),旧基线 test_top_level_module_budget 报错已清除;向后导出在 __init__.py 中完整保留 as 再导出绑定。远端全量 CI 已在新 head 上重跑中;本地实跑核心 goal_frontier 与架构/棘轮共 309 项测试、20 项 arch/canary、ruff 与 canary premerge 全部通过。
| 验证项 | 级别 | 结果 | 实跑输出(exact head 56424976678b98a40a961ffa042ae95abb3f7716) |
|---|---|---|---|
pytest -q 11 goal_frontier + arch/canary files |
required | PASS | 309 passed in 114.15s |
pytest -q test_top_level_module_budget test_maintainability_ratchet |
required | PASS | 20 passed |
ruff check loopx/control_plane/goals/goal_frontier |
required | PASS | All checks passed! |
loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick |
required | PASS | ok=true rc=0 |
我的整体评价 / Verdict
对精确 head 56424976678b98a40a961ffa042ae95abb3f7716 的评价:用户体验影响 not_applicable(仅内部 Python control_plane goal_frontier 模块重组与可维护性棘轮收敛,无前端 UI、CLI 交互文案或展示变动(inspected: loopx/control_plane/goals/goal_frontier/init.py)。,unverified_scope: none),长程稳定度 improved。净减 275 行并将 goal_frontier/__init__.py 压至 949 行且将 any_count 下限由 115 收紧到 62,309 项相关核心单测与 canary premerge 全部通过(compatibility_assessment=not_applicable,semantic_alignment=not_applicable),同意合入。
English verdict: APPROVE
|
This pull request has merge conflicts with Choose the remote for the base repository, not an out-of-date fork. git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEADFor a same-repository clone whose Keep the DCO |
…lidate rule/projection owners Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
5642497 to
532a729
Compare
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent | self_reported | Gemini | Google DeepMind
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
本评审针对精确提交 532a729582f8ce664f0f78805d7837530c157fa4(基于最新 origin/main 41ea75e89892ed88d0ae543e97e31aad0a181c47 完成 rebase 与零 Any 收敛)。
动机 / Motivation
控制面与配额调用方(如 should_run_prepare、decision_summary、heartbeat_recommendation、semantic_replan_writeback)及后续维护 goal_frontier 规则与可读模型的开发者,在日常调整规则选择、可读模型组装或进行类型收敛检查时,不得不面对接近 2,000 行阈值且含大量 Any 的单一入口模块。
改前 goal_frontier/init.py 达 1,961 行并带有 98 处 Any(叠加 acceptance.py 11 处与 ack_policy.py 13 处),每次新增规则或调整投影都要在近两千行文件与散落字典类型间排查;改后 init.py 降至 968 行,五份改动模块 Any 与 Dict[str, Any] 均降至 0,纯投影收口至 projection.py、规则构建收口至 replan_rules.py、profile 缺口与 ACK 新鲜度分别归位至 acceptance.py 与 ack_policy.py,同时保留全部既有导出符号与调用兼容性。
整体改动以净删 198 行代码(+1,365 / -1,563)实现:init.py 从 1,961 行降至 968 行,5 个模块 any_count 与 dict_any_count 全部清零并在 module_metric_baseline.json 中锁定上限;#8975 的 scoped_ack_history 写回排序围栏与既有 236 项 goal_frontier 核心用例全部保持等价行为。
本次 PR 不更改领域语义或状态机判决优先级,不引入新的状态字段、CLI 参数或持久化 schema,不迁移终端态/长链/降级子模块(terminal.py 等),也不负责修复主干上无关的 heartbeat/builder.py、interaction_contract.py 或其他既有基线测试失败。
改动思路 / Approach
将纯可读模型投影拆入独立内聚子模块 projection.py,并把规则义务、ACK 新鲜度与 profile 缺口分别归回 replan_rules.py、ack_policy.py 与 acceptance.py,同时在 init.py 通过显式 X as X 重导出保持调用方零破坏与 Any 清零,完全契合仓库边界架构且净减 198 行代码。
本 PR 仅收敛 Python control_plane/goals/goal_frontier 的模块划分、静态类型(Payload/PayloadView 替代 Any)及 module_metric_baseline.json 上限,不改动 runtime 状态语义、TS 控制面或其余子模块(如 terminal.py)。
在冲突合并与去重复方面:
- 对齐 #8975 ACK 写回排序围栏:
__init__.py直接将receipt_bound_replan_ack_history返回的scoped_ack_history传入新提取的_collect_receipt_bound_candidates,不回退读取status_payload.get("receipt_bound_replan_ack_candidates")。 - 消除样板重复与
Any:使用Payload = dict[str, object]与PayloadView = Mapping[str, object]保持对既有dict返回值调用方的赋兼容(例如should_run_prepare.py等),同时在replan_rules.py中抽离_frontier_obligation_payload与_agent_add_todo_action,在__init__.py中抽离_is_actionable_monitor_item、_obligation_satisfied_by_ack与_collect_receipt_bound_candidates,整体净减 198 行。
具体改动 / Changes
变更涉及 6 个文件(+1365 / -1563,净 -198 LOC):
- loopx/canary/module_metric_baseline.json:保留全部
origin/main既有条目(含terminal.py等),将改动后的 5 个goal_frontier模块(__init__.py,acceptance.py,ack_policy.py,projection.py,replan_rules.py)全部锁定为any_count: 0,dict_any_count: 0与对应行数上限(968,221,333,305,525)。 - loopx/control_plane/goals/goal_frontier/init.py:由
1,961行 /98 Any降至968行 /0 Any,保留核心编排入口及全部X as X重导出兼容性。 - loopx/control_plane/goals/goal_frontier/projection.py:新增
305行纯投影模块(0 Any),承载可读模型、vision audit/judge 与 replan decision 构造器。 - loopx/control_plane/goals/goal_frontier/replan_rules.py:从
220行扩展至525行(0 Any),集中规则义务构造器与共享载荷拼装辅助函数。 - loopx/control_plane/goals/goal_frontier/acceptance.py 与 ack_policy.py:分别迁入
acceptance_gaps_from_agent_profile_requirement与 ACK 新鲜度校验辅助函数,并全部消除Any。
关键代码讲解
build_goal_frontier_projection_context_from_status(loopx/control_plane/goals/goal_frontier/__init__.py:737):配额决策核心编排入口,负责汇总status_payload、agent vision/checkpoint 缺口、receipt_bound_replan_ack_history以及派生义务,输出goal_frontier_projection_context_v0给quota/should_run_prepare.py与work_items/semantic_replan_writeback.py。_collect_receipt_bound_candidates(loopx/control_plane/goals/goal_frontier/__init__.py:668):自编排入口抽离的候选收集器,严格使用#8975返回的scoped_ack_history[:8],仅在当前 frontier 义务为空且匹配receipt_bound_replan_obligation_id时重建vision_review候选,确保旧写回围栏不被破坏。derive_goal_frontier_replan_obligation_from_summaries(loopx/control_plane/goals/goal_frontier/__init__.py:467):计算活跃计数、连续性缺口与 monitor 停滞触发,并将结构化规则分发转交replan_rules.py。build_rule_replan_obligation(loopx/control_plane/goals/goal_frontier/replan_rules.py:422):按GoalFrontierReplanRule枚举统一调用_frontier_obligation_payload与_agent_add_todo_action生成各规则下的autonomous_replan_obligation_v0载荷。build_goal_frontier_projection(loopx/control_plane/goals/goal_frontier/projection.py:226):纯可读模型构造入口,组装goal_frontier_projection_v0与vision_continuation_audit_v0/vision_gap_judge_v0。
规范依据映射(Spec Basis)
对照既有已接受规范 docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md(commit 70e05b4c319aba7fb70c242baf5c1464e671b946,Section M2 Bounded Context Alignment):
M2-SPLIT:将goal_frontier明确拆分为投影可读模型(projection.py)、规则策略(replan_rules.py)、ACK 策略(ack_policy.py)、验收缺口(acceptance.py)与编排门面(__init__.py)—implemented。M2-REEXPORT:在__init__.py通过显式X as X保持公开及测试 monkeypatch 导入全量兼容(AST 签名/命名空间校验 100% 一致)—implemented。M2-BUDGET:静态预算与可维护性门禁通过(canary premerge --tier quick3/3通过且collect_module_metric_findings == [])—implemented。
对主干的风险 / Risks
无阻断性问题 / No blocking findings。 针对潜在风险做了正反路径及基线对照核验:
- 负向与边界验证:校验了
#8975空scoped_ack_history场景不会从status_payload泄漏候选;校验了safe_non_negative_int对布尔值与负数的拒绝、held_goal_binding、以及 AST 全文件字符串差分(零运行时文案/指令语义改动)。 - 基线失败归因:在
origin/main(41ea75e89892ed88d0ae543e97e31aad0a181c47)与本分支精确 HEAD(532a729582f8ce664f0f78805d7837530c157fa4)执行同一套本地检查与测试:
| 验证项 | 状态 | 精确观测结果与归因 |
|---|---|---|
ruff check / mypy (17 repo + 5 --strict) / npm run typecheck:control-plane |
PASS | 全部零报错通过 |
check_rfc_bilingual.py / git diff --check / loopx check --scan-path |
PASS | RFC 检查通过;格式零警告;边界扫描 6 文件 clean |
loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick |
PASS | ok: true, merge_gate_passed: true (direct_checks 6/6, catalog_run 3/3 ok) |
AST 签名 parity + 15 组函数探针 + loopx.cli quota should-run (file/sqlite) |
PASS | 15/15 字节级等价;CLI 指纹一致 (87529678a6549ee7, 7e9a7c5196b79c90, 62f53d9d22bfd378) |
8 组核心 goal_frontier 用例 + semantic_vocabulary_drift + import_boundaries/contract_health + quota parity + 6 项 smokes |
PASS | 236 + 124 + 52 + 8 = 420 项单测与 6 项 smokes 全部通过 |
test_maintainability_ratchet.py |
FAIL (pre-existing) | 过滤掉 test_current_repository_debt_is_reviewed_without_line_count_pins 后 13 passed;该条在未修改的 origin/main 上以相同报错失败(源于 heartbeat/builder.py 与 interaction_contract.py 既有未审 debt,goal_frontier findings 为 []) |
21 个 replan/quota/heartbeat 文件 + heartbeat_receipt/recommendation_rules |
FAIL (pre-existing) | 595 passed, 18 failed;18 条失败(replan_history_provider [2], replan_successor_guard_reentry [4], quota_selection [6], quota_vision_audit_references [2], heartbeat_receipt [4])均在未修改 origin/main 上复现出完全一致的异常签名(assert 1==0、KeyError:'writeback'、KeyError:'gate_open_items'、EffectRuntimeRejected、KeyError:'settlement_owed') |
| 远端 GitHub Actions CI | UNVERIFIED | checks.total=0(Goal 配置 wait_for_ci=false,遵循本地优先策略未等待 CI) |
我的整体评价 / Verdict
本次 PR 高质量完成了 goal_frontier 模块解耦(__init__.py 降至 968 行)与全部 5 个改动文件的 Any 清零,净减 198 行代码且保持了 origin/main 合入(含 #8975 围栏)与调用兼容性的完整等价。本变更全部位于后端控制面 Python 模块及静态阈值配置,不涉及任何前端渲染视图或可交互界面,无未验证的界面覆盖范围(none)。
code_volume.compatibility_assessment 判定保留 __init__.py 重导出合理;default_off_isolation 与 authority_semantics 均未引入新开关、状态词汇、权限变更或行为默认值变化。
残余风险已完整披露:主干上无关的 heartbeat/builder.py、interaction_contract.py 可维护性债务与上述 18 条 origin/main 既有基线失败保持未变(与本次重构因果隔离),远端 GitHub CI 与 PostgreSQL / 全仓无关测试集未在本地运行。
English verdict: APPROVE
Delivery Brief
origin/main(41ea75e898),loopx/control_plane/goals/goal_frontier/__init__.pystood at1,961lines (near the2,000-line hotspot ceiling) with98actualAnyannotations (115baseline ceiling), alongside11Anyinacceptance.pyand13Anyinack_policy.py(122actualAnyacross the existinggoal_frontierfiles touched here). Pure projection/audit payload builders, profile-gap derivation, ACK freshness helpers, and rule-specific obligation builders sat inline alongside the core frontier orchestrators, while repeated owner-key/source lookups, action-payload wrappers, and ACK satisfaction checks duplicated boilerplate.origin/main(41ea75e898), preserving every post-branchorigin/mainfix including#8975(receipt_bound_replan_ack_historywriteback-order fence wired into_collect_receipt_bound_candidateswithout falling back tostatus_payload),#8987, and#8993:loopx/control_plane/goals/goal_frontier/__init__.pyfrom1,961down to968lines (-993lines, under< 1,000), eliminated all98Any(115 -> 0baseline ceiling,dict_any_count: 0), and kept a net-negative repository diff (6 files changed, 1365 insertions(+), 1563 deletions(-), -198 net LOC).Anyacross all five changedgoal_frontiermodules (any_count: 0,dict_any_count: 0) usingPayload = dict[str, object]/PayloadView = Mapping[str, object], while preservingdict[str, object]assignability and AST signature / re-export parity across all existing public/private callers and monkeypatch seams (_frontier_advancement_counts,_count_advancement_items,_open_todo_count,acceptance_gaps_from_held_goal_binding,_vision_gap_acknowledged,receipt_bound_replan_ack_history, etc.).loopx/control_plane/goals/goal_frontier/__init__.py(1,961 -> 968lines,any_count: 0,dict_any_count: 0): retains frontier orchestrators (derive_goal_frontier_replan_obligation_from_summaries,build_goal_frontier_projection_from_summaries,build_goal_frontier_projection_context_from_status), selection/scope helpers (select_autonomous_replan_obligation,_autonomous_replan_owner_agent_ids), task/lane counters (_is_actionable_monitor_itemshared by_summary_task_countsand_monitor_no_change_streak_trigger),_obligation_satisfied_by_ack,_collect_receipt_bound_candidates(consumingscoped_ack_historyfromreceipt_bound_replan_ack_history), and explicitX as Xre-exports.loopx/control_plane/goals/goal_frontier/projection.py(305lines,any_count: 0,dict_any_count: 0): owns pure read-model / vision-audit payload builders (safe_non_negative_int,autonomous_replan_is_required,build_vision_gap_judge,build_vision_continuation_audit,compact_replan_obligation,build_autonomous_replan_recommendation,build_autonomous_replan_decision,build_goal_frontier_projection).loopx/control_plane/goals/goal_frontier/replan_rules.py(220 -> 525lines,any_count: 0,dict_any_count: 0): ownsbuild_rule_replan_obligationplus shared_frontier_obligation_payloadand_agent_add_todo_actionhelpers alongsideGoalFrontierReplanRuleandselect_goal_frontier_replan_rule.loopx/control_plane/goals/goal_frontier/acceptance.py(166 -> 221lines,any_count: 0,dict_any_count: 0): ownsVISION_PROFILE_MISSING_TRIGGERandacceptance_gaps_from_agent_profile_requirement.loopx/control_plane/goals/goal_frontier/ack_policy.py(224 -> 333lines,any_count: 0,dict_any_count: 0): ownsprojected_autonomous_replan_ack_for_agent,_ack_semantic_delta,_replan_evidence_acknowledged,_succession_gap_acknowledged,_vision_gap_acknowledged, and_acknowledged_replan_obligation_id.loopx/canary/module_metric_baseline.json: preserves allorigin/mainentries and tightens all five changedgoal_frontiermodules (__init__.py,acceptance.py,ack_policy.py,projection.py,replan_rules.py) to"any_count": 0,"dict_any_count": 0, and exact line ceilings (968,221,333,305,525).Verification (at exact HEAD
532a729582f8ce664f0f78805d7837530c157fa4)git diff --shortstat origin/main...HEAD:6 files changed, 1365 insertions(+), 1563 deletions(-)(-198 net LOC).ruff checkon the 5 changed Python files:All checks passed!.mypy:Success: no issues found in 17 source files;mypy --strict --follow-imports=silenton the 5 changedgoal_frontier/*.pyfiles:Success: no issues found in 5 source files.npm run typecheck:control-plane: passed (exit 0).python scripts/check_rfc_bilingual.py --base origin/main --head HEADandgit diff --check origin/main...HEAD: passed (exit 0).HOMEloopx check --scan-path ...on all 6 changed files:"ok": true,"errors": [],"public boundary scan clean: 6 files".HOMEloopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick --no-progress:status: passed,ok: true,merge_gate_passed: true(direct_checks6/6passed;catalog_run3/3ok —control-plane-maintainability-ratchet-smoke.py,semantic-vocabulary-drift-smoke.py,peer-agent-continuation-state-machine-smoke.py).origin/main(41ea75e898): 100% parameter/default/kwonly/vararg/kwarg parity across all retained and re-exported functions, plus 15/15 byte-for-byte behavioral equivalence & negative probes (receipt_bound_replan_ack_candidates: []fence preserved) and matchingloopx.cli quota should-run(file/sqlite) parity fingerprints (clean_advancement_no_replan:87529678a6549ee7,succession_gap_replan:7e9a7c5196b79c90,monitor_frontier_exhausted/vision_gap_replan:62f53d9d22bfd378).goal_frontiersuites (test_goal_frontier_replan_rules.py,test_goal_frontier_fallback_disposition.py,test_goal_frontier_full_source_counts.py,test_advancement_frontier_classification.py,test_goal_acceptance_stale_replan.py,test_goal_terminal_no_followup.py,test_monitor_replan_agent_scope.py,test_replan_novelty_policy.py):236 passed.tests/architecture/test_semantic_vocabulary_drift.py:124 passed.tests/architecture/test_control_plane_import_boundaries.py+tests/control_plane/test_contract_health.py:52 passed.tests/control_plane/test_quota_should_run_parity.py+tests/control_plane/test_quota_decision_summary.py:8 passed.tests/canary/test_maintainability_ratchet.py -k "not test_current_repository_debt_is_reviewed_without_line_count_pins":13 passed, 1 deselected(test_current_repository_debt_is_reviewed_without_line_count_pinsreproduced failing identically onorigin/main41ea75e898due to inherited findings inheartbeat/builder.py&interaction_contract.py).21files):572 passed, 14 failedplustest_heartbeat_receipt.py+test_heartbeat_recommendation_rules.py(23 passed, 4 failed) — all18failures (test_replan_history_provider.py[2],test_replan_successor_guard_reentry.py[4],test_quota_selection.py[6],test_quota_vision_audit_references.py[2],test_heartbeat_receipt.py[4]) reproduced with identical failure signatures on unmodifiedorigin/main(41ea75e898).goal-frontier-replan-rules-smoke.py,quota-replan-decision-plane-smoke.py,heartbeat-quota-flow-smoke.py,autonomous-replan-obligation-smoke.py,goal-vision-closed-successor-smoke.py,goal-vision-replan-contract-smoke.py): passed.