@betterdanlins/ai-memory 0.3.0 → 0.5.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,62 @@ 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.5.0 — managed entry blocks
+
+- Wraps the framework-owned sections of generated `AGENTS.md` and `CLAUDE.md` in explicit `ai-memory:managed` markers. Future updates replace only that block and preserve project commands and custom rules outside it.
+- An unchanged v0.4.0 entry file can migrate to marked blocks automatically because its generated baseline hash proves it has not been edited. A modified unmarked v0.4.0 file requires one manual merge; after markers are established, later framework updates no longer conflict with user-section changes.
+- Missing, duplicated, or malformed markers fail conservatively instead of triggering a whole-file overwrite. Managed-block updates also re-check the current file hash immediately before writing.
+- `.claude/settings.json` remains a mixed JSON file and still requires review when both the framework and user changed it; Markdown markers are intentionally not applied to JSON.
+- Fixes npm's automatic `.gitignore` template renaming and safely replaces the unchanged v0.4.0 `.ai/runs/.npmignore`; a locally edited obsolete file still requires review.
+
+### 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.
+
+### Upgrade from v0.4.0 to v0.5.0
+
+```bash
+npx @betterdanlins/ai-memory@0.5.0 update --dry-run
+npx @betterdanlins/ai-memory@0.5.0 update --yes
+```
+
+If `AGENTS.md` or `CLAUDE.md` is still the unchanged v0.4.0 generated version, it migrates automatically. If either unmarked file was customized, dry-run reports `merge`; compare it with a fresh v0.5.0 reference, keep project-specific content in the user block, and retry. Once markers exist, edit only outside `<!-- ai-memory:managed:start/end -->`.
+
 ## 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 +105,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 +123,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 +133,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 +146,21 @@ 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.
+- **managed entry blocks** — Markdown entry files update only their validated framework block. Unmarked or malformed customized files remain manual merges; JSON settings keep conservative whole-file review semantics.
+- **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 +169,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,62 @@ npx @betterdanlins/ai-memory update --yes
 生成前会检查重复模板目标、路径越界和符号链接;模板读取与渲染全部通过后才开始写入。若实际磁盘写入中途失败,错误摘要会列出已经写入和尚未写入的文件。
 已初始化项目不能重新运行 `init`;新版 CLI 先通过 `update --dry-run` 识别版本和用户修改。`update --yes` 只应用新增和基线哈希匹配的安全更新,存在合并/审查项时在写入前整体拒绝。
 
