@betterdanlins/ai-memory 0.4.0 → 0.5.0

package/README.md

@@ -44,6 +44,14 @@ An initialized project cannot be initialized again. A newer CLI first uses `upda
 
 ## 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.
@@ -73,6 +81,15 @@ 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
 
 ```
@@ -141,6 +158,7 @@ The generator is a small set of focused modules:
 - **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.
 

package/README.zh-CN.md

@@ -44,6 +44,14 @@ npx @betterdanlins/ai-memory models configure --profile balanced
 
 ## 版本与兼容性
 
+### 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 的工作流深度。
@@ -73,6 +81,15 @@ 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 -->` 之外编辑。
+
 ## 生成什么
 
 ```
@@ -141,6 +158,7 @@ AGENTS.md + .agents/ + .codex/# Codex:skills 与分层自定义 agents
 - **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 引用正式需求/设计/计划;输入过期、未决问题、路由变化、路径越界或符号链接都会关闭式失败。
 

package/bin/cli.js

@@ -203,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}`);
     }
   });
 
@@ -216,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) {
@@ -238,6 +243,8 @@ function printUpdatePlan(plan) {
   const groups = [
     ['add', '新增'],
     ['update', '可安全更新'],
+    ['update-managed', '更新受管区块'],
+    ['remove', '安全移除'],
     ['merge', '需要合并'],
     ['review', '需要人工审查'],
     ['review-remove', '需要确认移除'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterdanlins/ai-memory",
-  "version": "0.4.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';
@@ -111,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') {
@@ -119,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,
       });
     }
   }
@@ -161,26 +180,46 @@ export async function applyFrameworkUpdate({ targetDir, templatesRoot, plan }) {
   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,

package/src/managed-blocks.js

@@ -0,0 +1,62 @@
+export const MANAGED_BLOCK_START = '<!-- ai-memory:managed:start -->';
+export const MANAGED_BLOCK_END = '<!-- ai-memory:managed:end -->';
+
+const MANAGED_BLOCK_FILES = new Set(['AGENTS.md', 'CLAUDE.md']);
+
+export class ManagedBlockError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ManagedBlockError';
+  }
+}
+
+export function isManagedBlockFile(dest) {
+  return MANAGED_BLOCK_FILES.has(dest);
+}
+
+export function replaceManagedBlock(current, desired) {
+  const currentBlock = locateManagedBlock(current, '当前文件');
+  const desiredBlock = locateManagedBlock(desired, '新版模板');
+  const eol = current.includes('\r\n') ? '\r\n' : '\n';
+  const replacement = normalizeEol(desired.slice(desiredBlock.start, desiredBlock.end), eol);
+  return current.slice(0, currentBlock.start) + replacement + current.slice(currentBlock.end);
+}
+
+export function hasValidManagedBlock(content) {
+  try {
+    locateManagedBlock(content, '文件');
+    return true;
+  } catch (err) {
+    if (err instanceof ManagedBlockError) return false;
+    throw err;
+  }
+}
+
+function locateManagedBlock(content, label) {
+  if (typeof content !== 'string') throw new ManagedBlockError(`${label}内容必须是字符串`);
+  const starts = occurrences(content, MANAGED_BLOCK_START);
+  const ends = occurrences(content, MANAGED_BLOCK_END);
+  if (starts.length !== 1 || ends.length !== 1) {
+    throw new ManagedBlockError(`${label}必须且只能包含一组 ai-memory managed 标记`);
+  }
+  const start = starts[0];
+  const end = ends[0] + MANAGED_BLOCK_END.length;
+  if (end <= start) throw new ManagedBlockError(`${label}的 ai-memory managed 标记顺序无效`);
+  return { start, end };
+}
+
+function occurrences(content, token) {
+  const positions = [];
+  let offset = 0;
+  while (offset < content.length) {
+    const index = content.indexOf(token, offset);
+    if (index === -1) break;
+    positions.push(index);
+    offset = index + token.length;
+  }
+  return positions;
+}
+
+function normalizeEol(content, eol) {
+  return content.replace(/\r?\n/g, eol);
+}

package/src/manifest.js

@@ -13,7 +13,7 @@ export async function buildManifest(templatesRoot, tools) {
     if (!enabled(tools)) continue;
     const groupDir = path.join(templatesRoot, group);
     for (const rel of await walk(groupDir, '')) {
-      entries.push({ src: path.join(groupDir, ...rel.split('/')), dest: rel });
+      entries.push({ src: path.join(groupDir, ...rel.split('/')), dest: templateDestination(rel) });
     }
   }
   const sorted = entries.sort((a, b) => a.dest < b.dest ? -1 : a.dest > b.dest ? 1 : 0);
@@ -21,6 +21,12 @@ export async function buildManifest(templatesRoot, tools) {
   return sorted;
 }
 
+function templateDestination(rel) {
+  return rel.endsWith('/.gitignore.template') || rel === '.gitignore.template'
+    ? rel.slice(0, -'.template'.length)
+    : rel;
+}
+
 function assertUniqueDestinations(entries) {
   const sourcesByDest = new Map();
   for (const { src, dest } of entries) {

package/templates/claude/CLAUDE.md

@@ -1,8 +1,10 @@
 # {{projectName}}
 
+<!-- ai-memory:managed:start -->
 ## AI 协作框架(ai-memory)
 
 进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
+本 managed 区块由 ai-memory 更新;项目命令和自定义规则只写到下方 user 区块。
 
 - 0→1 项目/首次架构基线/重大重构 → project-inception skill,产物在 `docs/architecture/`;普通功能不要重复触发
 - 需求 what/why 与外部行为定稿 → requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
@@ -18,8 +20,11 @@
 2. S 级跳过 brainstorming/writing-plans;M 级只对未决高影响 how 选择性使用;L 级可使用完整流程
 3. 所有 Superpowers 结论必须回写 `docs/design/`,临时 spec/plan 不是唯一事实源
 4. code review 使用适合风险等级的流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+<!-- ai-memory:managed:end -->
 
+<!-- ai-memory:user:start -->
 ## 项目信息
 
 - 技术栈:{{techStack}}
 <!-- 在此补充启动/测试/构建命令 -->
+<!-- ai-memory:user:end -->

package/templates/codex/AGENTS.md

@@ -1,8 +1,10 @@
 # {{projectName}}
 
+<!-- ai-memory:managed:start -->
 ## AI 协作框架(ai-memory)
 
 进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
+本 managed 区块由 ai-memory 更新;项目命令和自定义规则只写到下方 user 区块。
 
 - 0→1 项目/首次架构基线/重大重构 → project-inception skill,产物在 `docs/architecture/`;普通功能不要重复触发
 - 需求 what/why 与外部行为定稿 → requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
@@ -18,8 +20,11 @@
 2. S 级跳过 brainstorming/writing-plans;M 级只对未决高影响 how 选择性使用;L 级可使用完整流程
 3. 所有 Superpowers 结论必须回写 `docs/design/`,临时 spec/plan 不是唯一事实源
 4. code review 使用适合风险等级的流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+<!-- ai-memory:managed:end -->
 
+<!-- ai-memory:user:start -->
 ## 项目信息
 
 - 技术栈:{{techStack}}
 <!-- 在此补充启动/测试/构建命令 -->
+<!-- ai-memory:user:end -->