Dopetaiga · Dopetaiga · Aug 15, 2026 · Aug 9, 2026 · Aug 15, 2026 · Aug 15, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -121,6 +121,9 @@ jobs:
           Package/EngineeringStructure/Test/Application/Query/ProductRootProjection.Test.py
           Package/EngineeringStructure/Test/Application/Query/StructureCompliance.Test.py
 
+      - name: Run LiteCodeBench offline oracle gate
+        run: python benchmarks/run_litecodebench.py
+
       - name: Run test suite
         run: python -m pytest -q --tb=short
 

diff --git a/.gitignore b/.gitignore
@@ -38,6 +38,7 @@ env/
 .pytest_cache/
 .coverage
 htmlcov/
+test_results/
 
 # OS
 .DS_Store

diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liu Mengxuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,15 +1,15 @@
 # MiniCode Python
 
 <p align="center">
-  <strong>A lightweight local coding agent for developers who want durable terminal workflows, not just a chat wrapper.</strong>
+  <strong>An independently recreated MiniCode Python runtime, extended with memory, subagents, recovery, and reproducible evaluation.</strong>
 </p>
 
 <p align="center">
   <a href="./README.zh-CN.md">Chinese</a>
   |
   <a href="https://github.com/LiuMengxuan04/MiniCode">MiniCode Main Repo</a>
   |
-  <a href="https://github.com/QUSETIONS/MiniCode-Python">Python Repo</a>
+  <a href="./REIMPLEMENTATION.md">Reimplementation Record</a>
 </p>
 
 <p align="center">
@@ -26,7 +26,9 @@
   <em>Real MiniCode frontend demo, not a mock: the landing page now reflects the current Python runtime and shows memory, session, rewind, and readiness as first-class product surfaces.</em>
 </p>
 
