@betterdanlins/ai-memory 0.3.0 → 0.4.0

package/README.md

@@ -21,6 +21,9 @@ npx @betterdanlins/ai-memory init
 # Non-interactive
 npx @betterdanlins/ai-memory init --name demo --stack "PHP + Vue" --tools claude,codex --yes
 
+# Opt in to staged model routing
+npx @betterdanlins/ai-memory init --model-profile balanced --yes
+
 # Import user-level memory (profile/feedback) from an existing project
 npx @betterdanlins/ai-memory init --import /path/to/other-project
 
@@ -29,6 +32,9 @@ npx @betterdanlins/ai-memory update --dry-run
 
 # Apply only conflict-free safe updates; abort entirely on user changes
 npx @betterdanlins/ai-memory update --yes
+
+# Switch an initialized project from inherited models to staged routing
+npx @betterdanlins/ai-memory models configure --profile balanced
 ```
 
 Nothing is ever overwritten silently: existing files are asked about one by one (interactive) or skipped (`--yes`).
@@ -36,12 +42,45 @@ An invalid, non-directory, or unreadable `--import` project path fails explicitl
 Before writing, the CLI checks for duplicate template destinations, path traversal, and symbolic links, then reads and renders every planned file. If an actual filesystem write fails midway, the error summary lists both written and not-yet-written files.
 An initialized project cannot be initialized again. A newer CLI first uses `update --dry-run` to identify versions and user modifications. `update --yes` applies only additions and baseline-matching safe updates, aborting before any write when merge or review items exist.
 
+## Versions and compatibility
+
+### v0.4.0 — staged model routing and verified handoffs
+
+- Adds opt-in `inherit`, `balanced`, and `quality` profiles. New and upgraded projects default to `inherit`, so installing v0.4.0 does not silently increase model cost or change v0.3.0 workflow depth.
+- Adds native Claude Code and Codex agents for premium planning/review, standard or premium implementation, and economy or standard test authoring. Model routing selects an executor only after the existing S/M/L workflow decides which stages are required.
+- Adds `models show/configure` plus `workflow prepare/verify/complete`. Cross-model handoffs reference formal requirements, designs, and plans by path and SHA-256; stale inputs, unresolved decisions, route changes, unsafe paths, and incomplete acceptance receipts fail closed.
+- Keeps `.ai/config/model-routing.json` user-owned and `.ai/runs/` local-only. Exact account entitlements are not auto-discovered: Claude uses native model aliases, while Codex agents use native reasoning-effort settings.
+
+### v0.3.0 — safe framework upgrades and engineering workflow
+
+- Introduced `.ai/ai-memory.json` framework/schema metadata, file ownership, generated baseline hashes, legacy v0.1 detection, and explicit migration planning.
+- Added `update --dry-run` and conflict-free `update --yes`. User memory, requirements, architecture, and design assets are preserved; changed framework or mixed files require review instead of being overwritten.
+- Added duplicate-destination checks, path traversal and symlink/junction protection, three-phase scaffolding, and diagnostic partial-write summaries.
+- Added the language-agnostic `project-inception`, `feature-design`, and `delivery-readiness` workflows covering data modeling, technical contracts, deployment, performance, observability, scalability, reliability, security, and cost.
+
+### Upgrade from v0.3.0 to v0.4.0
+
+```bash
+# Preview only; this must not modify the project
+npx @betterdanlins/ai-memory@0.4.0 update --dry-run
+
+# Apply only when the preview has no merge/review blockers
+npx @betterdanlins/ai-memory@0.4.0 update --yes
+
+# Optional: explicitly enable staged routing after the safe update
+npx @betterdanlins/ai-memory@0.4.0 models configure --profile balanced
+```
+
+After the update, the profile remains `inherit` until explicitly changed. Do not re-run `init` on an existing v0.3.0 project. If dry-run reports merge or review items, merge them with the generated v0.4.0 files as references, then run dry-run again.
+
 ## What it generates
 
 ```
 .ai/                          # single source of truth, shared by all agents
 ├── README.md                 # session entry protocol
 ├── ai-memory.json            # version, schema, tools, ownership, baseline hashes
+├── config/
+│   └── model-routing.json    # inherit/balanced/quality stage routing; user-owned
 ├── memory/
 │   ├── MEMORY.md             # index — agents read this first
 │   ├── project-state.md      # stack, current version, requirement progress
@@ -49,8 +88,9 @@ An initialized project cannot be initialized again. A newer CLI first uses `upda
 │   ├── user-profile.md       # background, preferences, communication style
 │   ├── feedback.md           # behavioral norms distilled from feedback
 │   └── features/             # per-feature dossiers
+├── runs/                     # local handoffs and stage receipts; ignored by Git
 └── skills/                   # methodology: requirements-flow, architecture,
-                              # project-inception, feature-design, delivery-readiness, etc.
+                              # feature-design, model-routing, delivery-readiness, etc.
 
 docs/architecture/            # engineering baseline for 0-to-1 projects
 ├── system-context.md         # boundaries, actors, modules, and key flows
@@ -66,7 +106,7 @@ docs/design/vX.Y.Z/           # M/L-risk feature how, technical contracts, delta
 
 # Thin adapters, generated only for the tools you enable:
 CLAUDE.md + .claude/          # Claude Code: commands, skills, agents, settings
-AGENTS.md + .agents/          # Codex: skills
+AGENTS.md + .agents/ + .codex/# Codex: skills and model-specific custom agents
 ```
 
 ## CLI commands
@@ -76,6 +116,11 @@ AGENTS.md + .agents/          # Codex: skills
 | `init` | Initialize a new project; refuses to run over an existing ai-memory installation |
 | `update --dry-run` | Read-only analysis of the upgrade plan from an existing project to this CLI version |
 | `update --yes` | Apply conflict-free safe updates; refuse user changes, mixed-file conflicts, or missing migration paths |
+| `models show` | Show the selected profile and resolved tier for every workflow stage |
+| `models configure --profile <name>` | Select `inherit`, `balanced`, or `quality` without changing requirements, designs, or code |
+| `workflow prepare` | Create a local handoff manifest with hashes of formal input documents |
+| `workflow verify` | Reject missing, stale, unresolved, or route-mismatched handoffs before execution |
+| `workflow complete` | Validate and store a structured stage receipt for downstream review |
 
 ### `init` options
 
@@ -84,17 +129,20 @@ AGENTS.md + .agents/          # Codex: skills
 | `--name <name>` | Project name (defaults to the current directory name) |
 | `--stack <desc>` | Tech-stack description |
 | `--tools <list>` | Comma-separated adapters to enable: `claude`, `codex` |
+| `--model-profile <profile>` | `inherit` (default), `balanced`, or `quality`; `--yes` never opts into costly routing implicitly |
 | `--import <path>` | Import `user-profile` / `feedback` from an existing project |
 | `--yes` | Non-interactive: fill defaults, skip on any conflict |
 
 ## How it works
 
