Promote strict orchestrator as mainline skill

Author: keithhegit

README.md

@@ -1,145 +1,158 @@
-# Codex Ultra Orchestration vNext 试跑说明
+# Codex Ultra Orchestration 主线试跑说明
 
 ## 目标
 
-这份说明用于试跑 `ultra-orchestration` 仓库中的 vNext 技能树。
+这份说明用于试跑 `ultra-orchestration` 仓库中的主线 strict 控制面。
 
-vNext 技能树位置：
+默认入口已经从 vNext 预览入口收敛为：
 
-`<REPO_ROOT>\skills-vnext`
+```text
+$ultra-orchestrator <任务描述>
+```
+
+`ultra-vnext-core` 仍然保留为兼容别名，但新用户和新项目默认使用
+`ultra-orchestrator`。
 
 ## 主入口
 
-vNext 只需要一个主入口：
+推荐调用方式：
 
 ```text
-$ultra-vnext-core <任务描述>
+$ultra-orchestrator <任务描述>
 ```
 
-`ultra-vnext-core` 会根据任务类型自动路由到需要的子技能。用户不需要手动列出 `ultra-brainstorming`、`ultra-planning`、`ultra-review` 等全部技能。
+OpenSpec 显式调用：
+
+```text
+$ultra-orchestrator OpenSpec change <change-id 或路径>: <任务描述>
+```
 
 如果客户端提供 slash alias，也可以使用：
 
 ```text
-/ultra-vnext-core <任务描述>
+/ultra-orchestrator <任务描述>
 ```
 
-## 技能组成
-
-- `ultra-vnext-core`
-  主入口、路由器、共享 contracts、状态机、ledger 初始化和 contract 校验脚本
-- `ultra-brainstorming`
-  设计先行的澄清流程与显式审批门
-- `ultra-planning`
-  TaskManifest、WorkPackage、DAG 和写锁边界
-- `ultra-execution-control`
-  dispatch、freeze/careful/guard、host-driven ledger
-- `ultra-review`
-  spec fidelity、evidence、downside risk 审查
-- `ultra-qa`
-  static + dynamic QA 双模式
-- `ultra-risk-vetting`
-  风险分级、审批门槛和护栏选择
-- `ultra-delivery`
-  final deliverable、orchestration log、vetter report 和 retro 交付
-- `openspec-ultra-bridge-v2`
-  将 OpenSpec change 资产桥接成 Ultra 执行工件
-
-## 推荐调用方式
-
-### 通用任务
+## 运行模式
+
+主入口启动后必须先判断运行模式：
+
+- `LIGHT`
+  适合 review-only、QA-only、解释类或用户明确要求轻量执行的任务。
+- `STANDARD`
+  适合用户明确要求快速编排、且风险低的任务。
+- `STRICT`
+  适合无法使用 OpenSpec，但仍需要 ledger 和 JSON contracts 的开发任务。
+- `STRICT_OPENSPEC`
+  开发任务默认优先模式，适合 feature、bugfix、多文件实现、pilot、完整控制面验证和 slice DAG 执行。
+
+开发任务应优先进入 `STRICT_OPENSPEC`。如果无法使用该模式，agent 必须说明降级原因。
+
+## 推荐试跑
+
+### 普通开发任务
 
 ```text
-$ultra-vnext-core 构建一个工作区模型默认值设置页。
+$ultra-orchestrator 构建一个工作区模型默认值设置页。
 ```
 
-主入口会按需要路由到设计澄清、规划、风险门、执行、审查、QA 和交付阶段。
+期望行为：
 
-最短成功链路：
-
-`ultra-vnext-core -> auto route -> ultra-planning -> review-ready TaskManifest / WorkPackages`
+- 默认优先 `STRICT_OPENSPEC`
+- 若没有现成 OpenSpec change，先创建或要求创建 change scaffold
+- 初始化 run ledger
+- 产出 JSON `TaskManifest` 和 JSON `WorkPackage`
+- 运行 contract validation
+- 按 slice DAG 推进
+- delivery 输出 `control_surface_used`
 
 ### OpenSpec 项目
 
 ```text
-$ultra-vnext-core OpenSpec change <change-id 或路径>: 实现第一个 slice。
+$ultra-orchestrator OpenSpec change <change-id 或路径>: 实现第一个 slice。
 ```
 
 示例 change 路径：
 
-`<PROJECT_ROOT>\openspec\changes\<change-id>`
+```text
+<PROJECT_ROOT>\openspec\changes\<change-id>
+```
+
+期望行为：
 
-主入口会先路由到 `openspec-ultra-bridge-v2`，再继续进入 Ultra 的规划、执行、审查、QA 和交付流程。
+- 通过 `openspec-ultra-bridge` 桥接 proposal、design、tasks 和 ultra-bridge
+- 将 OpenSpec change 转成 Ultra execution artifacts
+- 再进入 planning、risk、dispatch、review、QA 和 delivery
 