-MiniCode Python is the Python runtime in the MiniCode family. It is built for local development where the agent needs to survive long sessions, keep its state inspectable, recover from bad edits, and show what it is doing while it works.
+MiniCode-Python is my independent Python recreation and continuing engineering extension of [MiniCode](https://github.com/LiuMengxuan04/MiniCode), produced after studying its source and Python implementation. It does not claim official status or pretend to be a clean-room original: upstream provenance and licensing stay visible, while runnable code, tests, and experiment artifacts show the work I actually completed.
+
+After recreating the core agent, I extended it into a local-first runtime with durable sessions, memory, checkpoint/rewind, provider readiness, bounded `task` subagents, and the reproducible [LiteCodeBench](benchmarks/LITECODEBENCH.md). See the [reimplementation record](REIMPLEMENTATION.md) for the boundary and evidence map.
 
 If Claude Code represents the polished terminal-agent experience, MiniCode Python is the lightweight, local-first version that leans harder into runtime transparency, durable sessions, memory-backed continuity, rewindability, and verifiable behavior.
 
@@ -99,7 +101,7 @@ With the current repository state, you can already:
 ### 1. Install and launch
 
 ```bash
-git clone https://github.com/QUSETIONS/MiniCode-Python.git
+git clone https://github.com/Dopetaiga/MiniCode-Python.git
 cd MiniCode-Python
 python -m pip install -e .[dev]
 minicode-py
@@ -189,6 +191,31 @@ fallback, and artifact evidence as the release JSON. `--check-fallback-evidence`
 that provider risk is paired with fallback coverage or an auditable fallback
 repair path.
 
+## LiteCodeBench evaluation
+
+This branch carries LiteCodeBench v1.0 for MiniCode-Python together with the runtime. The
+15-task suite covers evidence retrieval, file artifacts, code repair, security,
+multi-file work, and the current synchronous `task` sub-agent interface. Its
+eight hidden-test tasks are checked against both a broken baseline and an oracle
+solution before any live model run starts.
+
+```bash
+python benchmarks/run_litecodebench.py
+python benchmarks/run_litecodebench.py --live --runs 3
+```
+
+The offline command makes no model request. Historical v1.1 fixtures and
+sanitized DSV4 Flash reports are preserved under `benchmarks/legacy/` and
+`benchmarks/results/`; see [the evaluation protocol](benchmarks/LITECODEBENCH.md).
+Historical scores are not presented as v1.2 scores: rerun v1.2 before making a
+current-runtime performance claim.
+
+The 2026-08-15 DSV4 study first scored 14/15 and exposed a shallow-copy aliasing
+failure. After aligning the task contract with a stricter two-sided alias
+verifier, a clean-worktree rerun scored 15/15. These runs are not presented as
+directly comparable model-performance samples; see the
+[full LiteCodeBench report](benchmarks/results/LITECODEBENCH_DSV4_REPORT_2026-08-15.md).
+
 ## Typical Workflow
 
 ```mermaid
@@ -325,21 +352,22 @@ What matters is not the diagram itself. What matters is that runtime state is tr
 | `minicode/runtime_profiles.py` | Runtime profiles such as `single` and `single-deep`. |
 | `minicode/cybernetic_orchestrator.py` | Runtime control lifecycle facade. |
 
-## MiniCode Family
+## Origin and Project Positioning
 
-| Version | Repository | Focus |
+| Code line | Repository | Relationship to this project |
 | --- | --- | --- |
-| TypeScript | [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode) | Mainline terminal agent, TUI, MCP, skills, sessions, and context controls. |
-| Python | [QUSETIONS/MiniCode-Python](https://github.com/QUSETIONS/MiniCode-Python) | Local-first Python runtime with stronger session, rewind, readiness, and observability surfaces. |
-| Rust | [harkerhand/MiniCode-rs](https://github.com/harkerhand/MiniCode-rs/tree/master) | Systems-side implementation and experiments. |
-| Java | [hobbescalvin414-tech/minicode4j](https://github.com/hobbescalvin414-tech/minicode4j/tree/feat/default-ts-ui) | Java implementation with a TypeScript-style UI direction. |
+| Study source | [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode) | Used to understand the agent loop, tool execution, and terminal interaction design. |
+| Python recreation and extensions | [Dopetaiga/MiniCode-Python](https://github.com/Dopetaiga/MiniCode-Python) | Recreates the core flow and adds memory, recovery, subagents, readiness, and evaluation. |
+
+This is more precise than calling the repository merely a modified fork. [REIMPLEMENTATION.md](REIMPLEMENTATION.md) separates the studied source, recreated scope, later extensions, and verifiable evidence for review or interviews.
 
 ## Documentation
 
 Start here if you want the deeper implementation and productization record:
 
 
 - [Chinese README](./README.zh-CN.md)
+- [Reimplementation and extension record](./REIMPLEMENTATION.md)
 - [Optimization Summary](./Docs/Documentation/OPTIMIZATION_SUMMARY.md)
 - [Memory Theory](./Docs/Documentation/memory_theory.md)
 - [Minicode-lite Productization Design](./Docs/Documentation/superpowers/specs/2026-06-05-minicode-lite-productization-design.md)

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -1,15 +1,15 @@
 # MiniCode Python
 
 <p align="center">
-  <strong>一个面向本地开发的轻量级 coding agent：不只是聊天壳子，而是可恢复、可回放、可检查的终端工作流。</strong>
+  <strong>源码研读驱动的 MiniCode Python 独立复刻：从可运行 agent 到 memory、subagent 与可复现实验。</strong>
 </p>
 
 <p align="center">
   <a href="./README.md">English</a>
   |
   <a href="https://github.com/LiuMengxuan04/MiniCode">MiniCode 主仓库</a>
   |
-  <a href="https://github.com/QUSETIONS/MiniCode-Python">Python 仓库</a>
+  <a href="./REIMPLEMENTATION.md">复刻与二次开发说明</a>
 </p>
 
 <p align="center">
@@ -26,7 +26,9 @@
   <em>这不是示意图，而是真实的 MiniCode 前端 Demo：首页直接把 memory、session、rewind 和 readiness 作为一等产品能力展示出来。</em>
 </p>
 
-MiniCode Python 是 MiniCode 家族里的 Python 运行时。它面向真实的本地开发场景：agent 不只是能调模型和工具，还要能跨长会话保留状态、回看历史、撤销错误编辑，并把自己的运行状态说清楚。
+MiniCode-Python 是我在研读 [MiniCode 主仓库](https://github.com/LiuMengxuan04/MiniCode)及其 Python 版本源码后，独立复刻、重新包装并持续二次开发的 Python coding-agent 项目。它不是对官方身份或“从零原创”的冒充；仓库保留上游来源与许可证，同时用可运行代码、测试和实验记录明确展示我实际完成的工程工作。
+
+复刻完成后，我继续把它扩展为面向真实本地开发的 agent runtime：支持持久会话、memory、checkpoint/rewind、provider readiness、有界 `task` subagent，以及可复现的 [LiteCodeBench](benchmarks/LITECODEBENCH.md)。实现边界和证据索引见[复刻与二次开发说明](REIMPLEMENTATION.md)。
 
 如果把 Claude Code 看成成熟的终端 agent 产品体验，那么 MiniCode Python 更像它的轻量级、本地优先版本：更强调运行时透明性、可持续会话、记忆连续性、可回退编辑，以及可验证行为。
 
@@ -99,7 +101,7 @@ MiniCode Python 是 MiniCode 家族里的 Python 运行时。它面向真实的
 ### 1. 安装并启动
 
 ```bash
-git clone https://github.com/QUSETIONS/MiniCode-Python.git
+git clone https://github.com/Dopetaiga/MiniCode-Python.git
 cd MiniCode-Python
 python -m pip install -e .[dev]
 minicode-py
@@ -158,6 +160,28 @@ python -m minicode.release_readiness --check-release-markdown benchmarks/release
 
 CI 环境建议用 `--fail-on blocked`：provider warning 会被报告，但不会误伤本地产品门禁。发布候选如果要求 provider 和 fallback 都 ready，再用 `--fail-on warning`。`--examples-out` 只导出只读配置建议，不会写入凭据，也不会修改 MiniCode settings。`--doctor-out` 会额外导出一份给 CI 和 release bundle 使用的人工可读诊断报告，其中包含 primary provider、fallback coverage、configured/default fallback 和 live smoke 分离状态的 local preflight 清单。`--repair-plan-out` 会把同一修复路径导出为已脱敏 JSON，让 CI 可以审计下一步动作但不写入凭据。`--patch-preview-out` 会导出已脱敏的 settings merge patch 预览，方便先审查选定 fallback provider，再由人工合并到本地 settings。artifact manifest 命令会记录 readiness artifacts 的存在性、大小和 SHA-256，用于发现证据缺失或漂移。`--bundle-out` 会一次性写出 examples、doctor、repair plan、patch preview、离线 fallback simulations 和 manifest，是本地最低操作成本的检查入口。`--check-fallback-patch-preview` 会校验 patch preview 的 safety 字段、apply notes、merge patch 形态和脱敏状态。`--check-fallback-simulation` 会逐项校验离线模拟并拒绝任何 live provider 声明，不会调用 provider。`--check-readiness-bundle` 会把 bundle 作为一个整体校验 schema、manifest 和脱敏状态。`benchmarks/release_readiness.py` 默认只刷新报告；如果发布候选必须在 live-provider 风险上失败，使用 `python benchmarks/release_readiness.py --fail-on at-risk`。它也会校验 headless provider trace，确保 live-smoke 失败仍保留机器可读的 readiness 快照和 repair plan。`--check-fallback-evidence` 会校验 provider 风险是否配有 fallback 覆盖或可审计的 fallback 修复路径。`--check-release-report` 会校验完整 release JSON 的 schema 和证据链接；只要诊断证据完整，provider `at-risk` 不会被误判为本地门禁失败。`--check-release-markdown` 会校验人工可读 Markdown 报告是否覆盖 JSON 中的状态、smoke、provider、fallback 和 artifact 证据。
 
+## LiteCodeBench 评测
+
+此分支把面向 MiniCode-Python 的 LiteCodeBench v1.0 与运行时代码放在同一仓库。15 个任务覆盖
+证据检索、文件产物、代码修复、安全边界、跨文件修改，以及最新版同步
+`task` subagent 接口。8 个隐藏测试任务会先验证缺陷基线确实失败、oracle
+解法确实通过，然后才允许发起 live 模型实验。
+
+```powershell
+python benchmarks/run_litecodebench.py
+python benchmarks/run_litecodebench.py --live --runs 3
+```
+
+离线命令不会调用模型。v1.1 原始题集和脱敏后的 DSV4 Flash 历史报告分别
+保存在 `benchmarks/legacy/` 与 `benchmarks/results/`；完整口径见
+[评测协议](benchmarks/LITECODEBENCH.md)。历史分数不会冒充当前版本
+成绩；对最新版做性能声明前需要重新运行 v1.2。
+
+2026-08-15 的 DSV4 单轮实验先取得 14/15，并暴露 deep merge 浅拷贝别名问题；
+在明确“返回值不得保留任一输入的可变别名”并加强双侧 verifier 后，干净
+worktree 复验为 15/15。两次运行的契约不同，不能包装成模型性能直接提升；详见
+[LiteCodeBench 完整报告](benchmarks/results/LITECODEBENCH_DSV4_REPORT_2026-08-15.md)。
+
 ## Typical Workflow
 
 ```mermaid
@@ -292,20 +316,21 @@ flowchart LR
 | `minicode/runtime_profiles.py` | `single`、`single-deep` 等 runtime profile。 |
 | `minicode/cybernetic_orchestrator.py` | runtime control 生命周期总控。 |
 
-## MiniCode Family
+## 项目来源与定位
 
-| 版本 | 仓库 | 侧重点 |
+| 代码线 | 仓库 | 与本项目的关系 |
 | --- | --- | --- |
-| TypeScript | [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode) | 主线终端 agent、TUI、MCP、skills、session 和 context control。 |
-| Python | [QUSETIONS/MiniCode-Python](https://github.com/QUSETIONS/MiniCode-Python) | 本地优先的 Python runtime，强化了 session、rewind、readiness 和 observability。 |
-| Rust | [harkerhand/MiniCode-rs](https://github.com/harkerhand/MiniCode-rs/tree/master) | 偏系统侧实现与实验。 |
-| Java | [hobbescalvin414-tech/minicode4j](https://github.com/hobbescalvin414-tech/minicode4j/tree/feat/default-ts-ui) | Java 实现，沿着 TypeScript 风格 UI 方向演进。 |
+| 学习来源 | [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode) | 用于理解 agent loop、工具调用和终端交互设计。 |
+| Python 复刻与二次开发 | [Dopetaiga/MiniCode-Python](https://github.com/Dopetaiga/MiniCode-Python) | 独立复刻核心流程，并继续实现 memory、恢复、subagent、readiness 与评测。 |
+
+这段关系不是一句模糊的 “fork 后修改”。[REIMPLEMENTATION.md](REIMPLEMENTATION.md) 将学习来源、复刻范围、后续扩展和可验证证据拆开记录，便于代码审查或面试追问。
 
 ## Documentation
 
 如果你想继续看更深的实现与产品化记录，可以从这里开始：
 
 - [English README](./README.md)
+- [复刻与二次开发说明](./REIMPLEMENTATION.md)
 - [Optimization Summary](./Docs/Documentation/OPTIMIZATION_SUMMARY.md)
 - [Memory Theory](./Docs/Documentation/memory_theory.md)
 - [Minicode-lite Productization Design](./Docs/Documentation/superpowers/specs/2026-06-05-minicode-lite-productization-design.md)

diff --git a/REIMPLEMENTATION.md b/REIMPLEMENTATION.md
@@ -0,0 +1,64 @@
+# MiniCode-Python: Reimplementation and Extension Record
+
+## Project statement
+
+MiniCode-Python is an independently recreated and packaged Python coding agent
+built after studying the MiniCode source code and its Python implementation. It
+is not presented as an official MiniCode release or as a clean-room design.
+The upstream source remains credited, and its MIT license is retained.
+
+The purpose of this repository is to make the learning process inspectable:
+recreate a working agent first, then extend it through testable runtime
+capabilities and reproducible experiments.
+
+## What was recreated
+
+- the model/tool execution loop and multi-turn state flow;
+- terminal-oriented local repository interaction;
+- tool registration, dispatch, and result replay;
+- configuration and OpenAI-compatible provider access;
+- the Python package, CLI entry points, and testable runtime boundaries.
+
+These items describe implementation work, not a claim that their product ideas
+were invented here. The MiniCode repository is the explicit study source.
+
+## What was added during continued development
+
+| Engineering area | Repository evidence |
+| --- | --- |
+| Durable sessions and replay | `minicode/session.py`, session CLI tests |
+| Working and project memory | `minicode/working_memory.py`, `minicode/memory_pipeline.py` |
+| Safe checkpoint and rewind | session/checkpoint implementation and recovery tests |
+| Bounded task subagents | task tool/runtime implementation and `tests/test_task_tool.py` |
+| Provider readiness and fallback evidence | `minicode/readiness.py`, `minicode/release_readiness.py` |
+| Agent evaluation | `benchmarks/LITECODEBENCH.md`, versioned JSONL tasks, raw result JSON |
+| Cross-platform regression | `.github/workflows/ci.yml` on Python 3.11 and 3.12 |
+
+## Evaluation discipline
+
+LiteCodeBench keeps prompts, task assets, verifiers, raw results, and the human
+report together. A score is only comparable when the dataset and contract are
+the same. The 2026-08-15 report therefore records the original 14/15 run and the
+revised-contract 15/15 run separately instead of describing them as a direct
+model-quality improvement.
+
+## How to discuss this project
+
+A concise and accurate description is:
+
+> I studied MiniCode's Python source, independently recreated and packaged a
+> runnable Python agent, then extended it with durable sessions, memory,
+> recovery, bounded subagents, provider readiness, and a reproducible agent
+> benchmark. I retained upstream attribution and used tests and raw evaluation
+> artifacts to distinguish reproduction from my later engineering work.
+
+Avoid claiming that the MiniCode concept, name, or all repository history was
+created here. The value of this project is the demonstrated source-reading,
+reimplementation, runtime engineering, and evaluation process.
+
+## Attribution
+
+- Study source: [LiuMengxuan04/MiniCode](https://github.com/LiuMengxuan04/MiniCode)
+- Current independently maintained repository:
+  [Dopetaiga/MiniCode-Python](https://github.com/Dopetaiga/MiniCode-Python)
+- License: MIT; original copyright notice preserved in `LICENSE`.