@betterdanlins/ai-memory 0.1.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Betterdan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,170 @@
-# @betterdanlins/ai-memory
+# ai-memory
 
-AI 记忆 + 需求工作流脚手架:一条命令在项目里生成跨 Claude Code / Codex 的
-记忆层(.ai/memory)、方法论层(.ai/skills)、需求版本目录(docs/requirements)
-与两侧薄适配层。
+> Scaffold a shared AI memory layer and requirements workflow into any project — one command, portable across Claude Code, Codex, and future agents.
 
-## 用法
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+## Why
+
+AI coding agents forget everything between sessions, and every tool (Claude Code, Codex, …) wants its own config format. `ai-memory` fixes both:
+
+- **One source of truth.** All real content lives in a single agent-agnostic `.ai/` directory. Tool-specific folders (`.claude/`, `.agents/`) are thin wrappers that just point back to it — so switching or adding tools never forks your knowledge base.
+- **Memory that survives sessions.** A structured memory layer records what the last session finished, overall requirement progress, and user-level preferences, so a fresh agent can pick up exactly where the previous one left off.
+- **A requirements workflow with guardrails.** Human rough drafts and AI-finalized specs live in versioned `draft/` → `final/` directories, with a mandatory "critic" review gate before anything is finalized.
+
+## Quick start
 
 ```bash
+# Interactive
 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
+
+# Inspect an existing project's upgrade plan without writing
+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`).
+An invalid, non-directory, or unreadable `--import` project path fails explicitly. If the project directory is valid but an individual memory file is missing, the CLI falls back to its template and reports that fallback in the summary.
+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
+│   ├── session-log.md        # rolling log of progress & next steps
+│   ├── 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,
+                              # 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
+├── data-model.md             # entities, ownership, consistency, and migration
+├── quality-attributes.md     # performance, observability, scalability, reliability
+└── deployment.md             # topology, releases, rollback, and operations
+
+docs/requirements/vX.Y.Z/
+├── draft/                    # human-written rough requirements
+└── final/                    # AI-finalized specs (passes the critic gate)
+
+docs/design/vX.Y.Z/           # M/L-risk feature how, technical contracts, deltas
+
+# Thin adapters, generated only for the tools you enable:
+CLAUDE.md + .claude/          # Claude Code: commands, skills, agents, settings
+AGENTS.md + .agents/ + .codex/# Codex: skills and model-specific custom agents
+```
+
+## CLI commands
 
-`--import` 从已有项目导入 user-profile/feedback;目标文件已存在时按冲突策略处理(--yes 下跳过,交互下询问),绝不静默覆盖。
+| Command | Description |
+| --- | --- |
+| `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
+
+| Option | Description |
+| --- | --- |
+| `--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 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
+
+- **Single source** — content lives only in `.ai/`; `.claude/` and `.agents/` are trigger wrappers.
+- **Engineering-node memory** — write session-log entries for independently verifiable features/phases, durable decisions, status changes, or tool handoffs, avoiding noise from tiny implementation steps.
+- **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.
+- **Safe writes** — destinations must remain inside the target project, symbolic-link overwrites are rejected, and write failures retain a diagnostic progress summary.
+- **Explicit compatibility** — newer CLIs can recognize older schemas, user assets are never overwritten from templates, and actual updates only touch baseline-matching files after a dry run rather than re-running init.
+
+## Development
+
+```bash
+npm test        # node --test test/*.test.js
+```
 
-- 单一源:所有正文只在 `.ai/`,`.claude/`、`.agents/` 只是触发包装
-- 节点式记忆:完成任务节点立即写 session-log,跨工具切换不断档
-- 需求双目录:人工粗稿 `draft/` → AI 定稿 `final/`(强制 critic 门)
-- 幂等:已存在的文件逐个询问,绝不静默覆盖(`--yes` 一律跳过)
+## License
 
-设计文档:`docs/superpowers/specs/2026-07-05-ai-memory-framework-design.md`
+[MIT](LICENSE) © Betterdan

package/README.zh-CN.md

@@ -0,0 +1,170 @@
+# ai-memory
+
+> 一条命令,为任意项目搭建一套共享的 AI 记忆层与需求工作流 —— 跨 Claude Code、Codex 及未来的 agent 通用。
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+## 为什么
+
+AI 编码 agent 在会话之间会丢失全部上下文,而每个工具(Claude Code、Codex……)又各有各的配置格式。`ai-memory` 同时解决这两个问题:
+
+- **单一源。** 所有实际内容只存在于一份 agent 无关的 `.ai/` 目录里。工具专属目录(`.claude/`、`.agents/`)只是指回它的薄包装 —— 切换或新增工具都不会让你的知识库分叉。
+- **跨会话不断档的记忆。** 结构化的记忆层记录上个会话完成到哪、需求整体进度、以及用户级偏好,让全新的 agent 能从上一个 agent 停下的地方精确接续。
+- **带护栏的需求工作流。** 人工粗稿与 AI 定稿分别存放在带版本号的 `draft/` → `final/` 目录中,定稿前强制经过一道 “critic” 反驳评审门。
+
+## 快速开始
+
+```bash
+# 交互式
+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
+
+# 已初始化项目只读检查升级计划
+npx @betterdanlins/ai-memory update --dry-run
+
+# 只应用无冲突的安全更新;有用户修改时整体拒绝
+npx @betterdanlins/ai-memory update --yes
+
+# 已初始化项目从继承模型切换到分层路由
+npx @betterdanlins/ai-memory models configure --profile balanced
+```
+
+绝不静默覆盖:已存在的文件会逐个询问(交互式),或直接跳过(`--yes`)。
+`--import` 指向的项目目录不存在、不是目录或不可读时会直接报错;目录有效但某个记忆文件缺失时会回退到默认模板,并在执行摘要中明确提示。
+生成前会检查重复模板目标、路径越界和符号链接;模板读取与渲染全部通过后才开始写入。若实际磁盘写入中途失败,错误摘要会列出已经写入和尚未写入的文件。
+已初始化项目不能重新运行 `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      # 技术栈、当前版本、需求进度
+│   ├── session-log.md        # 进展与下一步的流水日志
+│   ├── user-profile.md       # 背景、偏好、沟通方式
+│   ├── feedback.md           # 从反馈提炼的行为规范
+│   └── features/             # 功能档案
+├── runs/                     # 本地交接与阶段回执;默认不进入 Git
+└── skills/                   # 方法论:requirements-flow、architecture、
+                              # feature-design、model-routing、delivery-readiness 等
+
+docs/architecture/            # 0→1 项目工程基线
+├── system-context.md         # 系统边界、参与者、模块和关键流程
+├── data-model.md             # 实体、关系、所有权、一致性和迁移
+├── quality-attributes.md     # 性能、可观测性、扩展性、可靠性等
+└── deployment.md             # 部署拓扑、发布、回滚和运行保障
+
+docs/requirements/vX.Y.Z/
+├── draft/                    # 人工书写的粗稿需求
+└── final/                    # AI 定稿(通过 critic 门)
+
+docs/design/vX.Y.Z/           # M/L 级功能 how、技术接口与工程增量
+
+# 薄适配层,仅为你启用的工具生成:
+CLAUDE.md + .claude/          # Claude Code:commands、skills、agents、settings
+AGENTS.md + .agents/ + .codex/# Codex:skills 与分层自定义 agents
+```
+
+## CLI 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `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` 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `--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 引用正式需求/设计/计划;输入过期、未决问题、路由变化、路径越界或符号链接都会关闭式失败。
+
+## 设计原则
+
+- **单一源** —— 正文只在 `.ai/`;`.claude/`、`.agents/` 只是触发包装。
+- **工程节点记忆** —— 只在可独立验收的功能/阶段、关键决策、状态变化或工具切换时写 session-log,避免细碎步骤制造噪声。
+- **需求双目录** —— 人工粗稿(`draft/`)→ AI 定稿(`final/`),中间隔一道强制 critic 门。
+- **项目工程基线** —— 0→1 项目先建立语言无关的系统、数据、质量属性和部署基线;普通功能只记录增量,不重复设计全局架构。
+- **风险分级设计** —— S 级需求直接实现;M/L 级用 feature-design 补齐 how、技术接口和工程影响,Superpowers 只按风险选择使用。
+- **可选成本路由** —— `inherit` 保持旧行为;显式 profile 才用高级模型规划/审查和低成本 worker 做有边界的测试工作,确定性测试执行不调用模型。
+- **工程产物交接** —— 跨模型阶段通过校验后的正式文档交接,不依赖对话摘要;阶段回执向最终 reviewer 暴露验收覆盖、设计偏差和未决风险。
+- **证据化交付** —— 发布前按风险检查契约、测试、迁移、回滚、性能、可观测性和运行保障,输出明确 ready 状态。
+- **低噪声记忆** —— 只在可验收工程节点、关键决策、状态变化和会话切换时落盘,不记录每个细碎代码步骤。
+- **幂等** —— 已存在的文件逐个询问;`--yes` 一律跳过。绝不静默覆盖。
+- **安全落盘** —— 目标必须位于项目目录内,拒绝跟随符号链接覆盖;写入失败会保留可诊断的进度摘要。
+- **显式兼容** —— 新版 CLI 可识别旧 Schema,用户资产永不由模板覆盖;升级先 dry-run,实际更新只处理基线匹配文件,不把重新 init 当作更新。
+
+## 开发
+
+```bash
+npm test        # node --test test/*.test.js
+```
+
+## 许可证
+
+[MIT](LICENSE) © Betterdan