-The generator is a small set of pure functions:
+The generator is a small set of focused modules:
 
 - **manifest** — walks the `common` / `claude` / `codex` template groups, keeping only the groups whose tools are enabled, and produces a flat `{src, dest}` list; duplicate destinations fail before writing and list every source.
 - **render** — substitutes `{{variable}}` placeholders and throws on any undefined variable, so a broken template fails loudly instead of shipping `{{...}}`.
 - **scaffold** — validates safe destinations and symbolic links, resolves conflicts, and reads/renders the complete plan in memory before writing; it also validates `--import` and pulls `user-profile` / `feedback` from it (falling back to the template with an explicit report when an individual source file is missing).
 - **framework metadata** — a fresh init records framework/schema versions, ownership, and generated hashes; update uses them to distinguish safe updates from user changes. Metadata-free v0.1 projects are planned conservatively as legacy installations.
+- **model routing** — optional profiles map existing workflow stages to premium, standard, economy, inherited, or no-model execution. Claude and Codex adapters use native custom-agent configuration; routing never creates extra S/M/L stages.
+- **workflow handoff** — a local manifest references formal requirements/design/plan files by path and SHA-256. Verification fails closed on stale inputs, unresolved decisions, changed routing, path escape, or symbolic links.
 
 ## Design principles
 
@@ -103,6 +151,8 @@ The generator is a small set of pure functions:
 - **Dual requirement directories** — human draft (`draft/`) → AI final (`final/`) behind a mandatory critic gate.
 - **Project engineering baseline** — 0-to-1 projects establish language-agnostic system, data, quality-attribute, and deployment baselines once; ordinary features record only deltas.
 - **Risk-tiered design** — S-risk requirements proceed directly to implementation; M/L-risk work uses feature-design for how, technical contracts, and engineering impact, with Superpowers selected only when justified by risk.
+- **Optional cost routing** — `inherit` preserves prior behavior; explicit profiles can use stronger models for planning/review and cheaper workers for bounded test work while deterministic test execution uses no model.
+- **Artifact-based handoff** — cross-model stages read formal artifacts through a verified handoff rather than relying on conversational summaries; implementation receipts expose coverage, deviations, and unresolved risk to the final reviewer.
 - **Evidence-based delivery** — before release, verify applicable contracts, tests, migration, rollback, performance, observability, and operations, producing an explicit readiness verdict.
 - **Low-noise memory** — persist independently verifiable engineering nodes, durable decisions, status changes, and session handoffs instead of every small coding step.
 - **Idempotent** — existing files are asked about one by one; `--yes` always skips. Never a silent overwrite.

package/README.zh-CN.md

@@ -21,6 +21,9 @@ npx @betterdanlins/ai-memory init
 # 非交互式
 npx @betterdanlins/ai-memory init --name demo --stack "PHP + Vue" --tools claude,codex --yes
 
+# 显式启用分阶段模型路由
+npx @betterdanlins/ai-memory init --model-profile balanced --yes
+
 # 从已有项目导入用户级记忆(profile/feedback)
 npx @betterdanlins/ai-memory init --import /path/to/other-project
 
@@ -29,6 +32,9 @@ npx @betterdanlins/ai-memory update --dry-run
 
 # 只应用无冲突的安全更新;有用户修改时整体拒绝
 npx @betterdanlins/ai-memory update --yes
+
+# 已初始化项目从继承模型切换到分层路由
+npx @betterdanlins/ai-memory models configure --profile balanced
 ```
 
 绝不静默覆盖:已存在的文件会逐个询问(交互式),或直接跳过(`--yes`)。
@@ -36,12 +42,45 @@ npx @betterdanlins/ai-memory update --yes
 生成前会检查重复模板目标、路径越界和符号链接;模板读取与渲染全部通过后才开始写入。若实际磁盘写入中途失败,错误摘要会列出已经写入和尚未写入的文件。
 已初始化项目不能重新运行 `init`;新版 CLI 先通过 `update --dry-run` 识别版本和用户修改。`update --yes` 只应用新增和基线哈希匹配的安全更新,存在合并/审查项时在写入前整体拒绝。
 
+## 版本与兼容性
+
+### v0.4.0 —— 分阶段模型路由与可靠交接
+
+- 新增可选的 `inherit`、`balanced`、`quality` profile。新项目和升级项目默认保持 `inherit`,安装 v0.4.0 不会静默增加模型成本,也不会改变 v0.3.0 的工作流深度。
+- 为 Claude Code 和 Codex 新增原生分层 agents,覆盖高级规划/审查、中等或高级实现、低成本或中等测试编写。仍先由原有 S/M/L 流程决定是否需要某个阶段,模型路由只选择执行者。
+- 新增 `models show/configure` 和 `workflow prepare/verify/complete`。跨模型交接通过路径和 SHA-256 引用正式需求、设计与计划;输入过期、未决问题、路由变化、不安全路径和验收回执缺失都会关闭式失败。
+- `.ai/config/model-routing.json` 属于用户配置,`.ai/runs/` 只保存本地运行状态。框架不会自动探测账号模型权限:Claude 使用原生模型别名,Codex agents 使用原生推理等级。
+
+### v0.3.0 —— 安全升级与工程工作流
+
+- 引入 `.ai/ai-memory.json` 框架/Schema 元数据、文件所有权、生成基线哈希、v0.1 legacy 检测和显式迁移规划。
+- 新增 `update --dry-run` 与无冲突 `update --yes`。用户记忆、需求、架构和设计资产始终保留;修改过的框架文件或混合文件进入人工审查,不会被直接覆盖。
+- 增加重复目标、路径穿越、符号链接/junction 防护、三阶段生成和可诊断的部分写入摘要。
+- 增加语言无关的 `project-inception`、`feature-design`、`delivery-readiness`,覆盖数据建模、技术接口、部署、性能、可观测性、扩展性、可靠性、安全和成本。
+
+### 从 v0.3.0 升级到 v0.4.0
+
+```bash
+# 只读预览,不得修改项目
+npx @betterdanlins/ai-memory@0.4.0 update --dry-run
+
+# 仅在预览没有 merge/review 阻塞项时应用
+npx @betterdanlins/ai-memory@0.4.0 update --yes
+
+# 可选:安全升级后显式启用分阶段模型路由
+npx @betterdanlins/ai-memory@0.4.0 models configure --profile balanced
+```
+
+升级完成后 profile 仍为 `inherit`,只有显式配置才会改变。不要在已有 v0.3.0 项目重新运行 `init`。若 dry-run 出现 merge/review 项,应以新生成的 v0.4.0 文件为参考人工合并,然后重新执行 dry-run。
+
 ## 生成什么
 
 ```
 .ai/                          # 单一源,所有 agent 共享
 ├── README.md                 # 会话进场协议
 ├── ai-memory.json            # 版本、Schema、工具、所有权和生成基线哈希
+├── config/
+│   └── model-routing.json    # inherit/balanced/quality 阶段路由;属于用户配置
 ├── memory/
 │   ├── MEMORY.md             # 索引 —— agent 进场先读
 │   ├── project-state.md      # 技术栈、当前版本、需求进度
@@ -49,8 +88,9 @@ npx @betterdanlins/ai-memory update --yes
 │   ├── user-profile.md       # 背景、偏好、沟通方式
 │   ├── feedback.md           # 从反馈提炼的行为规范
 │   └── features/             # 功能档案
+├── runs/                     # 本地交接与阶段回执;默认不进入 Git
 └── skills/                   # 方法论:requirements-flow、architecture、