+## 版本与兼容性
+
+### v0.5.0 —— 入口文件受管区块
+
+- 为生成的 `AGENTS.md` 和 `CLAUDE.md` 框架区域增加明确的 `ai-memory:managed` 标记。后续升级只替换该区块,区块外的项目命令和自定义规则保持不变。
+- 未修改的 v0.4.0 入口文件可依据生成基线哈希自动迁移为带标记结构。已经修改且没有标记的 v0.4.0 文件需要一次人工合并;标记建立后,后续框架升级不再与用户区块修改冲突。
+- 标记缺失、重复或格式损坏时保守拒绝自动合并,不会退化为整文件覆盖。写入受管区块前还会再次核对当前文件哈希。
+- `.claude/settings.json` 仍是混合 JSON 文件;框架和用户都修改时继续要求审查,不会向 JSON 强行加入 Markdown 标记。
+- 修复 npm 自动改名 `.gitignore` 模板的问题,并安全替换未修改的 v0.4.0 `.ai/runs/.npmignore`;若该废弃文件被本地修改,仍要求人工审查。
+
+### 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。
+
+### 从 v0.4.0 升级到 v0.5.0
+
+```bash
+npx @betterdanlins/ai-memory@0.5.0 update --dry-run
+npx @betterdanlins/ai-memory@0.5.0 update --yes
+```
+
+如果 `AGENTS.md` 或 `CLAUDE.md` 仍是未修改的 v0.4.0 生成版本,会自动迁移。若无标记入口已被定制,dry-run 会报告 `merge`;应对照全新 v0.5.0 参考文件,把项目内容放进 user 区块后重试。标记建立后,只在 `<!-- ai-memory:managed:start/end -->` 之外编辑。
+
 ## 生成什么
 
 ```
 .ai/                          # 单一源,所有 agent 共享
 ├── README.md                 # 会话进场协议
 ├── ai-memory.json            # 版本、Schema、工具、所有权和生成基线哈希
+├── config/
+│   └── model-routing.json    # inherit/balanced/quality 阶段路由;属于用户配置
 ├── memory/
 │   ├── MEMORY.md             # 索引 —— agent 进场先读
 │   ├── project-state.md      # 技术栈、当前版本、需求进度
@@ -49,8 +105,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 +123,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 +133,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 +146,21 @@ 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 保守规划。
+- **managed entry blocks** —— Markdown 入口只更新通过校验的框架区块;无标记或标记损坏的定制文件仍人工合并,JSON settings 继续采用保守整文件审查。
+- **model routing** —— 可选 profile 把现有阶段映射为 premium、standard、economy、inherit 或无模型执行;Claude/Codex 使用原生自定义 agent 配置,路由不会增加 S/M/L 阶段。
+- **workflow handoff** —— 本地清单只用路径和 SHA-256 引用正式需求/设计/计划;输入过期、未决问题、路由变化、路径越界或符号链接都会关闭式失败。
 
 ## 设计原则
 
@@ -103,6 +169,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 版本所需的变更')
@@ -112,8 +203,9 @@ program
     printUpdatePlan(plan);
     if (opts.yes) {
       const result = await applyFrameworkUpdate({ targetDir: process.cwd(), templatesRoot: TEMPLATES, plan });
-      console.log(`安全更新完成:写入 ${result.written.length}`);
+      console.log(`安全更新完成:写入 ${result.written.length},移除 ${result.removed.length}`);
       for (const dest of result.written) console.log(`  ${dest}`);
+      for (const dest of result.removed) console.log(`  移除 ${dest}`);
     }
   });
 
@@ -125,6 +217,10 @@ program.parseAsync().catch((e) => {
     if (e.name === 'ScaffoldError') {
       console.error(`已写入 ${e.summary.written.length}:`);
       for (const d of e.summary.written) console.error(`  ${d}`);
+      if (e.summary.removed?.length) {
+        console.error(`已移除 ${e.summary.removed.length}:`);
+        for (const d of e.summary.removed) console.error(`  ${d}`);
+      }
       console.error(`尚未写入 ${e.notWritten.length}:`);
       for (const d of e.notWritten) console.error(`  ${d}`);
       if (e.summary.skipped.length) {
@@ -147,6 +243,8 @@ function printUpdatePlan(plan) {
   const groups = [
     ['add', '新增'],
     ['update', '可安全更新'],
+    ['update-managed', '更新受管区块'],
+    ['remove', '安全移除'],
     ['merge', '需要合并'],
     ['review', '需要人工审查'],
     ['review-remove', '需要确认移除'],
@@ -167,3 +265,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.5.0",
   "description": "AI memory + requirements workflow scaffolder for Claude Code & Codex",
   "type": "module",
   "bin": {

package/src/framework.js

@@ -1,8 +1,9 @@
 import { createHash } from 'node:crypto';
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { buildManifest } from './manifest.js';
 import { matchesLegacyV01Baseline } from './legacy-v0.1.js';
+import { hasValidManagedBlock, isManagedBlockFile, replaceManagedBlock } from './managed-blocks.js';
 import { migrationsBetween } from './migrations.js';
 import { assertNoSymlinkPath, resolveSafeDestination } from './path-safety.js';
 import { render } from './render.js';
@@ -12,6 +13,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 +90,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`);
   }
