diff --git a/.sopify-skills/plan/20260522_runtime_slimming_kernel_extraction/tasks.md b/.sopify-skills/plan/20260522_runtime_slimming_kernel_extraction/tasks.md index 10c6a8b..4598dd7 100644 --- a/.sopify-skills/plan/20260522_runtime_slimming_kernel_extraction/tasks.md +++ b/.sopify-skills/plan/20260522_runtime_slimming_kernel_extraction/tasks.md @@ -291,16 +291,23 @@ archive_ready: false > 4. state_conflict inspect 严格只读（store 不变, last_route 不写） > 5. state_conflict abort tombstone 语义（plan/run 存活, stage 不变） > - 全量 631 passed, 49 subtests passed -- [ ] 4.12 post-cutover naming/comment polish（deferred，非行为变更） - > 进入条件: Package A + C 完成，retained 模块集合稳定 - > 范围: - > - 确认 `runtime/_kernel_turn.py` 的最终命名，按最终职责改名 - > - 审查其他 retained/internal 文件名是否仍带过渡态语义 - > - 对难以直读的 orchestration / state-ownership / resolution-id 代码补充选择性注释 - > 非目标: - > - 不改业务逻辑 - > - 不新增 public surface / 抽象层 - > - 不做大规模重构 +- [x] 4.12 post-cutover naming/comment polish ✅ 完成 + > **命名决策**: `runtime/_kernel_turn.py` → `runtime/_orchestration.py` + > - 保留下划线 internal 语义（external 进入点仍为 gate.py） + > - `execute_kernel_turn()` 函数名保留不改，不扩大变更面 + > - 不留 `_kernel_turn.py` 兼容 shim — 内部模块不承诺 import 稳定性 + > - 理由：orchestration 是稳态职责描述，kernel_turn 带迁移过程味道 + > + > **docstring/comment polish**: + > - `_orchestration.py` 模块 docstring 重写（去迁移语言，写稳态描述） + > - `_derived_resolution_id()` 加 docstring（优先级链说明） + > - `_result_state_store_for_route()` 加 docstring（store 选择逻辑说明） + > - `engine.py` 模块 docstring 更正（"Top-level orchestration" → legacy wrapper） + > - `run_runtime()` deprecation docstring 修正（去 "will be removed in Package A"） + > - `state.py` / `context_snapshot.py` 注释同步更新 + > + > **import 更新**: gate.py, cli.py, engine.py (3 处), test_runtime_orchestration.py (1 处) + > **测试**: 全量 631 passed, 49 subtests passed — 0 行为变更 ## 5. 文档更新 (⚠️ 部分完成 — 剩余项见"后续路线"节) - [x] 5.1 按审计结果决定是否需要回写 `blueprint/tasks.md` @@ -425,8 +432,8 @@ archive_ready: false | 编号 | 内容 | 当前状态 | |------|------|----------| -| 4.11 | kernel 验证 (gate→route→handoff→checkpoint) | ✅ 完成 — `test_runtime_kernel_turn.py` (5 cases) | -| 4.12 | naming/comment polish | deferred — 进入条件: 模块集合稳定 | +| 4.11 | kernel 验证 (gate→route→handoff→checkpoint) | ✅ 完成 — `test_runtime_orchestration.py` (5 cases) | +| 4.12 | naming/comment polish | ✅ 完成 — `_kernel_turn.py` → `_orchestration.py` + docstring polish | ### Tier 4: 文档更新 diff --git a/CHANGELOG.md b/CHANGELOG.md index 673cd3f..a875568 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,38 @@ Format: Summary → Changed → Plan Packages. File-level details live in `git l ## [Unreleased] +## [2026-05-26.130923] - 2026-05-26 + +### Summary + +- Updated 1 active plan package(s); Changes across: Docs, Runtime, Skills, Tests. + +### Changed + +- **Docs**: Refined public documentation (2 files) +- **Runtime**: Updated runtime internals (7 files) +- **Skills**: Synced prompt-layer skills (4 files) +- **Tests**: Updated automated coverage (2 files) + +### Plan Packages + +- `20260522_runtime_slimming_kernel_extraction` (active) + +## [2026-05-26.130719] - 2026-05-26 + +### Summary + +- Updated 1 active plan package(s); Changes across: Runtime, Tests. + +### Changed + +- **Runtime**: Updated runtime internals (7 files) +- **Tests**: Updated automated coverage (2 files) + +### Plan Packages + +- `20260522_runtime_slimming_kernel_extraction` (active) + ## [2026-05-26.112801] - 2026-05-26 ### Summary diff --git a/Claude/Skills/CN/CLAUDE.md b/Claude/Skills/CN/CLAUDE.md index 1779091..30fe963 100644 --- a/Claude/Skills/CN/CLAUDE.md +++ b/Claude/Skills/CN/CLAUDE.md @@ -1,5 +1,5 @@ - + # Sopify - 自适应 AI 编程助手 diff --git a/Claude/Skills/EN/CLAUDE.md b/Claude/Skills/EN/CLAUDE.md index f91e890..c15bf1d 100644 --- a/Claude/Skills/EN/CLAUDE.md +++ b/Claude/Skills/EN/CLAUDE.md @@ -1,5 +1,5 @@ - + # Sopify - Adaptive AI Programming Assistant diff --git a/Codex/Skills/CN/AGENTS.md b/Codex/Skills/CN/AGENTS.md index 597aba3..ac62d7f 100644 --- a/Codex/Skills/CN/AGENTS.md +++ b/Codex/Skills/CN/AGENTS.md @@ -1,5 +1,5 @@ - + # Sopify - 自适应 AI 编程助手 diff --git a/Codex/Skills/EN/AGENTS.md b/Codex/Skills/EN/AGENTS.md index fa7dab9..172d779 100644 --- a/Codex/Skills/EN/AGENTS.md +++ b/Codex/Skills/EN/AGENTS.md @@ -1,5 +1,5 @@ - + # Sopify - Adaptive AI Programming Assistant diff --git a/README.md b/README.md index 06b5f85..8ba5e2b 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE) [![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs) -[![Version](https://img.shields.io/badge/version-2026--05--26.112801-orange.svg)](#version-history) +[![Version](https://img.shields.io/badge/version-2026--05--26.130923-orange.svg)](#version-history) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) English · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [Contributors](./CONTRIBUTORS.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index 1fe3cb4..6df1bd0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -8,7 +8,7 @@ [![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE) [![文档](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs) -[![版本](https://img.shields.io/badge/version-2026--05--26.112801-orange.svg)](#版本历史) +[![版本](https://img.shields.io/badge/version-2026--05--26.130923-orange.svg)](#版本历史) [![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md) [English](./README.md) · 简体中文 · [快速开始](#快速开始) · [贡献者](./CONTRIBUTORS.md) diff --git a/runtime/_kernel_turn.py b/runtime/_orchestration.py similarity index 97% rename from runtime/_kernel_turn.py rename to runtime/_orchestration.py index 76973e1..a807511 100644 --- a/runtime/_kernel_turn.py +++ b/runtime/_orchestration.py @@ -1,16 +1,12 @@ -"""Kernel orchestration entry point (internal). - -Guarantees achieved: - - gate.py imports execute_kernel_turn() from this module instead of - engine.run_runtime(). - - engine.run_runtime() is a deprecated lazy-import wrapper. - - No runtime.models bridge consumption — types come from sopify_contracts. - - Kernel-path helpers are inlined (A1 complete) — no engine.py - implementation coupling for the core orchestration pipeline. - -Remaining engine dependency: - - 10 non-kernel route handlers still imported from engine.py. - A2 contract audit determined 9 retain + 1 deleted (skill execution sidecar). +"""Internal orchestration entry point for the Sopify runtime kernel. + +Exports ``execute_kernel_turn()`` — the single pipeline that resolves context, +routes a request, builds a handoff, and writes result state. All production +callers (gate.py, cli.py) import from this module; engine.run_runtime() is a +deprecated compatibility wrapper. + +The underscore prefix marks this as an internal module: external host code +should enter through ``gate.py``, never import ``_orchestration`` directly. """ from __future__ import annotations @@ -136,6 +132,10 @@ def _derived_resolution_id( current_run: RunState | None = None, current_handoff: RuntimeHandoff | None = None, ) -> str: + """Pick the best existing resolution ID, falling back to a fresh one. + + Priority: explicit resolved > current run > current handoff > new UUID. + """ for candidate in ( resolved_resolution_id, current_run.resolution_id if current_run is not None else "", @@ -242,6 +242,7 @@ def _result_state_store_for_route( current_decision: DecisionState | None = None, snapshot: ContextResolvedSnapshot | None = None, ) -> StateStore: + """Choose review or global store based on route and checkpoint phase.""" if canceled_store is not None: if canceled_store is global_store and preserved_review_after_cancel: return review_store diff --git a/runtime/cli.py b/runtime/cli.py index 7362732..050b37e 100644 --- a/runtime/cli.py +++ b/runtime/cli.py @@ -8,7 +8,7 @@ from typing import Callable, Mapping, Optional from .config import ConfigError, load_runtime_config -from ._kernel_turn import execute_kernel_turn +from ._orchestration import execute_kernel_turn from .output import render_runtime_error, render_runtime_output RequestTransform = Callable[[str], str] diff --git a/runtime/context_snapshot.py b/runtime/context_snapshot.py index 2bc101a..2114713 100644 --- a/runtime/context_snapshot.py +++ b/runtime/context_snapshot.py @@ -968,7 +968,7 @@ def _freeze_mapping(value: Mapping[str, Any]) -> Mapping[str, Any]: return MappingProxyType(frozen) -# -- Snapshot query helpers (consolidated from engine.py / _kernel_turn.py) ---- +# -- Snapshot query helpers (consolidated from engine.py / _orchestration.py) -- GLOBAL_EXECUTION_ROUTES = frozenset({"resume_active", "exec_plan", "archive_lifecycle"}) PROMOTABLE_REVIEW_STAGES = frozenset({"plan_generated", "ready_for_execution", "develop_pending"}) diff --git a/runtime/engine.py b/runtime/engine.py index 147eafd..85a9ce1 100644 --- a/runtime/engine.py +++ b/runtime/engine.py @@ -1,4 +1,4 @@ -"""Top-level orchestration for Sopify runtime — conflict handling, activation, archive.""" +"""Legacy compatibility wrapper + non-kernel route handlers (conflict, cancel, archive).""" from __future__ import annotations @@ -214,12 +214,11 @@ def run_runtime( """Run the Sopify runtime pipeline for a single input. .. deprecated:: - Legacy wrapper — delegates to ``_kernel_turn.execute_kernel_turn()``. - Direct callers should import from ``_kernel_turn`` instead. - This wrapper exists only for backward-compatible test imports - and will be removed in Package A. + Legacy wrapper — delegates to ``_orchestration.execute_kernel_turn()``. + Direct callers should import from ``_orchestration`` instead. + Kept for backward-compatible test imports (50+ callers use this path). """ - from ._kernel_turn import execute_kernel_turn # lazy to avoid circular + from ._orchestration import execute_kernel_turn # lazy to avoid circular return execute_kernel_turn( user_input, diff --git a/runtime/gate.py b/runtime/gate.py index d77075d..ca644c5 100644 --- a/runtime/gate.py +++ b/runtime/gate.py @@ -15,7 +15,7 @@ def _workspace_manifest_found(workspace: Path) -> bool: return (workspace / ".sopify-skills" / "sopify.json").is_file() from .config import ConfigError, load_runtime_config -from ._kernel_turn import execute_kernel_turn +from ._orchestration import execute_kernel_turn from .entry_guard import ENTRY_GUARD_PENDING_ACTIONS from .action_intent import ( ACTION_TYPES, diff --git a/runtime/state.py b/runtime/state.py index 86fe27b..9313d60 100644 --- a/runtime/state.py +++ b/runtime/state.py @@ -139,7 +139,7 @@ def _read_json_file(path: Path) -> Optional[dict[str, Any]]: return payload if isinstance(payload, dict) else None -# -- Run state construction (consolidated from engine.py / _kernel_turn.py) ---- +# -- Run state construction (consolidated from engine.py / _orchestration.py) -- def make_run_id(request_text: str) -> str: diff --git a/tests/test_runtime_kernel_turn.py b/tests/test_runtime_orchestration.py similarity index 98% rename from tests/test_runtime_kernel_turn.py rename to tests/test_runtime_orchestration.py index 937a93f..e1f8d83 100644 --- a/tests/test_runtime_kernel_turn.py +++ b/tests/test_runtime_orchestration.py @@ -1,13 +1,13 @@ # Test classification: contract # -# 4.11 — Direct tests for execute_kernel_turn(). +# 4.11 — Direct tests for execute_kernel_turn() through the orchestration module. # Proves the kernel orchestration seam works independently of the # run_runtime() wrapper in engine.py. from __future__ import annotations from tests.runtime_test_support import * -from runtime._kernel_turn import execute_kernel_turn +from runtime._orchestration import execute_kernel_turn class TestKernelTurnDirect(unittest.TestCase):