-### Bug 修复
+### Review-only
 
 ```text
-$ultra-vnext-core bugfix: 审批通过后命令执行卡住。
+$ultra-orchestrator review this implementation
 ```
 
-主入口会建立最小调查计划，识别回归面，执行风险判断，并要求交付前提供 QA 证据。
+期望行为：
 
-## Planning 是第二道关键门
+- 允许 `LIGHT`
+- delivery 明确说明为什么未使用 OpenSpec、ledger 或 contract validation
 
-在 vNext 中，`ultra-planning` 是主入口之后的第二道关键门。
+## 严格控制面最低要求
 
-只有当 planning 输出满足以下条件，运行才可以进入受控 dispatch：
+`STRICT` 和 `STRICT_OPENSPEC` 运行必须具备：
 
-- 有 `TaskManifest`
-- 有一个或多个 `WorkPackage`
-- owned paths 明确
-- acceptance checks 可验证
-- 依赖顺序明确
-- risk 和 retry 假设明确
+- `ledger.json`
+- JSON `TaskManifest`
+- JSON `WorkPackage`
+- JSON 或结构化 `AgentResult`
+- `validate_contracts.py` 校验结果
+- review 结论
+- QA 结论
+- `control_surface_used`
 
-如果 planning 产物仍然依赖聊天上下文才能理解，则试跑视为失败。
+如果只能产出 Markdown 文档，本次试跑不能算 strict 成功。
 
 ## 辅助脚本
 
 初始化 run：
 
 ```powershell
-python <REPO_ROOT>\skills-vnext\ultra-vnext-core\scripts\new_run.py `
-  <PROJECT_ROOT>\runs-vnext `
-  --run-id run-001
+python <REPO_ROOT>\skills\ultra-orchestrator\scripts\new_run.py `
+  <PROJECT_ROOT>\runs `
+  --run-id run-001 `
+  --run-mode STRICT_OPENSPEC
 ```
 
-桥接 OpenSpec change：
+校验核心 contract：
 
 ```powershell
-python <REPO_ROOT>\skills-vnext\openspec-ultra-bridge-v2\scripts\bridge_change.py `
-  <PROJECT_ROOT>\openspec\changes\<change-id> `
-  <PROJECT_ROOT>\runs-vnext\bridge-output
+python <REPO_ROOT>\skills\ultra-orchestrator\scripts\validate_contracts.py `
+  <PROJECT_ROOT>\runs\run-001\ledger.json `
+  --kind executionledger
 ```
 
-校验核心 contract：
+校验完整 run：
 
 ```powershell
-python <REPO_ROOT>\skills-vnext\ultra-vnext-core\scripts\validate_contracts.py `
-  <PROJECT_ROOT>\runs-vnext\run-001\ledger.json `
-  --kind executionledger
+python <REPO_ROOT>\skills\ultra-orchestrator\scripts\validate_run.py `
+  <PROJECT_ROOT>\runs\run-001
 ```
 
-## 不安装时如何调用
-
-如果暂时不想安装 vNext，可以让 agent 直接读取主入口技能文件：
+桥接 OpenSpec change：
 