@@ -109,6 +112,9 @@ export async function planFrameworkUpdate({ targetDir, templatesRoot, frameworkV
 
     const currentHash = hashContent(current);
     const desiredHash = hashContent(desired);
+    if (isManagedBlockFile(dest) && !hasValidManagedBlock(desired)) {
+      throw new Error(`受管模板缺少有效 managed 标记: ${dest}`);
+    }
     if (currentHash === desiredHash) {
       actions.push({ action: 'unchanged', dest, ownership });
     } else if (ownership === 'user') {
@@ -117,18 +123,33 @@ export async function planFrameworkUpdate({ targetDir, templatesRoot, frameworkV
       const matchesBaseline = installation.kind === 'metadata'
         ? installation.metadata.files[dest]?.sha256 === currentHash
         : matchesLegacyV01Baseline(dest, current, vars);
-      const action = matchesBaseline ? 'update' : ownership === 'mixed' ? 'merge' : 'review';
-      actions.push({ action, dest, ownership, currentHash, desiredHash });
+      if (isManagedBlockFile(dest) && hasValidManagedBlock(current)) {
+        const merged = replaceManagedBlock(current, desired);
+        actions.push({
+          action: merged === current ? 'unchanged' : 'update-managed',
+          dest, ownership, currentHash, desiredHash,
+        });
+      } else {
+        const action = matchesBaseline ? 'update' : ownership === 'mixed' ? 'merge' : 'review';
+        actions.push({ action, dest, ownership, currentHash, desiredHash });
+      }
     }
   }
 
   if (installation.kind === 'metadata') {
     for (const [dest, record] of Object.entries(installation.metadata.files)) {
-      if (desiredDests.has(dest) || !(await exists(path.join(targetDir, ...dest.split('/'))))) continue;
+      const destPath = resolveSafeDestination(targetDir, dest);
+      const current = await readOptional(destPath);
+      if (desiredDests.has(dest) || current === undefined) continue;
+      const currentHash = hashContent(current);
+      const canRemove = record.ownership === 'framework'
+        && ownershipFor(dest) === 'framework'
+        && record.sha256 === currentHash;
       actions.push({
-        action: record.ownership === 'user' ? 'preserve' : 'review-remove',
+        action: record.ownership === 'user' ? 'preserve' : canRemove ? 'remove' : 'review-remove',
         dest,
         ownership: record.ownership,
+        currentHash,
       });
     }
   }
@@ -138,6 +159,7 @@ export async function planFrameworkUpdate({ targetDir, templatesRoot, frameworkV
     frameworkVersion,
     schemaVersion: CURRENT_SCHEMA_VERSION,
     tools,
+    templateVars: vars,
     migrations,
     actions,
   };
@@ -153,33 +175,51 @@ 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 = [];
 
-  for (const action of plan.actions.filter(item => item.action === 'add' || item.action === 'update')) {
+  for (const action of plan.actions.filter(item => ['add', 'update', 'update-managed', 'remove'].includes(item.action))) {
+    if (action.action === 'remove') {
+      const destPath = resolveSafeDestination(targetDir, action.dest);
+      await assertNoSymlinkPath(targetDir, destPath);
+      const current = await readFile(destPath, 'utf8');
+      if (hashContent(current) !== action.currentHash) {
+        throw new Error(`文件在预检后发生变化,请重新 dry-run: ${action.dest}`);
+      }
+      candidates.push({ ...action, destPath });
+      continue;
+    }
     const src = sources.get(action.dest);
     if (!src) throw new Error(`升级计划缺少当前模板: ${action.dest}`);
     const destPath = resolveSafeDestination(targetDir, action.dest);
     await assertNoSymlinkPath(targetDir, destPath);
-    if (action.action === 'update') {
-      const current = await readFile(destPath, 'utf8');
+    let current;
+    if (action.action !== 'add') {
+      current = await readFile(destPath, 'utf8');
       if (action.currentHash && hashContent(current) !== action.currentHash) {
         throw new Error(`文件在预检后发生变化,请重新 dry-run: ${action.dest}`);
       }
     }
-    candidates.push({ ...action, destPath, content: render(await readFile(src, 'utf8'), vars) });
+    const desired = render(await readFile(src, 'utf8'), vars);
+    const content = action.action === 'update-managed'
+      ? replaceManagedBlock(current, desired)
+      : desired;
+    candidates.push({ ...action, destPath, content });
   }
 
-  const summary = { written: [], skipped: [], imported: [], fallback: [] };
+  const summary = { written: [], removed: [], skipped: [], imported: [], fallback: [] };
   for (const [index, item] of candidates.entries()) {
     try {
-      await mkdir(path.dirname(item.destPath), { recursive: true });
-      await writeFile(item.destPath, item.content, { flag: item.action === 'add' ? 'wx' : 'w' });
-      summary.written.push(item.dest);
+      if (item.action === 'remove') {
+        await unlink(item.destPath);
+        summary.removed.push(item.dest);
+      } else {
+        await mkdir(path.dirname(item.destPath), { recursive: true });
+        await writeFile(item.destPath, item.content, { flag: item.action === 'add' ? 'wx' : 'w' });
+        summary.written.push(item.dest);
+      }
     } catch (err) {
       throw new ScaffoldError({
         phase: 'update', dest: item.dest, destPath: item.destPath, cause: err, summary,