evidentloop · Li-Sanze · May 26, 2026 · May 26, 2026
diff --git 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
@@ -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
@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=zh-CN; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-05-26.112801 -->
+<!-- SOPIFY_VERSION: 2026-05-26.130923 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - 自适应 AI 编程助手

diff --git a/Claude/Skills/EN/CLAUDE.md b/Claude/Skills/EN/CLAUDE.md
@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=en-US; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-05-26.112801 -->
+<!-- SOPIFY_VERSION: 2026-05-26.130923 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - Adaptive AI Programming Assistant

diff --git a/Codex/Skills/CN/AGENTS.md b/Codex/Skills/CN/AGENTS.md
@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=zh-CN; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-05-26.112801 -->
+<!-- SOPIFY_VERSION: 2026-05-26.130923 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - 自适应 AI 编程助手

diff --git a/Codex/Skills/EN/AGENTS.md b/Codex/Skills/EN/AGENTS.md
@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=en-US; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-05-26.112801 -->
+<!-- SOPIFY_VERSION: 2026-05-26.130923 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - Adaptive AI Programming Assistant

diff --git 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
@@ -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 → runtime/_orchestration.py b/runtime/_kernel_turn.py → 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 → tests/test_runtime_orchestration.py b/tests/test_runtime_kernel_turn.py → 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):