@betterdanlins/ai-memory 0.3.0 → 0.5.0

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/src/model-routing.js

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

package/src/workflow.js

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/templates/claude/CLAUDE.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/templates/codex/AGENTS.md

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

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

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

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

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

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

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

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

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

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

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

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