Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "2718lab-devkit",
"version": "1.1.4",
"version": "1.1.5",
"description": "Local MCP server for developer workflow coordination, indexing, and evidence handling.",
"author": {
"name": "2718lab",
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ body:
id: version
attributes:
label: DevKit version
placeholder: "v1.1.4"
placeholder: "v1.1.5"
validations:
required: true

Expand Down
28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,34 @@ only after the CI and artifact checks pass.

## [Unreleased]

## [1.1.5] - 2026-09-05

### Added

- Added the model-neutral `fast-lane-request-v2` / `work-package-v3` /
`fast-lane-plan-v3` path. New assignments describe complexity, capability,
effort, and cost requirements while the coordinator chooses from the model
IDs and efforts exposed by the current Codex dispatch tool.
- Added public request preparation plus model-selection record helpers. A
selection record binds the exact model ID, effort, reason,
`requirement_hash`, and `plan_item_id` without claiming dispatch or model
availability.

### Fixed

- Future bounded model IDs, including an explicitly requested `gpt-6-astra`,
no longer require a DevKit model-name whitelist. Explicit model/effort intent
is hash-bound and cannot be silently replaced by a fallback route.
- Reject mixed request/work-package versions in both directions; request-v1 is
paired with work-package-v2 and request-v2 with work-package-v3.

### Security

- Model-neutral plans remain `plan_only`, `not_dispatched`, and unauthorized;
the actual dispatch tool is the only availability gate and worker `ultra`
remains forbidden. Legacy v3/v4/v5 routing policy assets and legacy
request-v1/plan-v2 replay behavior are unchanged.

## [1.1.4] - 2026-09-04

### Added
Expand Down
57 changes: 35 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,27 @@
[简体中文](README.zh-CN.md)

# 2718lab DevKit — Codex + MCP v1.1.4
# 2718lab DevKit — Codex + MCP v1.1.5

[![version](https://img.shields.io/badge/version-v1.1.4-blue)](./.codex-plugin/plugin.json)
[![version](https://img.shields.io/badge/version-v1.1.5-blue)](./.codex-plugin/plugin.json)
[![license](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)

2718lab DevKit is a Codex-first engineering toolkit: a local, stdio-only MCP
runtime for bounded project indexing, Atlas evidence, Relay lifecycle
coordination, and deterministic Fast Lane planning, plus a compact Skill bundle
of reference manuals. This repository carries the versioned v1.1.4 package.
of reference manuals. This repository carries the versioned v1.1.5 package.
The checked-in manifest and allowlist define the executable runtime surface;
the manual map, install, build, and verification sections below describe the
supported workflow.

The public Python compiler and CLI retain the deliberately fail-closed
`team-efficiency/fast-lane-plan-v1` preview. The MCP `fastlane_compile` tool
instead resolves caller-supplied workspace/snapshot selectors through its local
RuntimeRoot and returns a verified `team-efficiency/fast-lane-plan-v2` planning
descriptor. That descriptor is `plan_only`: it never dispatches, claims a
lease, creates a worktree, or authorizes execution.
`team-efficiency/fast-lane-plan-v1` preview. For new work, prepare
`fast-lane-request-v2` with `prepare_model_neutral_fast_lane_request`; MCP
`fastlane_compile` then resolves the workspace/snapshot selectors through its
local RuntimeRoot and returns a verified `team-efficiency/fast-lane-plan-v3`.
Its assignments describe requirements and leave model selection to the
coordinator using current Codex tool metadata. Every descriptor remains
`plan_only`: it never dispatches, claims a lease, creates a worktree, or
authorizes execution. Request-v1/plan-v2 stays available for exact legacy replay.

The prior v1.1.3 storage-governance integration references compatible Host source only
on Ayleovelle's user-fork
Expand Down Expand Up @@ -61,12 +64,14 @@ and continue to fail closed.
- The optional Codex Skill bundle is part of DevKit's documentation surface. It
provides short, module-specific manuals without becoming a second runtime or
an executable prompt/agent surface.
- Fast Lane is a pure planning compiler. The MCP tool can emit bounded
`team-efficiency/fast-lane-plan-v2` assignments only after its private
- Fast Lane is a pure planning compiler. New model-neutral requests emit bounded
`team-efficiency/fast-lane-plan-v3` assignments only after its private
RuntimeRoot verifies a registered `INDEX_READY` snapshot, Git HEAD, and full
write-scope coverage. Every result remains `plan_only`; no agent, Git command,
lease, or worktree action is executed. The public Python compiler/CLI remains
the authority-inert plan-v1 diagnostic surface.
write-scope coverage. Assignments contain no default model name; the
coordinator records an exact model/effort choice before the dispatch tool
validates availability. Every result remains `plan_only`; no agent, Git
command, lease, or worktree action is executed. The public Python compiler/CLI
remains the authority-inert plan-v1 diagnostic surface.

## Module overview

Expand All @@ -84,8 +89,9 @@ and continue to fail closed.
## Overall workflow

The repository workflow defaults to Fast Lane. `workflow-design` prepares a
bounded input. MCP `fastlane_compile` verifies the persisted local project
snapshot and returns a plan-v2 descriptor; `team_efficiency.py` retains the
bounded model-neutral request-v2 input. MCP `fastlane_compile` verifies the
persisted local project snapshot and returns a plan-v3 descriptor;
`team_efficiency.py` retains the
blocked plan-v1 diagnostic path. Neither path starts agents or creates/executes
cross-session worktrees. A coordinator must separately validate route
availability, claim a lease, and dispatch any selected work.
Expand All @@ -98,7 +104,7 @@ flowchart TD
end
subgraph FAST["Fast Lane"]
F["fast-lane request"] --> G["MCP fastlane_compile<br/>private RuntimeRoot verification"]
G --> X["plan-v2<br/>plan_only, not dispatched"]
G --> X["plan-v3 requirements<br/>unselected, plan_only"]
F --> H["public Python / CLI"] --> I["plan-v1<br/>NO_SAFE_WORK"]
end
B -->|MCP tools| C
Expand Down Expand Up @@ -179,7 +185,7 @@ source of record remains `main` and immutable release tags.

Maintainers build that snapshot with the dedicated marketplace allowlist:

python .codex-plugin/build_main_artifact.py --plugin-root . --allowlist .codex-plugin/marketplace-artifact-allowlist.json --output <artifact-output-dir>/2718lab-devkit-marketplace-v1.1.4.zip
python .codex-plugin/build_main_artifact.py --plugin-root . --allowlist .codex-plugin/marketplace-artifact-allowlist.json --output <artifact-output-dir>/2718lab-devkit-marketplace-v1.1.5.zip

## Install and run locally

Expand Down Expand Up @@ -226,7 +232,7 @@ handles or falls back to an unrelated local start.
The allowlisted builder creates a deterministic ZIP outside the plugin source
tree. Choose an output directory outside the source tree:

python .codex-plugin/build_main_artifact.py --plugin-root . --output <artifact-output-dir>/2718lab-devkit-v1.1.4.zip
python .codex-plugin/build_main_artifact.py --plugin-root . --output <artifact-output-dir>/2718lab-devkit-v1.1.5.zip

The artifact contains the manifest, .mcp.json, LICENSE, the locked Python
project, and the runtime files selected by
Expand Down Expand Up @@ -337,18 +343,25 @@ cleanup target.
The Fast Lane compiler is in
mcp-tools/devkit_fastlane/scripts/fastlane_routing.py and
mcp-tools/devkit_fastlane/scripts/team_efficiency.py. The MCP `fastlane_compile`
entry returns `team-efficiency/fast-lane-plan-v2` only after a read-only
entry returns `team-efficiency/fast-lane-plan-v3` for a model-neutral request
only after a read-only
RuntimeRoot unit of work resolves the registered workspace and snapshot. The
snapshot must be current, `INDEX_READY`, bound to the repository Git HEAD, and
its persisted `include_paths` must fully cover every writer `write_scope`.

- `reasoning_effort` is required and accepts only `low`, `medium`, `high`,
`xhigh`, or `max`; the MCP output never dispatches a worker.
- `team-efficiency/fast-lane-plan-v2` fixes `plan_only=true`,
- `team-efficiency/fast-lane-plan-v3` fixes `plan_only=true`,
`dispatch_state="not_dispatched"`, and `execution_authorized=false`.
Assignments use `team-efficiency/local-writer-plan-v1`; path-free
Assignments use `team-efficiency/local-writer-plan-v2`, with bounded
`route_requirements` and coordinator-owned `selection.state="unselected"`;
path-free
`index_evidence` includes snapshot/binding hashes, `include_paths_hash`, and
the compiled `scope_hash`.
- `record_model_selection` binds `plan_item_id`, `requirement_hash`, the exact
model ID and effort, and the coordinator's reason. It is a `selection_only`,
`not_dispatched` record; the dispatch tool remains the availability gate.
An explicit request intent cannot be replaced by a fallback model.
- `INDEX_STALE` rejects filesystem or Git drift. `INDEX_PARTIAL` rejects either
a partial snapshot or any snapshot whose include roots omit a writer scope.
- Caller IDs are selectors, not authority material. The public MCP request and
Expand Down Expand Up @@ -395,7 +408,7 @@ freeze a transient regression count.

## Version

This repository represents the versioned v1.1.4 package. Release notes are
This repository represents the versioned v1.1.5 package. Release notes are
in [CHANGELOG.md](CHANGELOG.md); build and install from the checked-in manifest,
artifact allowlist, and locked dependency set. A maintainer dispatches Release
from current `main`; it validates all declared gates, creates the annotated tag,
Expand Down
49 changes: 29 additions & 20 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,23 @@
[English](README.md)

# 2718lab DevKit —— Codex + MCP v1.1.4
# 2718lab DevKit —— Codex + MCP v1.1.5

[![版本](https://img.shields.io/badge/version-v1.1.4-blue)](./.codex-plugin/plugin.json)
[![版本](https://img.shields.io/badge/version-v1.1.5-blue)](./.codex-plugin/plugin.json)
[![许可证](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)

2718lab DevKit 是一个 Codex-first 工程工具包:它包含一个本地、仅 stdio
传输的 MCP 运行时,用于有边界的项目索引、Atlas 证据、Relay 生命周期协调和
确定性的 Fast Lane 规划;同时还包含一组精简的 Skill 说明书。本仓库承载版本化的
v1.1.4 包;已提交的 manifest 和 allowlist 定义可执行运行时范围,说明书导航、
v1.1.5 包;已提交的 manifest 和 allowlist 定义可执行运行时范围,说明书导航、
安装、构建和验证章节共同给出支持的工作流。

公共 Python 编译器和 CLI 继续保留刻意 fail-closed 的
`team-efficiency/fast-lane-plan-v1` 预览。MCP `fastlane_compile` 则通过本地
RuntimeRoot 解析 caller 提供的 workspace/snapshot selector,并返回已验证的
`team-efficiency/fast-lane-plan-v2` 规划描述符。该描述符固定为 `plan_only`:不会
派发、领取 lease、创建 worktree 或授权执行。
`team-efficiency/fast-lane-plan-v1` 预览。新任务先用
`prepare_model_neutral_fast_lane_request` 准备 `fast-lane-request-v2`;MCP
`fastlane_compile` 再通过本地 RuntimeRoot 解析 workspace/snapshot selector,并返回
已验证的 `team-efficiency/fast-lane-plan-v3`。assignment 只描述需求,由协调器根据
本次 Codex 工具 metadata 选择模型。描述符仍固定为 `plan_only`:不会派发、领取
lease、创建 worktree 或授权执行。request-v1/plan-v2 仅保留精确历史重放。

此前 v1.1.3 的存储治理集成只引用 Ayleovelle 用户 fork 上的兼容 Host 源码:
[`codex/host-1.1.3-storage-governance-upstream`](https://github.com/Ayleovelle/codex/tree/codex/host-1.1.3-storage-governance-upstream)
Expand Down Expand Up @@ -47,11 +49,12 @@ stock Codex Host 没有经过证明的 protected broker,继续 fail-closed。
静态 prompt agent 或模型运行器。
- 可选的 Codex Skill bundle 是 DevKit 的说明书表面,提供简短的模块化手册;
它不构成第二个运行时,也不是可执行的 prompt/agent 表面。
- Fast Lane 是纯规划编译器。只有 server 私有 RuntimeRoot 验证已注册的
- Fast Lane 是纯规划编译器。新 model-neutral request 只有在 server 私有 RuntimeRoot 验证已注册的
`INDEX_READY` snapshot、Git HEAD 和完整 writer scope 覆盖后,MCP 工具才会
产出有界的 `team-efficiency/fast-lane-plan-v2` assignments。所有结果仍为
`plan_only`,不执行 agent、Git 命令、lease 或 worktree 动作。公共 Python
编译器/CLI 继续作为无 authority 的 plan-v1 诊断面。
产出有界的 `team-efficiency/fast-lane-plan-v3` assignments。assignment 不带
默认模型名;协调器先记录 exact model/effort,再由 dispatch tool 校验可用性。
所有结果仍为 `plan_only`,不执行 agent、Git 命令、lease 或 worktree 动作。
公共 Python 编译器/CLI 继续作为无 authority 的 plan-v1 诊断面。

## 核心模块速览

Expand All @@ -68,8 +71,9 @@ stock Codex Host 没有经过证明的 protected broker,继续 fail-closed。

## 整体工作流

仓库级默认工作流是 Fast Lane。`workflow-design` 准备有界输入;MCP
`fastlane_compile` 验证持久化本地项目 snapshot 后返回 plan-v2 描述符,
仓库级默认工作流是 Fast Lane。`workflow-design` 准备有界的 model-neutral
request-v2 输入;MCP `fastlane_compile` 验证持久化本地项目 snapshot 后返回
plan-v3 描述符,
`team_efficiency.py` 则保留被阻断的 plan-v1 诊断路径。两条路径都不会启动 agent,
也不会创建或执行跨会话工作树。协调器必须另行验证 route availability、领取 lease
并派发所选工作。
Expand All @@ -82,7 +86,7 @@ flowchart TD
end
subgraph FAST["Fast Lane"]
F["fast-lane request"] --> G["MCP fastlane_compile<br/>私有 RuntimeRoot 验证"]
G --> X["plan-v2<br/>plan_only,未派发"]
G --> X["plan-v3 requirements<br/>未选择,plan_only"]
F --> H["公共 Python / CLI"] --> I["plan-v1<br/>NO_SAFE_WORK"]
end
B -->|MCP 工具| C
Expand Down Expand Up @@ -157,7 +161,7 @@ Fast Lane 不含额度协调器合同;公共编译器和 CLI 不读取、协

维护者使用专用的 marketplace allowlist 构建该快照:

python .codex-plugin/build_main_artifact.py --plugin-root . --allowlist .codex-plugin/marketplace-artifact-allowlist.json --output <artifact-output-dir>/2718lab-devkit-marketplace-v1.1.4.zip
python .codex-plugin/build_main_artifact.py --plugin-root . --allowlist .codex-plugin/marketplace-artifact-allowlist.json --output <artifact-output-dir>/2718lab-devkit-marketplace-v1.1.5.zip

## 本地安装与运行

Expand Down Expand Up @@ -197,7 +201,7 @@ RELAY_CAPABILITY_BROKER_UNAVAILABLE。服务器不会暴露原始 handle,也

allowlist builder 会在插件源码树之外生成确定性的 ZIP。请选择源码树之外的输出目录:

python .codex-plugin/build_main_artifact.py --plugin-root . --output <artifact-output-dir>/2718lab-devkit-v1.1.4.zip
python .codex-plugin/build_main_artifact.py --plugin-root . --output <artifact-output-dir>/2718lab-devkit-v1.1.5.zip

产物包含 manifest、.mcp.json、LICENSE、锁定的 Python 项目,以及
.codex-plugin/main-artifact-allowlist.json 选中的运行时文件。它的可执行运行时
Expand Down Expand Up @@ -293,16 +297,21 @@ Fast Lane 编译器位于
mcp-tools/devkit_fastlane/scripts/fastlane_routing.py 和
mcp-tools/devkit_fastlane/scripts/team_efficiency.py。MCP `fastlane_compile` 只有在
只读 RuntimeRoot UoW 解析已注册 workspace/snapshot 后才返回
`team-efficiency/fast-lane-plan-v2`。snapshot 必须 current、处于 `INDEX_READY`、
model-neutral request 返回 `team-efficiency/fast-lane-plan-v3`。snapshot 必须
current、处于 `INDEX_READY`、
绑定仓库 Git HEAD,且持久化 `include_paths` 完整覆盖每个 writer `write_scope`。

- `reasoning_effort` 必填且只接受 `low`、`medium`、`high`、`xhigh` 或
`max`;MCP 输出永不派发 worker。
- `team-efficiency/fast-lane-plan-v2` 固定 `plan_only=true`、
- `team-efficiency/fast-lane-plan-v3` 固定 `plan_only=true`、
`dispatch_state="not_dispatched"`、`execution_authorized=false`。
assignment 使用 `team-efficiency/local-writer-plan-v1`;无路径的
assignment 使用 `team-efficiency/local-writer-plan-v2`,包含有界
`route_requirements` 与协调器负责的 `selection.state="unselected"`;无路径的
`index_evidence` 包含 snapshot/binding hashes、`include_paths_hash` 与已编译
`scope_hash`。
- `record_model_selection` 绑定 `plan_item_id`、`requirement_hash`、exact model ID、
effort 与协调器选择理由。该记录仍为 `selection_only/not_dispatched`,可用性只由
dispatch tool 校验;显式请求的模型不得被 fallback 替换。
- filesystem 或 Git 漂移返回 `INDEX_STALE`;snapshot 本身 partial,或其 include
roots 遗漏任一 writer scope,均返回 `INDEX_PARTIAL`。
- caller ID 只是 selector,不是 authority material。公共 MCP request 与公共
Expand Down Expand Up @@ -342,7 +351,7 @@ CI 和全新产物检查才是当前测试计数的唯一来源。它们验证

## 版本

本仓库代表版本化的 v1.1.4 包。发布说明见
本仓库代表版本化的 v1.1.5 包。发布说明见
[CHANGELOG.md](CHANGELOG.md);构建和安装请以已提交的 manifest、产物 allowlist
和锁定依赖为准。维护者从 current `main` 手动 dispatch Release;它通过全部 gates
后才创建注释 tag 并发布匹配的 GitHub Release。单独 push tag 不会触发发布。
Expand Down
Loading