-                              # project-inception、feature-design、delivery-readiness 等
+                              # feature-design、model-routing、delivery-readiness 等
 
 docs/architecture/            # 0→1 项目工程基线
 ├── system-context.md         # 系统边界、参与者、模块和关键流程
@@ -66,7 +106,7 @@ docs/design/vX.Y.Z/           # M/L 级功能 how、技术接口与工程增量
 
 # 薄适配层,仅为你启用的工具生成:
 CLAUDE.md + .claude/          # Claude Code:commands、skills、agents、settings
-AGENTS.md + .agents/          # Codex:skills
+AGENTS.md + .agents/ + .codex/# Codex:skills 与分层自定义 agents
 ```
 
 ## CLI 命令
@@ -76,6 +116,11 @@ AGENTS.md + .agents/          # Codex:skills
 | `init` | 初始化全新项目;检测到已有 ai-memory 安装时拒绝执行 |
 | `update --dry-run` | 只读分析旧项目到当前 CLI 版本的升级计划 |
 | `update --yes` | 应用无冲突安全更新;用户修改、混合文件冲突或缺失迁移路径会拒绝执行 |
+| `models show` | 显示当前 profile 和每个阶段解析后的模型等级 |
+| `models configure --profile <name>` | 选择 `inherit`、`balanced` 或 `quality`,不修改需求、设计或代码 |
+| `workflow prepare` | 用正式输入文档的哈希创建本地交接清单 |
+| `workflow verify` | 执行前拒绝缺失、过期、有未决问题或路由不匹配的交接 |
+| `workflow complete` | 校验并保存供后续审查使用的结构化阶段回执 |
 
 ### `init` 选项
 
@@ -84,17 +129,20 @@ AGENTS.md + .agents/          # Codex:skills
 | `--name <name>` | 项目名(默认取当前目录名) |
 | `--stack <desc>` | 技术栈描述 |
 | `--tools <list>` | 逗号分隔的适配层:`claude`、`codex` |
+| `--model-profile <profile>` | `inherit`(默认)、`balanced` 或 `quality`;`--yes` 不会静默启用高成本路由 |
 | `--import <path>` | 从已有项目导入 `user-profile` / `feedback` |
 | `--yes` | 非交互模式:缺参用默认值,冲突一律跳过 |
 
 ## 工作原理
 
-生成器由一组纯函数构成:
+生成器由一组职责明确的小模块构成:
 
 - **manifest** —— 遍历 `common` / `claude` / `codex` 模板组,只保留已启用工具对应的组,产出一份扁平的 `{src, dest}` 清单;重复目标会在写入前报错并列出来源。
 - **render** —— 替换 `{{变量}}` 占位符,遇到任何未定义变量即抛错,让坏掉的模板大声失败,而不是把 `{{...}}` 发出去。
 - **scaffold** —— 预检安全目标路径和符号链接,处理冲突并在内存中完成全部读取/渲染后再逐个写入;提供 `--import` 时先校验导入目录,再从中拉取 `user-profile` / `feedback`(单个源文件缺失则回退到模板并明确报告)。
 - **framework metadata** —— 全新 init 记录 framework/schema 版本、文件所有权和生成哈希;update 据此区分安全更新与用户修改。无元数据的 v0.1 项目按 legacy 保守规划。
+- **model routing** —— 可选 profile 把现有阶段映射为 premium、standard、economy、inherit 或无模型执行;Claude/Codex 使用原生自定义 agent 配置,路由不会增加 S/M/L 阶段。
+- **workflow handoff** —— 本地清单只用路径和 SHA-256 引用正式需求/设计/计划;输入过期、未决问题、路由变化、路径越界或符号链接都会关闭式失败。
 
 ## 设计原则
 
@@ -103,6 +151,8 @@ AGENTS.md + .agents/          # Codex:skills
 - **需求双目录** —— 人工粗稿(`draft/`)→ AI 定稿(`final/`),中间隔一道强制 critic 门。
 - **项目工程基线** —— 0→1 项目先建立语言无关的系统、数据、质量属性和部署基线;普通功能只记录增量,不重复设计全局架构。
 - **风险分级设计** —— S 级需求直接实现;M/L 级用 feature-design 补齐 how、技术接口和工程影响,Superpowers 只按风险选择使用。
+- **可选成本路由** —— `inherit` 保持旧行为;显式 profile 才用高级模型规划/审查和低成本 worker 做有边界的测试工作,确定性测试执行不调用模型。
+- **工程产物交接** —— 跨模型阶段通过校验后的正式文档交接,不依赖对话摘要;阶段回执向最终 reviewer 暴露验收覆盖、设计偏差和未决风险。
 - **证据化交付** —— 发布前按风险检查契约、测试、迁移、回滚、性能、可观测性和运行保障,输出明确 ready 状态。
 - **低噪声记忆** —— 只在可验收工程节点、关键决策、状态变化和会话切换时落盘,不记录每个细碎代码步骤。
 - **幂等** —— 已存在的文件逐个询问;`--yes` 一律跳过。绝不静默覆盖。

package/bin/cli.js

@@ -4,7 +4,12 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { applyFrameworkUpdate, detectInstallation, METADATA_DEST, planFrameworkUpdate, writeFrameworkMetadata } from '../src/framework.js';
+import {
+  createModelRoutingConfig, MODEL_PROFILES, readModelRoutingConfig,
+  resolveModelRouting, writeModelRoutingConfig,
+} from '../src/model-routing.js';
 import { ScaffoldError, scaffold } from '../src/scaffold.js';
+import { prepareHandoff, recordStageResult, verifyHandoff } from '../src/workflow.js';
 
 const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates');
 const PACKAGE = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
@@ -18,6 +23,7 @@ program
   .option('--name <name>', '项目名')
   .option('--stack <desc>', '技术栈描述')
   .option('--tools <list>', '启用工具,逗号分隔:claude,codex')
+  .option('--model-profile <profile>', '模型路由策略:inherit,balanced,quality', 'inherit')
   .option('--import <path>', '从已有项目导入 user-profile/feedback')
   .option('--yes', '非交互模式:缺参用默认值,冲突一律跳过')
   .action(async (opts) => {
@@ -30,6 +36,9 @@ program
       throw new Error(`${label};不要重新运行 init,请先执行 ai-memory update --dry-run`);
     }
     let { name, stack, tools: toolsRaw } = opts;
+    if (!MODEL_PROFILES.includes(opts.modelProfile)) {
+      throw new Error(`model profile 仅支持 ${MODEL_PROFILES.join('、')},收到: ${opts.modelProfile}`);
+    }
 
     // Validate CLI-supplied --tools before entering interactive prompts
     if (toolsRaw !== undefined) {
@@ -43,7 +52,7 @@ program
 
     let importFrom = opts.import;
     if (!opts.yes) {
-      const { input, checkbox } = await import('@inquirer/prompts');
+      const { input, checkbox, select } = await import('@inquirer/prompts');
       name ??= await input({ message: '项目名:', default: path.basename(targetDir) });
       stack ??= await input({ message: '技术栈描述:', default: '(待补充)' });
       toolsRaw ??= (await checkbox({
@@ -56,6 +65,17 @@ program
       importFrom ??= (await input({
         message: '从已有项目导入 user-profile/feedback?(输入项目路径,留空跳过)', default: '',
       })) || undefined;
+      if (opts.modelProfile === 'inherit') {
+        opts.modelProfile = await select({
+          message: '模型路由策略:',
+          choices: [
+            { name: 'inherit - 继承当前会话模型,兼容旧行为', value: 'inherit' },
+            { name: 'balanced - 高级规划/中等实现/便宜测试/高级审查', value: 'balanced' },
+            { name: 'quality - 关键实现与诊断也使用高级模型', value: 'quality' },
+          ],
+          default: 'inherit',
+        });
+      }
     }
     name ??= path.basename(targetDir);
     stack ??= '(待补充)';
@@ -74,7 +94,9 @@ program
         };
 
     const date = new Date().toISOString().slice(0, 10);
-    const vars = { projectName: name, techStack: stack, date };
+    const vars = {
+      projectName: name, techStack: stack, date, modelProfile: opts.modelProfile, frameworkVersion: PACKAGE.version,
+    };
     const r = await scaffold({ templatesRoot: TEMPLATES, targetDir, vars, tools, onConflict, importFrom });
     if (r.skipped.length === 0) {
       try {
@@ -93,12 +115,81 @@ program
       console.log('警告:存在冲突跳过项,未创建框架元数据;当前结果不能自动升级');
     }
     console.log(`完成:写入 ${r.written.length},跳过 ${r.skipped.length}`);
+    console.log(`模型路由:${opts.modelProfile}`);
     if (r.imported.length) for (const d of r.imported) console.log(`  已导入 ${d}`);
     if (r.fallback.length) for (const d of r.fallback) console.log(`  导入源缺失,使用模板 ${d}`);
     if (r.skipped.length) for (const d of r.skipped) console.log(`  跳过 ${d}`);
     console.log('下一步:打开项目让 agent 读 .ai/memory/MEMORY.md;把项目命令补进 CLAUDE.md/AGENTS.md。');
   });
 
+const models = program.command('models').description('查看或配置阶段模型路由');
+
+models
+  .command('show')
+  .description('显示当前模型路由配置与阶段映射')
+  .action(async () => {
+    const config = await readModelRoutingConfig(process.cwd());
+    console.log(`模型路由:${config.profile}`);
+    for (const [stage, tier] of Object.entries(resolveModelRouting(config))) console.log(`  ${stage}: ${tier}`);
+  });
+
+models
+  .command('configure')
+  .description('切换模型路由预设;不修改需求、设计或代码')
+  .requiredOption('--profile <profile>', 'inherit,balanced,quality')
+  .action(async (opts) => {
+    const installation = await detectInstallation(process.cwd());
+    if (installation.kind === 'none') throw new Error('当前目录不是 ai-memory 项目,请先运行 init');
+    const current = await readModelRoutingConfig(process.cwd());
+    const next = createModelRoutingConfig(opts.profile);
+    next.overrides = current.overrides;
+    await writeModelRoutingConfig(process.cwd(), next);
+    console.log(`模型路由已切换:${current.profile} → ${next.profile}`);
+  });
+
+const workflow = program.command('workflow').description('创建并校验跨模型阶段交接');
+
+workflow
+  .command('prepare')
+  .description('根据正式文档生成带哈希的本地交接清单')
+  .requiredOption('--feature <id>', '功能标识,不得包含路径分隔符')
+  .requiredOption('--stage <stage>', '目标工作流阶段')
+  .requiredOption('--risk <level>', 'S,M,L')
+  .option('--input <path>', '正式输入文件,可重复', collect, [])
+  .option('--acceptance <id>', '验收标准编号,可重复', collect, [])
+  .option('--scope <path>', '允许变更范围,可重复', collect, [])
+  .option('--unresolved <text>', '未决问题,可重复;存在时 verify 会阻止进入阶段', collect, [])
+  .action(async (opts) => {
+    const result = await prepareHandoff({
+      targetDir: process.cwd(), feature: opts.feature, stage: opts.stage, risk: opts.risk,
+      inputs: opts.input, acceptanceCriteria: opts.acceptance, allowedChangeScope: opts.scope,
+      unresolvedDecisions: opts.unresolved,
+    });
+    console.log(`交接清单已生成:${result.path}`);
+    console.log(`执行等级:${result.handoff.executorTier}`);
+    if (result.handoff.unresolvedDecisions.length) console.log(`警告:仍有 ${result.handoff.unresolvedDecisions.length} 个未决问题`);
+  });
+
+workflow
+  .command('verify')
+  .description('验证交接输入、哈希、路由和未决问题')
+  .requiredOption('--feature <id>', '功能标识')
+  .option('--stage <stage>', '期望工作流阶段')
+  .action(async (opts) => {
+    const handoff = await verifyHandoff({ targetDir: process.cwd(), feature: opts.feature, expectedStage: opts.stage });
+    console.log(`交接校验通过:${handoff.featureId} / ${handoff.stage} / ${handoff.executorTier}`);
+  });
+
+workflow
+  .command('complete')
+  .description('校验阶段回执并保存到对应 run 目录')
+  .requiredOption('--feature <id>', '功能标识')
+  .requiredOption('--result <path>', '项目内阶段回执 JSON 路径')
+  .action(async (opts) => {
+    const recorded = await recordStageResult({ targetDir: process.cwd(), feature: opts.feature, resultPath: opts.result });
+    console.log(`阶段回执已记录:${recorded.path} / ${recorded.result.status}`);
+  });
+
 program
   .command('update')
   .description('检查当前项目升级到本 CLI 版本所需的变更')
@@ -167,3 +258,7 @@ function printUpdatePlan(plan) {
   console.log('升级计划完成');
   if (process.argv.includes('--dry-run')) console.log('dry-run:未修改任何文件');
 }
+
+function collect(value, previous) {
+  return [...previous, value];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterdanlins/ai-memory",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AI memory + requirements workflow scaffolder for Claude Code & Codex",
   "type": "module",
   "bin": {

package/src/framework.js

@@ -12,6 +12,7 @@ export const CURRENT_SCHEMA_VERSION = 1;
 export const METADATA_DEST = '.ai/ai-memory.json';
 
 const USER_PREFIXES = [
+  '.ai/config/',
   '.ai/memory/',
   'docs/architecture/',
   'docs/requirements/v',
@@ -88,7 +89,8 @@ export async function planFrameworkUpdate({ targetDir, templatesRoot, frameworkV
   if (installation.kind === 'none') throw new Error('当前目录不是 ai-memory 项目,请先运行 init');
 
   const tools = installation.kind === 'metadata' ? installation.metadata.tools : installation.tools;
-  const vars = installation.kind === 'metadata' ? installation.metadata.templateVars : installation.templateVars;
+  const rawVars = installation.kind === 'metadata' ? installation.metadata.templateVars : installation.templateVars;
+  const vars = { modelProfile: 'inherit', ...rawVars, frameworkVersion };
   if (installation.kind === 'metadata' && compareVersions(installation.metadata.frameworkVersion, frameworkVersion) > 0) {
     throw new Error(`项目框架版本 ${installation.metadata.frameworkVersion} 高于当前 CLI ${frameworkVersion},请使用更新版本的 CLI`);
   }
@@ -138,6 +140,7 @@ export async function planFrameworkUpdate({ targetDir, templatesRoot, frameworkV
     frameworkVersion,
     schemaVersion: CURRENT_SCHEMA_VERSION,
     tools,
+    templateVars: vars,
     migrations,
     actions,
   };
@@ -153,9 +156,7 @@ export async function applyFrameworkUpdate({ targetDir, templatesRoot, plan }) {
     throw new Error(`存在不可自动执行的 Schema 迁移: ${manualMigrations.map(item => item.id).join(', ')}`);
   }
 
-  const vars = plan.installation.kind === 'metadata'
-    ? plan.installation.metadata.templateVars
-    : plan.installation.templateVars;
+  const vars = plan.templateVars;
   const manifest = await buildManifest(templatesRoot, plan.tools);
   const sources = new Map(manifest.map(entry => [entry.dest, entry.src]));
   const candidates = [];

package/src/model-routing.js

@@ -0,0 +1,108 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { assertNoSymlinkPath } from './path-safety.js';
+
+export const MODEL_ROUTING_DEST = '.ai/config/model-routing.json';
+export const MODEL_ROUTING_SCHEMA_VERSION = 1;
+
+export const STAGES = [
+  'brainstorm',
+  'requirement-finalize',
+  'feature-design',
+  'write-plan',
+  'implementation',
+  'routine-tests',
+  'test-execution',
+  'failure-diagnosis',
+  'adversarial-testing',
+  'final-review',
+];
+
+const PROFILES = {
+  inherit: Object.fromEntries(STAGES.map(stage => [stage, stage === 'test-execution' ? 'none' : 'inherit'])),
+  balanced: {
+    brainstorm: 'premium',
+    'requirement-finalize': 'premium',
+    'feature-design': 'premium',
+    'write-plan': 'premium',
+    implementation: 'standard',
+    'routine-tests': 'economy',
+    'test-execution': 'none',
+    'failure-diagnosis': 'standard',
+    'adversarial-testing': 'premium',
+    'final-review': 'premium',
+  },
+  quality: {
+    brainstorm: 'premium',
+    'requirement-finalize': 'premium',
+    'feature-design': 'premium',
+    'write-plan': 'premium',
+    implementation: 'premium',
+    'routine-tests': 'standard',
+    'test-execution': 'none',
+    'failure-diagnosis': 'premium',
+    'adversarial-testing': 'premium',
+    'final-review': 'premium',
+  },
+};
+
+export const MODEL_PROFILES = Object.freeze(Object.keys(PROFILES));
+
+export function createModelRoutingConfig(profile = 'inherit') {
+  assertProfile(profile);
+  return { schemaVersion: MODEL_ROUTING_SCHEMA_VERSION, profile, overrides: {} };
+}
+
+export function resolveModelRouting(config) {
+  validateModelRoutingConfig(config);
+  return { ...PROFILES[config.profile], ...config.overrides };
+}
+
+export async function readModelRoutingConfig(targetDir) {
+  const configPath = path.join(targetDir, ...MODEL_ROUTING_DEST.split('/'));
+  await assertNoSymlinkPath(targetDir, configPath);
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new Error(`缺少模型路由配置: ${MODEL_ROUTING_DEST};请先更新 ai-memory 框架`);
+    if (err instanceof SyntaxError) throw new Error(`模型路由配置不是有效 JSON: ${MODEL_ROUTING_DEST}`, { cause: err });
+    throw err;
+  }
+  validateModelRoutingConfig(config);
+  return config;
+}
+
+export async function writeModelRoutingConfig(targetDir, config) {
+  validateModelRoutingConfig(config);
+  const configPath = path.join(targetDir, ...MODEL_ROUTING_DEST.split('/'));
+  await assertNoSymlinkPath(targetDir, configPath);
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+  return config;
+}
+
+export function validateModelRoutingConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('模型路由配置必须是对象');
+  }
+  if (config.schemaVersion !== MODEL_ROUTING_SCHEMA_VERSION) {
+    throw new Error(`不支持的模型路由 Schema: ${config.schemaVersion}`);
+  }
+  assertProfile(config.profile);
+  if (!config.overrides || typeof config.overrides !== 'object' || Array.isArray(config.overrides)) {
+    throw new Error('模型路由 overrides 必须是对象');
+  }
+  for (const [stage, tier] of Object.entries(config.overrides)) {
+    if (!STAGES.includes(stage)) throw new Error(`未知模型路由阶段: ${stage}`);
+    if (!['inherit', 'premium', 'standard', 'economy', 'none'].includes(tier)) {
+      throw new Error(`阶段 ${stage} 的模型等级无效: ${tier}`);
+    }
+  }
+}
+
+function assertProfile(profile) {
+  if (!MODEL_PROFILES.includes(profile)) {
+    throw new Error(`model profile 仅支持 ${MODEL_PROFILES.join('、')},收到: ${profile}`);
+  }
+}

package/src/workflow.js

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readModelRoutingConfig, resolveModelRouting, STAGES } from './model-routing.js';
+import { assertNoSymlinkPath } from './path-safety.js';
+
+const RISKS = ['S', 'M', 'L'];
+
+export async function prepareHandoff({
+  targetDir, feature, stage, risk, inputs, acceptanceCriteria = [], allowedChangeScope = [], unresolvedDecisions = [],
+}) {
+  validateFeature(feature);
+  if (!STAGES.includes(stage)) throw new Error(`未知工作流阶段: ${stage}`);
+  if (!RISKS.includes(risk)) throw new Error(`risk 仅支持 S、M、L,收到: ${risk}`);
+  if (!Array.isArray(inputs) || inputs.length === 0) throw new Error('至少需要一个 --input 正式输入文件');
+  if (requiresAcceptance(stage) && acceptanceCriteria.length === 0) {
+    throw new Error(`阶段 ${stage} 至少需要一个 --acceptance 验收标准编号`);
+  }
+
+  const routing = resolveModelRouting(await readModelRoutingConfig(targetDir));
+  const records = [];
+  for (const input of [...new Set(inputs)]) {
+    const { relative, absolute } = resolveProjectInput(targetDir, input);
+    await assertNoSymlinkPath(targetDir, absolute);
+    let content;
+    try {
+      content = await readFile(absolute);
+    } catch (err) {
+      if (err.code === 'ENOENT' || err.code === 'EISDIR') throw new Error(`交接输入不是可读文件: ${relative}`, { cause: err });
+      throw err;
+    }
+    records.push({ path: relative, sha256: createHash('sha256').update(content).digest('hex') });
+  }
+
+  const handoff = {
+    schemaVersion: 1,
+    featureId: feature,
+    riskLevel: risk,
+    stage,
+    executorTier: routing[stage],
+    createdAt: new Date().toISOString(),
+    inputs: records,
+    acceptanceCriteria: uniqueStrings(acceptanceCriteria),
+    unresolvedDecisions: uniqueStrings(unresolvedDecisions),
+    allowedChangeScope: uniqueStrings(allowedChangeScope),
+  };
+  const handoffPath = handoffFile(targetDir, feature);
+  await assertNoSymlinkPath(targetDir, handoffPath);
+  await mkdir(path.dirname(handoffPath), { recursive: true });
+  await writeFile(handoffPath, JSON.stringify(handoff, null, 2) + '\n');
+  return { handoff, path: relativeFromRoot(targetDir, handoffPath) };
+}
+
+export async function verifyHandoff({ targetDir, feature, expectedStage }) {
+  validateFeature(feature);
+  const handoffPath = handoffFile(targetDir, feature);
+  await assertNoSymlinkPath(targetDir, handoffPath);
+  let handoff;
+  try {
+    handoff = JSON.parse(await readFile(handoffPath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new Error(`缺少交接清单: ${relativeFromRoot(targetDir, handoffPath)}`);
+    if (err instanceof SyntaxError) throw new Error(`交接清单不是有效 JSON: ${relativeFromRoot(targetDir, handoffPath)}`, { cause: err });
+    throw err;
+  }
+  validateHandoff(handoff, feature);
+  if (expectedStage && handoff.stage !== expectedStage) {
+    throw new Error(`交接阶段不匹配: 期望 ${expectedStage},实际 ${handoff.stage}`);
+  }
+  if (handoff.unresolvedDecisions.length) {
+    throw new Error(`仍有 ${handoff.unresolvedDecisions.length} 个未决问题,不能进入 ${handoff.stage}`);
+  }
+
+  const routing = resolveModelRouting(await readModelRoutingConfig(targetDir));
+  if (handoff.executorTier !== routing[handoff.stage]) {
+    throw new Error(`模型路由已变化: ${handoff.stage} 当前应使用 ${routing[handoff.stage]},请重新 prepare`);
+  }
+  for (const record of handoff.inputs) {
+    const { absolute } = resolveProjectInput(targetDir, record.path);
+    await assertNoSymlinkPath(targetDir, absolute);
+    let current;
+    try {
+      current = await readFile(absolute);
+    } catch (err) {
+      if (err.code === 'ENOENT') throw new Error(`交接输入已不存在: ${record.path}`);
+      throw err;
+    }
+    const currentHash = createHash('sha256').update(current).digest('hex');
+    if (currentHash !== record.sha256) throw new Error(`交接输入已变化,请重新 prepare: ${record.path}`);
+  }
+  return handoff;
+}
+
+export async function recordStageResult({ targetDir, feature, resultPath }) {
+  const handoff = await verifyHandoff({ targetDir, feature });
+  const source = resolveProjectInput(targetDir, resultPath);
+  await assertNoSymlinkPath(targetDir, source.absolute);
+  let result;
+  try {
+    result = JSON.parse(await readFile(source.absolute, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new Error(`阶段回执不存在: ${source.relative}`);
+    if (err instanceof SyntaxError) throw new Error(`阶段回执不是有效 JSON: ${source.relative}`, { cause: err });
+    throw err;
+  }
+  validateStageResult(result, handoff);
+  const destination = path.join(targetDir, '.ai', 'runs', feature, `${handoff.stage}-result.json`);
+  await assertNoSymlinkPath(targetDir, destination);
+  await writeFile(destination, JSON.stringify(result, null, 2) + '\n');
+  return { result, path: relativeFromRoot(targetDir, destination) };
+}
+
+function validateHandoff(handoff, feature) {
+  if (!handoff || handoff.schemaVersion !== 1 || handoff.featureId !== feature) {
+    throw new Error(`交接清单格式或 featureId 无效: ${feature}`);
+  }
+  if (!STAGES.includes(handoff.stage) || !RISKS.includes(handoff.riskLevel)) {
+    throw new Error(`交接清单阶段或风险等级无效: ${feature}`);
+  }
+  if (!Array.isArray(handoff.inputs) || !handoff.inputs.length
+    || !Array.isArray(handoff.acceptanceCriteria)
+    || !Array.isArray(handoff.unresolvedDecisions)
+    || !Array.isArray(handoff.allowedChangeScope)) {
+    throw new Error(`交接清单缺少必要字段: ${feature}`);
+  }
+  if (!['inherit', 'premium', 'standard', 'economy', 'none'].includes(handoff.executorTier)
+    || handoff.inputs.some(record => !record || typeof record.path !== 'string' || !/^[a-f0-9]{64}$/.test(record.sha256))) {
+    throw new Error(`交接清单输入或执行等级无效: ${feature}`);
+  }
+}
+
+function validateStageResult(result, handoff) {
+  if (!result || typeof result !== 'object' || result.stage !== handoff.stage) {
+    throw new Error(`阶段回执 stage 必须为 ${handoff.stage}`);
+  }
+  if (!['completed', 'blocked', 'failed'].includes(result.status)) throw new Error(`阶段回执 status 无效: ${result.status}`);
+  for (const field of ['changedFiles', 'tests', 'designDeviations', 'unresolvedRisks']) {
+    if (!Array.isArray(result[field]) || result[field].some(value => typeof value !== 'string')) {
+      throw new Error(`阶段回执 ${field} 必须是字符串数组`);
+    }
+  }
+  if (!result.acceptanceCoverage || typeof result.acceptanceCoverage !== 'object' || Array.isArray(result.acceptanceCoverage)) {
+    throw new Error('阶段回执 acceptanceCoverage 必须是对象');
+  }
+  for (const [id, coverage] of Object.entries(result.acceptanceCoverage)) {
+    if (!id.trim() || !['covered', 'partial', 'not-covered', 'not-applicable'].includes(coverage)) {
+      throw new Error(`阶段回执验收覆盖无效: ${id}=${coverage}`);
+    }
+  }
+  const missing = handoff.acceptanceCriteria.filter(id => !(id in result.acceptanceCoverage));
+  if (missing.length) throw new Error(`阶段回执缺少验收覆盖: ${missing.join(', ')}`);
+}
+
+function resolveProjectInput(targetDir, input) {
+  if (typeof input !== 'string' || !input.trim() || path.isAbsolute(input)) throw new Error(`输入路径必须是项目内相对路径: ${input}`);
+  const root = path.resolve(targetDir);
+  const absolute = path.resolve(root, input);
+  const relative = path.relative(root, absolute);
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`输入路径越出项目目录: ${input}`);
+  }
+  return { absolute, relative: relative.split(path.sep).join('/') };
+}
+
+function handoffFile(targetDir, feature) {
+  return path.join(targetDir, '.ai', 'runs', feature, 'handoff.json');
+}
+
+function relativeFromRoot(targetDir, filePath) {
+  return path.relative(path.resolve(targetDir), filePath).split(path.sep).join('/');
+}
+
+function validateFeature(feature) {
+  if (typeof feature !== 'string' || !/^[\p{L}\p{N}][\p{L}\p{N}._-]*$/u.test(feature)) {
+    throw new Error(`feature 必须是单个安全目录名,收到: ${feature}`);
+  }
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.map(value => value.trim()).filter(Boolean))];
+}
+
+function requiresAcceptance(stage) {
+  return ['implementation', 'routine-tests', 'adversarial-testing', 'final-review'].includes(stage);
+}

package/templates/claude/.claude/agents/economy-test-worker.md

@@ -0,0 +1,8 @@
+---
+name: economy-test-worker
+description: 根据明确验收标准和测试矩阵补充机械性测试。仅在模型路由要求 economy 测试时使用。
+model: haiku
+tools: Read, Edit, Write, Bash, Grep, Glob
+---
+
+先验证 handoff。只修改测试范围并运行现有测试命令；不得修改生产代码、设计、接口或删除断言。发现生产缺陷、契约歧义、安全、迁移或并发问题时停止并升级。完成后记录覆盖和未覆盖项。

package/templates/claude/.claude/agents/premium-implementer.md

@@ -0,0 +1,8 @@
+---
+name: premium-implementer
+description: 执行高风险实现和复杂失败诊断。仅在模型路由要求 premium 实现或诊断时使用。
+model: opus
+tools: Read, Edit, Write, Bash, Grep, Glob
+---
+
+先验证 handoff 并读取全部正式输入。在 allowedChangeScope 内处理高风险实现或诊断，保持需求和接口契约不变。设计不足时停止并返回 premium-planner；完成后写结构化阶段回执。

package/templates/claude/.claude/agents/premium-planner.md

@@ -0,0 +1,8 @@
+---
+name: premium-planner
+description: 高风险需求定稿、功能设计和实施计划。仅在模型路由要求 premium 规划时使用。
+model: opus
+tools: Read, Grep, Glob
+---
+
+先读取并验证 `.ai/runs/<feature>/handoff.json`，再读取其中全部输入和 `.ai/skills/model-routing.md`。只输出需求、设计或计划，不修改实现。发现输入过期、需求矛盾或未决问题时停止并报告。

package/templates/claude/.claude/agents/premium-reviewer.md

@@ -0,0 +1,8 @@
+---
+name: premium-reviewer
+description: 对实现做独立对抗性测试设计和最终审查。仅在模型路由要求 premium 审查时使用。
+model: opus
+tools: Read, Bash, Grep, Glob
+---
+
+验证 handoff 后读取需求、设计、计划、Git diff、阶段回执和测试证据。保持只读，按 P0/P1/P2 输出带证据的问题或明确通过；不直接修复。修复后必须重新审查。

package/templates/claude/.claude/agents/standard-implementer.md

@@ -0,0 +1,8 @@
+---
+name: standard-implementer
+description: 按已批准设计和计划实现功能。仅在模型路由要求 standard 实现或修复时使用。
+model: sonnet
+tools: Read, Edit, Write, Bash, Grep, Glob
+---
+
+先验证 handoff 并读取全部正式输入。只在 allowedChangeScope 内按计划实现和测试；不得重新定义需求或接口。发现设计缺口时停止并升级给 premium-planner。完成后写结构化阶段回执。

package/templates/claude/.claude/agents/standard-test-worker.md

@@ -0,0 +1,8 @@
+---
+name: standard-test-worker
+description: 根据契约设计和补充较复杂测试。仅在模型路由要求 standard 测试时使用。
+model: sonnet
+tools: Read, Edit, Write, Bash, Grep, Glob
+---
+
+先验证 handoff。根据验收标准设计边界和失败测试，只修改允许的测试范围；发现生产缺陷或设计歧义时停止并交给 implementer/planner。完成后记录覆盖、命令和未覆盖风险。

package/templates/claude/.claude/skills/model-routing/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: model-routing
+description: 按项目模型策略路由规划、实现、测试和审查，并在跨模型阶段创建和校验结构化交接。用于准备阶段切换、选择执行代理或验证 handoff。
+---
+
+先读取 `.ai/skills/model-routing.md` 与 `.ai/config/model-routing.json`。风险流程决定阶段，模型路由只选择执行者。跨模型前创建并校验 handoff；失败时停止，不得用对话摘要补缺失输入。

package/templates/claude/CLAUDE.md

@@ -10,6 +10,7 @@
 - 交付前 → delivery-readiness skill,按风险验证契约、测试、迁移、回滚、性能与可观测性
 - 记忆更新 → 只在可验收工程节点、关键决策、状态变化或会话切换时写;手动 /update-memory
 - 反驳检查 → S 级精简自检;M/L 级或用户明确要求时用 /critic 独立审查
+- 模型路由 → 读取 `.ai/config/model-routing.json`;非 inherit 时按 model-routing skill 创建/验证 handoff，再调用匹配的 planner/implementer/test-worker/reviewer
 
 ## 与 superpowers 的编排(未安装则忽略本节)
 

package/templates/codex/.agents/skills/model-routing/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: model-routing
+description: 按项目模型策略路由规划、实现、测试和审查，并在跨模型阶段创建和校验结构化交接。用于准备阶段切换、选择执行代理或验证 handoff。
+---
+
+先读取 `.ai/skills/model-routing.md` 与 `.ai/config/model-routing.json`。风险流程决定阶段，模型路由只选择执行者。跨模型前创建并校验 handoff；失败时停止，不得用对话摘要补缺失输入。

package/templates/codex/.codex/agents/economy_test_worker.toml

@@ -0,0 +1,6 @@
+name = "economy_test_worker"
+description = "根据明确验收标准和测试矩阵补机械性测试；仅在模型路由要求 economy 测试时使用。"
+model_reasoning_effort = "low"
+developer_instructions = """
+先验证 handoff。只修改测试范围并运行现有测试命令；不得修改生产代码、设计、接口或删除断言。发现生产缺陷、歧义、安全、迁移或并发问题时停止并升级。
+"""

package/templates/codex/.codex/agents/premium_implementer.toml

@@ -0,0 +1,6 @@
+name = "premium_implementer"
+description = "执行高风险实现和复杂失败诊断；仅在模型路由要求 premium 实现或诊断时使用。"
+model_reasoning_effort = "high"
+developer_instructions = """
+先验证 handoff 并读取全部正式输入。在 allowedChangeScope 内处理高风险实现或诊断，保持需求和接口契约不变。设计不足时停止并返回 premium planner；完成后写结构化阶段回执。
+"""

package/templates/codex/.codex/agents/premium_planner.toml

@@ -0,0 +1,6 @@
+name = "premium_planner"
+description = "高风险需求定稿、功能设计和实施计划；仅在模型路由要求 premium 规划时使用。"
+model_reasoning_effort = "high"
+developer_instructions = """
+先验证 .ai/runs/<feature>/handoff.json，读取其中全部正式输入和 .ai/skills/model-routing.md。只输出需求、设计或计划，不修改实现。输入过期、矛盾或仍有未决问题时停止。
+"""

package/templates/codex/.codex/agents/premium_reviewer.toml

@@ -0,0 +1,6 @@
+name = "premium_reviewer"
+description = "独立对抗性测试设计和最终审查；仅在模型路由要求 premium 审查时使用。"
+model_reasoning_effort = "high"
+developer_instructions = """
+验证 handoff 后读取需求、设计、计划、Git diff、阶段回执和测试证据。保持只读，按 P0/P1/P2 输出带证据的问题或明确通过，不直接修复；修复后重新审查。
+"""

package/templates/codex/.codex/agents/standard_implementer.toml

@@ -0,0 +1,6 @@
+name = "standard_implementer"
+description = "按已批准设计和计划实现功能；仅在模型路由要求 standard 实现或修复时使用。"
+model_reasoning_effort = "medium"
+developer_instructions = """
+先验证 handoff 并读取全部正式输入。只在 allowedChangeScope 内实现和测试，不得重新定义需求或接口。发现设计缺口时停止并升级。完成后写结构化阶段回执。
+"""

package/templates/codex/.codex/agents/standard_test_worker.toml

@@ -0,0 +1,6 @@
+name = "standard_test_worker"
+description = "根据契约设计和补充较复杂测试；仅在模型路由要求 standard 测试时使用。"
+model_reasoning_effort = "medium"
+developer_instructions = """
+先验证 handoff。根据验收标准设计边界和失败测试，只修改允许的测试范围；发现生产缺陷或设计歧义时停止并升级。完成后记录覆盖、命令和未覆盖风险。
+"""

package/templates/codex/AGENTS.md

@@ -10,6 +10,7 @@
 - 交付前 → delivery-readiness skill,按风险验证契约、测试、迁移、回滚、性能与可观测性
 - 记忆更新 → 只在可验收工程节点、关键决策、状态变化或会话切换时写
 - 反驳检查 → S 级精简自检;M/L 级或用户明确要求时用 critic skill
+- 模型路由 → 读取 `.ai/config/model-routing.json`;非 inherit 时按 model-routing skill 创建/验证 handoff，再调用 `.codex/agents/` 中匹配的执行者
 
 ## 与 superpowers 的编排(未安装则忽略本节)
 

package/templates/common/.ai/README.md

@@ -8,12 +8,15 @@
 1. 读 `memory/MEMORY.md`(记忆索引)
 2. 读 `memory/session-log.md` 末尾条目(接上进度)
 3. 按任务类型按需加载 `skills/` 对应方法论
+4. 跨模型阶段先按 `skills/model-routing.md` 创建并校验 handoff，不用对话摘要替代正式输入
 
 ## 目录
 
 - `ai-memory.json` — 框架版本、Schema、启用工具、文件所有权与生成基线哈希;供安全升级预检使用
+- `config/model-routing.json` — 可选阶段模型策略;默认 `inherit` 不改变旧行为
 - `memory/` — 记忆层:MEMORY.md 索引、project-state 全景、session-log 流水、user-profile/feedback 用户级记忆、features/ 功能档案
-- `skills/` — 方法论层:project-inception、requirements-flow、feature-design、delivery-readiness、architecture、code-review、critic、memory-update
+- `runs/` — 本地交接清单和阶段回执;默认不进入 Git
+- `skills/` — 方法论层:project-inception、requirements-flow、feature-design、delivery-readiness、model-routing、architecture、code-review、critic、memory-update
 
 ## 与工具专属配置的关系
 

package/templates/common/.ai/config/model-routing.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": 1,
+  "profile": "{{modelProfile}}",
+  "overrides": {}
+}

package/templates/common/.ai/runs/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

package/templates/common/.ai/skills/critic.md

@@ -20,3 +20,4 @@
 - S 级低风险需求可在同上下文按四类清单做一次精简自检,不启动独立 agent
 - M/L 级需求、架构基线和高影响技术设计优先由独立 critic 执行,只给文档路径与本方法,不给对话历史
 - 工具不支持独立上下文时才降级为同上下文自检,并刻意抵制为自己刚写内容辩护
+- 启用模型路由时，M/L 对抗性检查和最终审查使用 premium reviewer；只传 handoff、正式文档路径、diff 和验证证据

package/templates/common/.ai/skills/delivery-readiness.md

@@ -16,6 +16,8 @@
 4. 将结果写入 `docs/design/...` 的“交付验证”章节；S 级无设计文档时记入 session-log。
 5. 输出明确结论：`ready`、`conditional` 或 `not-ready`，并列出阻塞项。
 
+启用模型路由时，机械性测试可交给 economy 执行者，但测试策略、安全/迁移/并发场景和最终审查仍由 premium 执行者负责。测试命令直接运行，不调用模型。reviewer 第一轮保持只读，修复后重新审查。
+
 ## 检查面
 
 | 检查面 | 必须回答的问题 |

package/templates/common/.ai/skills/feature-design.md

@@ -19,6 +19,8 @@
 7. M 级做一次精简自检；L 级按 critic 方法做独立或聚焦审查。
 8. 更新 `project-state.md` 为 `designed`，实现计划只引用本设计，不重新生成同义 spec。
 
+启用模型路由时，`feature-design` 与需要的 `write-plan` 分别创建 handoff；实现阶段必须重新 prepare，引用最终需求、设计和计划的当前哈希。不要把 brainstorming 对话作为实现输入。
+
 ## Superpowers 路由
 
 - S：跳过 brainstorming 和 writing-plans。

package/templates/common/.ai/skills/model-routing.md

@@ -0,0 +1,39 @@
+# 分阶段模型路由与交接
+
+模型路由只选择现有阶段的执行者，不得增加或跳过 S/M/L 风险流程。读取 `.ai/config/model-routing.json`：`inherit` 保持当前模型；`balanced` 使用高级规划、中等实现、便宜测试和高级审查；`quality` 提高实现与诊断等级。
+
+执行 CLI 时优先使用当前环境的 `ai-memory`；若命令不可用，使用 `npx --yes @betterdanlins/ai-memory@{{frameworkVersion}}`。必须固定与项目框架一致的版本，不使用未固定的 latest。
+
+## 执行协议
+
+1. 先由 requirements-flow / feature-design 判断是否需要该阶段，再解析模型等级。
+2. 跨模型执行前，用 `ai-memory workflow prepare` 从正式需求、设计和计划生成 `.ai/runs/<feature>/handoff.json`。
+3. 执行者先运行 `ai-memory workflow verify`，再读取 handoff 中的全部输入；不得用对话摘要替代正式文档。
+4. 输入缺失、哈希变化、路由变化或存在未决问题时停止，不得猜测。
+5. 实现结束后在同一 run 目录写 `<stage>-result.json`，记录变更文件、验收覆盖、测试、设计偏差和未决风险。
+6. reviewer 第一轮只读；修复交给 implementer，修复后重新审查。
+
+## 能力边界与升级
+
+- `premium`：需求定稿、重大方案、计划、对抗性测试和最终审查。
+- `standard`：按已批准计划实现、普通失败诊断。
+- `economy`：根据明确测试矩阵补机械性测试；不得修改生产代码或重新解释契约。
+- `none`：直接运行确定性命令，不调用模型。
+- economy 无法理解契约或发现生产缺陷 → standard；standard 发现设计缺口或连续两次失败 → premium。
+- 安全、权限、资金、隐私、数据迁移和并发问题直接使用 premium。
+
+模型不可用时可降级为 `inherit`，但必须报告一次；不得静默把高风险阶段降为 economy。
+
+## 交接回执最小字段
+
+```json
+{
+  "stage": "implementation",
+  "status": "completed",
+  "changedFiles": [],
+  "acceptanceCoverage": {},
+  "tests": [],
+  "designDeviations": [],
+  "unresolvedRisks": []
+}
+```

package/templates/common/.ai/skills/requirements-flow.md

@@ -23,6 +23,8 @@
 5. 按下方路由选择下一步，不在本流程中启动重复 brainstorming。
 6. 更新 `project-state.md` 为 `finalized`；在 `features/<需求名>.md` 记录外部契约与关键决策，并更新 MEMORY 索引。
 
+若 `.ai/config/model-routing.json` 的 profile 不是 `inherit`，定稿前按 `.ai/skills/model-routing.md` 为 `requirement-finalize` 准备并校验 handoff，再使用对应等级执行者。模型路由不得改变下方 S/M/L 流程深度。
+
 ## 风险路由
 
 | 等级 | 判断 | 下一步 |