package/bin/cli.js

@@ -1,13 +1,21 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { scaffold } from '../src/scaffold.js';
+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'));
 const program = new Command();
 
-program.name('ai-memory').description('AI memory + requirements workflow scaffolder');
+program.name('ai-memory').description('AI memory + requirements workflow scaffolder').version(PACKAGE.version);
 
 program
   .command('init')
@@ -15,11 +23,22 @@ 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) => {
     const targetDir = process.cwd();
+    const existingInstallation = await detectInstallation(targetDir);
+    if (existingInstallation.kind !== 'none') {
+      const label = existingInstallation.kind === 'legacy'
+        ? '检测到无元数据的 v0.1.0 legacy 项目'
+        : `项目已由 ai-memory ${existingInstallation.metadata.frameworkVersion} 初始化`;
+      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) {
@@ -33,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({
@@ -46,12 +65,23 @@ 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 ??= '(待补充)';
     toolsRaw ??= 'claude,codex';
 
-    const tools = toolsRaw.split(',').map(s => s.trim()).filter(Boolean);
+    const tools = [...new Set(toolsRaw.split(',').map(s => s.trim()).filter(Boolean))];
     if (tools.length === 0) {
       console.log('未启用任何工具适配,仅生成 .ai/ 通用层');
     }
@@ -63,18 +93,172 @@ program
           return (await confirm({ message: `${dest} 已存在,覆盖?`, default: false })) ? 'overwrite' : 'skip';
         };
 
-    const vars = { projectName: name, techStack: stack, date: new Date().toISOString().slice(0, 10) };
+    const date = new Date().toISOString().slice(0, 10);
+    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 {
+        await writeFrameworkMetadata({
+          targetDir, templatesRoot: TEMPLATES, frameworkVersion: PACKAGE.version,
+          tools, projectName: name, techStack: stack, date,
+        });
+        r.written.push(METADATA_DEST);
+      } catch (err) {
+        throw new ScaffoldError({
+          phase: 'write', dest: METADATA_DEST, destPath: path.join(targetDir, '.ai', 'ai-memory.json'),
+          cause: err, summary: r, notWritten: [METADATA_DEST],
+        });
+      }
+    } else {
+      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 版本所需的变更')
+  .option('--dry-run', '只输出升级计划,不修改任何文件')
+  .option('--yes', '应用无冲突的安全更新;存在合并/审查项时拒绝写入')
+  .action(async (opts) => {
+    if (opts.dryRun === opts.yes) throw new Error('update 必须且只能指定 --dry-run 或 --yes');
+    const plan = await planFrameworkUpdate({
+      targetDir: process.cwd(), templatesRoot: TEMPLATES, frameworkVersion: PACKAGE.version,
+    });
+    printUpdatePlan(plan);
+    if (opts.yes) {
+      const result = await applyFrameworkUpdate({ targetDir: process.cwd(), templatesRoot: TEMPLATES, plan });
+      console.log(`安全更新完成:写入 ${result.written.length}`);
+      for (const dest of result.written) console.log(`  ${dest}`);
+    }
+  });
+
 program.parseAsync().catch((e) => {
   if (e.name === 'ExitPromptError') {
     console.log('已取消');
   } else {
     console.error('错误: ' + e.message);
+    if (e.name === 'ScaffoldError') {
+      console.error(`已写入 ${e.summary.written.length}:`);
+      for (const d of e.summary.written) console.error(`  ${d}`);
+      console.error(`尚未写入 ${e.notWritten.length}:`);
+      for (const d of e.notWritten) console.error(`  ${d}`);
+      if (e.summary.skipped.length) {
+        console.error(`已跳过 ${e.summary.skipped.length}:`);
+        for (const d of e.summary.skipped) console.error(`  ${d}`);
+      }
+    }
   }
   process.exit(1);
 });
+
+function printUpdatePlan(plan) {
+  const current = plan.installation.kind === 'legacy'
+    ? 'v0.1.0 legacy(无元数据)'
+    : `${plan.installation.metadata.frameworkVersion} / schema ${plan.installation.metadata.schemaVersion}`;
+  console.log(`当前:${current}`);
+  console.log(`目标:${plan.frameworkVersion} / schema ${plan.schemaVersion}`);
+  console.log(`工具:${plan.tools.length ? plan.tools.join(',') : '(仅 common)'}`);
+
+  const groups = [
+    ['add', '新增'],
+    ['update', '可安全更新'],
+    ['merge', '需要合并'],
+    ['review', '需要人工审查'],
+    ['review-remove', '需要确认移除'],
+    ['preserve', '保留用户资产'],
+    ['unchanged', '无需变化'],
+  ];
+  for (const [action, label] of groups) {
+    const items = plan.actions.filter(item => item.action === action);
+    console.log(`${label} ${items.length}`);
+    if (action !== 'unchanged') for (const item of items) console.log(`  ${item.dest}`);
+  }
+  if (plan.migrations.length) {
+    console.log(`Schema 迁移 ${plan.migrations.length}(当前仅规划,不执行)`);
+    for (const migration of plan.migrations) {
+      console.log(`  ${migration.id}: ${migration.from} → ${migration.to}`);
+    }
+  }
+  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.1.0",
+  "version": "0.4.0",
   "description": "AI memory + requirements workflow scaffolder for Claude Code & Codex",
   "type": "module",
   "bin": {