@betterdanlins/ai-memory 0.1.0 → 0.3.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,120 @@
-# @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
-# 从已有项目导入用户级记忆:
+
+# 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
+```
+
+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.
+
+## 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
+├── 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
+└── skills/                   # methodology: requirements-flow, architecture,
+                              # project-inception, feature-design, 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: skills
 ```
 
-`--import` 从已有项目导入 user-profile/feedback;目标文件已存在时按冲突策略处理(--yes 下跳过,交互下询问),绝不静默覆盖。
+## CLI commands
+
+| 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 |
+
+### `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` |
+| `--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:
+
+- **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.
+
+## 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.
+- **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,120 @@
+# 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
+
+# 从已有项目导入用户级记忆(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
+```
+
+绝不静默覆盖:已存在的文件会逐个询问(交互式),或直接跳过(`--yes`)。
+`--import` 指向的项目目录不存在、不是目录或不可读时会直接报错;目录有效但某个记忆文件缺失时会回退到默认模板,并在执行摘要中明确提示。
+生成前会检查重复模板目标、路径越界和符号链接;模板读取与渲染全部通过后才开始写入。若实际磁盘写入中途失败,错误摘要会列出已经写入和尚未写入的文件。
+已初始化项目不能重新运行 `init`;新版 CLI 先通过 `update --dry-run` 识别版本和用户修改。`update --yes` 只应用新增和基线哈希匹配的安全更新,存在合并/审查项时在写入前整体拒绝。
+
+## 生成什么
+
+```
+.ai/                          # 单一源,所有 agent 共享
+├── README.md                 # 会话进场协议
+├── ai-memory.json            # 版本、Schema、工具、所有权和生成基线哈希
+├── memory/
+│   ├── MEMORY.md             # 索引 —— agent 进场先读
+│   ├── project-state.md      # 技术栈、当前版本、需求进度
+│   ├── session-log.md        # 进展与下一步的流水日志
+│   ├── user-profile.md       # 背景、偏好、沟通方式
+│   ├── feedback.md           # 从反馈提炼的行为规范
+│   └── features/             # 功能档案
+└── skills/                   # 方法论:requirements-flow、architecture、
+                              # project-inception、feature-design、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:skills
+```
+
+## CLI 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `init` | 初始化全新项目;检测到已有 ai-memory 安装时拒绝执行 |
+| `update --dry-run` | 只读分析旧项目到当前 CLI 版本的升级计划 |
+| `update --yes` | 应用无冲突安全更新;用户修改、混合文件冲突或缺失迁移路径会拒绝执行 |
+
+### `init` 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `--name <name>` | 项目名(默认取当前目录名) |
+| `--stack <desc>` | 技术栈描述 |
+| `--tools <list>` | 逗号分隔的适配层:`claude`、`codex` |
+| `--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 保守规划。
+
+## 设计原则
+
+- **单一源** —— 正文只在 `.ai/`;`.claude/`、`.agents/` 只是触发包装。
+- **工程节点记忆** —— 只在可独立验收的功能/阶段、关键决策、状态变化或工具切换时写 session-log,避免细碎步骤制造噪声。
+- **需求双目录** —— 人工粗稿(`draft/`)→ AI 定稿(`final/`),中间隔一道强制 critic 门。
+- **项目工程基线** —— 0→1 项目先建立语言无关的系统、数据、质量属性和部署基线;普通功能只记录增量,不重复设计全局架构。
+- **风险分级设计** —— S 级需求直接实现;M/L 级用 feature-design 补齐 how、技术接口和工程影响,Superpowers 只按风险选择使用。
+- **证据化交付** —— 发布前按风险检查契约、测试、迁移、回滚、性能、可观测性和运行保障,输出明确 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,16 @@
 #!/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 { ScaffoldError, scaffold } from '../src/scaffold.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')
@@ -19,6 +22,13 @@ program
   .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;
 
     // Validate CLI-supplied --tools before entering interactive prompts
@@ -51,7 +61,7 @@ program
     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 +73,97 @@ 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 };
     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}`);
+    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。');
   });
 
+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:未修改任何文件');
+}

package/package.json

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