-```text
-请读取并使用 <REPO_ROOT>\skills-vnext\ultra-vnext-core\SKILL.md。
-任务：OpenSpec change <PROJECT_ROOT>\openspec\changes\<change-id>，实现第一个 slice。
+```powershell
+python <REPO_ROOT>\skills-vnext\openspec-ultra-bridge-v2\scripts\bridge_change.py `
+  <PROJECT_ROOT>\openspec\changes\<change-id> `
+  <PROJECT_ROOT>\runs\bridge-output
 ```
 
 ## 成功判断
 
-一次试跑可以认为成功，当它满足：
+一次主线试跑可以认为成功，当它满足：
 
-- 用户只需要调用 `ultra-vnext-core` 主入口
-- 主入口能正确识别通用任务、OpenSpec change 或 bugfix
-- 实现前存在明确 design 或 OpenSpec change
-- `ultra-planning` 已作为第二道关键门发挥作用
+- 用户只需要调用 `ultra-orchestrator`
+- 开发任务默认优先 `STRICT_OPENSPEC`
+- 无 OpenSpec change 时不会直接降级为 Markdown-only 编排
+- strict run 使用 ledger、JSON artifacts 和 contract validation
 - `TaskManifest` 和 `WorkPackage` 不依赖聊天历史也能被理解
-- 风险门有明确分级和 guardrail
-- review 有 accept / reject / reroute 结论
-- QA 明确区分 static evidence 与 dynamic evidence
-- delivery 产出 `final_deliverable`、`orchestration_log`、`vetter_report`
-- 残余风险和 follow-up 被单独列出
+- slice status、owned paths、review gate 和 QA gate 明确
+- delivery 输出 `final_deliverable`、`orchestration_log`、`vetter_report` 和 `control_surface_used`
+- 残余风险和 skipped control surfaces 被单独列出

docs/ultra-vnext-pilot-guide-CN.md

@@ -1,11 +1,13 @@
 # Ultra Orchestration vNext Skill Tree
 
-This directory contains the vNext preview suite for Ultra Orchestration. The
-skills are compatible with agents that support `SKILL.md`-based Agent Skills.
+This directory contains vNext compatibility aliases and preview internals for
+Ultra Orchestration. The main public entry point now lives in
+`../skills/ultra-orchestrator`.
 
 ## Goals
 
-- provide a stricter orchestration protocol for complex engineering work
+- preserve vNext invocation compatibility while the strict protocol moves into
+  the mainline `ultra-orchestrator`
 - keep specification, execution, review, QA, risk, and delivery roles explicit
 - support artifact-driven handoff instead of full chat-history inheritance
 - make risk decisions, QA evidence, and final delivery logs auditable
@@ -35,8 +37,7 @@ or role boundaries.
 ## Skills
 
 - `ultra-vnext-core`
-  primary entry point, router, shared contracts, state-machine rules,
-  host-driven ledger, and helper scripts
+  compatibility alias for the mainline `ultra-orchestrator` strict protocol
 - `ultra-brainstorming`
   design-first discovery and approval gates before planning or coding
 - `ultra-planning`
@@ -54,11 +55,11 @@ or role boundaries.
 - `openspec-ultra-bridge-v2`
   map OpenSpec change assets into Ultra execution artifacts
 
-## Stable To vNext Mapping
+## Mainline Relationship
 
-| vNext skill | Stable relationship | Migration type |
+| vNext skill | Mainline relationship | Migration type |
 |---|---|---|
-| `ultra-vnext-core` | `ultra-orchestrator` | shared kernel |
+| `ultra-vnext-core` | `ultra-orchestrator` | compatibility alias |
 | `ultra-brainstorming` | `clarify-and-intake` + early `autoplan` | enhanced version |
 | `ultra-planning` | `decision-complete-planner` | direct counterpart |
 | `ultra-execution-control` | `dispatch-and-track` + part of `safety-guard` | integrated version |
@@ -71,20 +72,21 @@ or role boundaries.
 ## Usage
 
 Install these folders into your target agent's documented skills directory.
-Start with the main entry skill:
+Start new work with the mainline entry skill:
 
 ```text
-$ultra-vnext-core <task description>
+$ultra-orchestrator <task description>
 ```
 
-For OpenSpec projects:
+Existing vNext prompts still work:
 
 ```text
 $ultra-vnext-core OpenSpec change <change-id or path>: <task description>
 ```
 
-`ultra-vnext-core` routes to the other vNext skills as needed, so users do not
-need to list every subskill in the startup prompt.
+`ultra-vnext-core` should follow the same run-mode decision rules as
+`ultra-orchestrator`, including `STRICT_OPENSPEC` preference for development
+work.
 
 `ultra-planning` is the hard gate before controlled dispatch. If the resulting
 plan still leaves key decisions to the implementer, the run is not ready.

skills-vnext/README.md

@@ -7,6 +7,9 @@ description: Bridge OpenSpec change artifacts into Codex Ultra vNext execution c
 
 OpenSpec is the specification layer. Ultra remains the control plane.
 
+This skill is a compatibility bridge for vNext users. The default public entry
+point is now `$ultra-orchestrator`, which invokes this bridge as needed.
+
 ## What This Skill Does
 
 Translate:
@@ -28,6 +31,8 @@ into:
 2. Prefer one bounded `change` as the default execution unit.
 3. Use OpenSpec for durable spec memory and archive history.
 4. Use Ultra for dispatch, retries, review, QA, and delivery.
+5. In `STRICT_OPENSPEC`, do not continue without change scaffold, slice status,
+   JSON-ready planning artifacts, and ledger handoff.
 
 ## How To Use
 
@@ -38,6 +43,37 @@ into:
    set.
 5. Hand off those outputs to `ultra-planning` or `ultra-execution-control`.
 
+## Required Change Scaffold
+
+For newly opened strict changes, initialize at minimum:
+
+- `proposal.md`
+- `design.md`
+- `tasks.md`
+- `ultra-bridge.md`
+
+Default status:
+
+- `slice_0_spec_ready` when the change is ready for implementation
+- `slice_0_not_opened` only for unopened planned changes
+
+## Slice Contract
+
+Keep `change` and `slice` separate:
+
+- OpenSpec `change` is the durable spec and progress node
+- Ultra `slice` is the implementation and verification unit
+
+Every bridge output should name:
+
+- `change_id`
+- current slice status
+- next slice
+- owned paths
+- review targets
+- QA targets
+- blockers for status sync or archive
+
 ## Script
 
 Use `scripts/bridge_change.py` to extract and materialize bridge artifacts from