@betterdanlins/ai-memory 0.1.0 → 0.4.0

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/commands/delivery-readiness.md

@@ -0,0 +1,6 @@
+---
+description: 按风险等级验证功能是否具备合并、发布或部署条件
+argument-hint: <需求名或设计文档路径>
+---
+
+按 `.ai/skills/delivery-readiness.md` 检查 $ARGUMENTS。输出 ready/conditional/not-ready 和证据；不要用“代码已完成”代替交付验证。

package/templates/claude/.claude/commands/design-feature.md

@@ -0,0 +1,6 @@
+---
+description: 为 M/L 级定稿需求生成语言无关的功能技术设计
+argument-hint: <需求名> [版本]
+---
+
+按 `.ai/skills/feature-design.md` 执行。需求与版本：$ARGUMENTS。S 级需求先说明为何无需完整设计；M/L 级写入 `docs/design/vX.Y.Z/<需求名>.md`。

package/templates/claude/.claude/commands/finalize-requirement.md

@@ -4,4 +4,4 @@ argument-hint: <需求名>
 ---
 
 按 `.ai/skills/requirements-flow.md` 的「定稿」章节执行,需求名:$ARGUMENTS。
-critic 门必须由 critic subagent 独立上下文执行,逐条回应后才写 final/。
+S 级按四类清单精简自检;M/L 级由 critic subagent 独立上下文执行。逐条回应后才写 final/。

package/templates/claude/.claude/commands/project-inception.md

@@ -0,0 +1,5 @@
+---
+description: 为 0→1 项目或重大重构建立语言无关的工程基线
+---
+
+按 `.ai/skills/project-inception.md` 执行。先判断是否属于 0→1、首次补建基线或重大架构重构；不适用则停止，不为普通功能重复生成项目基线。

package/templates/claude/.claude/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '[ai-memory] 会话收尾:请确认本次进展已按节点式协议写入 .ai/memory/session-log.md'"
+            "command": "echo '[ai-memory] 会话收尾:如有可验收工程节点、关键决策或跨会话风险,请写入 .ai/memory/session-log.md'"
           }
         ]
       }

package/templates/claude/.claude/skills/critic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: critic
-description: Use when 需要对需求定稿、架构设计或实现方案做对抗性检查/反驳/挑毛病
+description: Use when an M/L-risk requirement, architecture baseline, or implementation design needs independent adversarial review, or when the user explicitly requests critique, rebuttal, or challenge
 ---
 
-派发 critic subagent(独立上下文,只给文档路径与 `.ai/skills/critic.md`,不给对话历史),随后按其纪律逐条回应质疑。
+派发 critic subagent(独立上下文,只给文档路径与 `.ai/skills/critic.md`,不给对话历史),随后按其纪律逐条回应质疑。S 级需求由 requirements-flow 直接做精简自检,不要为其触发本 skill。

package/templates/claude/.claude/skills/delivery-readiness/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: delivery-readiness
+description: Use when a feature is preparing to merge, release, deploy, or hand over and needs evidence-based verification of contracts, tests, migration, rollback, performance, observability, reliability, security, or operational readiness
+---
+
+读取并严格遵循 `.ai/skills/delivery-readiness.md`，按 S/M/L 风险检查适用项；不要重新执行需求澄清或技术设计。

package/templates/claude/.claude/skills/feature-design/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: feature-design
+description: Use when an M/L-risk finalized requirement needs implementation design, module or service boundaries, technical interface contracts, data-model changes, quality-attribute impact, migration, rollback, or an implementation-ready how document
+---
+
+读取并严格遵循 `.ai/skills/feature-design.md`，以 final 需求和项目架构基线为输入；不要重新讨论已确认的 what/why，也不要默认启动完整 Superpowers 流程。

package/templates/claude/.claude/skills/memory-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-update
-description: Use when 完成一个任务节点、做出关键决策、会话收尾,或用户要求更新记忆/总结进展
+description: Use when completing an independently verifiable feature, phase, or release; making a durable decision; changing requirement/design/delivery status; preserving a cross-session risk; switching tools; or when the user explicitly asks to update memory
 ---
 
 读取并严格遵循 `.ai/skills/memory-update.md` 的写入路由与硬性约束执行。

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/skills/project-inception/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: project-inception
+description: Use when starting a 0-to-1/greenfield project, establishing its first engineering and architecture baseline, or planning a major redesign that changes system boundaries, data ownership, deployment topology, or quality-attribute targets
+---
+
+读取并严格遵循 `.ai/skills/project-inception.md`，建立或增量更新 `docs/architecture/` 四份工程基线；普通功能迭代不要触发。

package/templates/claude/CLAUDE.md

@@ -4,14 +4,20 @@
 
 进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
 
-- 需求文档工作(新建/定稿)→ requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
-- 记忆更新 → 节点式(完成任务节点立即写),协议见 `.ai/skills/memory-update.md`;手动 /update-memory
-- 反驳检查 → /critic 或定稿流程内强制触发;必须派 critic subagent 独立上下文执行
+- 0→1 项目/首次架构基线/重大重构 → project-inception skill,产物在 `docs/architecture/`;普通功能不要重复触发
+- 需求 what/why 与外部行为定稿 → requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
+- M/L 级功能 how 与技术接口 → feature-design skill,产物在 `docs/design/vX.Y.Z/`;S 级可直接实现
+- 交付前 → 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 的编排(未安装则忽略本节)
 
-1. 需求定稿(what/why)走 requirements-flow;实现设计(how)走 brainstorming,以 `docs/requirements/*/final/*.md` 为输入
-2. code review 走 superpowers 流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+1. final 需求已经确认 what/why,不要用 brainstorming 重复澄清目标与范围
+2. S 级跳过 brainstorming/writing-plans;M 级只对未决高影响 how 选择性使用;L 级可使用完整流程
+3. 所有 Superpowers 结论必须回写 `docs/design/`,临时 spec/plan 不是唯一事实源
+4. code review 使用适合风险等级的流程,叠加 `.ai/skills/code-review.md` 的项目检查项
 
 ## 项目信息
 

package/templates/codex/.agents/skills/critic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: critic
-description: Use when 需要对需求定稿、架构设计或实现方案做对抗性检查/反驳/挑毛病
+description: Use when an M/L-risk requirement, architecture baseline, or implementation design needs adversarial review, or when the user explicitly requests critique, rebuttal, or challenge
 ---
 
-读取 `.ai/skills/critic.md`,按四类清单攻击目标文档;输出带严重度的质疑列表后,逐条回应「接受并修改」或「有理由反驳」。刻意抵制为自己刚写内容辩护的倾向。
+读取 `.ai/skills/critic.md`,按四类清单攻击目标文档;输出带严重度的质疑列表后,逐条回应「接受并修改」或「有理由反驳」。S 级只做精简自检;M/L 级在当前工具无法提供独立上下文时降级自检,刻意抵制自我辩护。

package/templates/codex/.agents/skills/delivery-readiness/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: delivery-readiness
+description: Use when a feature is preparing to merge, release, deploy, or hand over and needs evidence-based verification of contracts, tests, migration, rollback, performance, observability, reliability, security, or operational readiness
+---
+
+读取并严格遵循 `.ai/skills/delivery-readiness.md`，按 S/M/L 风险检查适用项；不要重新执行需求澄清或技术设计。

package/templates/codex/.agents/skills/feature-design/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: feature-design
+description: Use when an M/L-risk finalized requirement needs implementation design, module or service boundaries, technical interface contracts, data-model changes, quality-attribute impact, migration, rollback, or an implementation-ready how document
+---
+
+读取并严格遵循 `.ai/skills/feature-design.md`，以 final 需求和项目架构基线为输入；不要重新讨论已确认的 what/why，也不要默认启动完整 Superpowers 流程。

package/templates/codex/.agents/skills/memory-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-update
-description: Use when 完成一个任务节点、做出关键决策、会话收尾,或用户要求更新记忆/总结进展
+description: Use when completing an independently verifiable feature, phase, or release; making a durable decision; changing requirement/design/delivery status; preserving a cross-session risk; switching tools; or when the user explicitly asks to update memory
 ---
 
 读取并严格遵循 `.ai/skills/memory-update.md` 的写入路由与硬性约束执行。

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/.agents/skills/project-inception/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: project-inception
+description: Use when starting a 0-to-1/greenfield project, establishing its first engineering and architecture baseline, or planning a major redesign that changes system boundaries, data ownership, deployment topology, or quality-attribute targets
+---
+
+读取并严格遵循 `.ai/skills/project-inception.md`，建立或增量更新 `docs/architecture/` 四份工程基线；普通功能迭代不要触发。

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

@@ -4,14 +4,20 @@
 
 进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
 
-- 需求文档工作(新建/定稿)→ requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
-- 记忆更新 → 节点式(完成任务节点立即写),协议见 `.ai/skills/memory-update.md`
-- 反驳检查 → critic skill 或定稿流程内强制触发;同上下文自检,刻意抵制自我辩护(见 `.ai/skills/critic.md` 纪律)
+- 0→1 项目/首次架构基线/重大重构 → project-inception skill,产物在 `docs/architecture/`;普通功能不要重复触发
+- 需求 what/why 与外部行为定稿 → requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
+- M/L 级功能 how 与技术接口 → feature-design skill,产物在 `docs/design/vX.Y.Z/`;S 级可直接实现
+- 交付前 → delivery-readiness skill,按风险验证契约、测试、迁移、回滚、性能与可观测性
+- 记忆更新 → 只在可验收工程节点、关键决策、状态变化或会话切换时写
+- 反驳检查 → S 级精简自检;M/L 级或用户明确要求时用 critic skill
+- 模型路由 → 读取 `.ai/config/model-routing.json`;非 inherit 时按 model-routing skill 创建/验证 handoff，再调用 `.codex/agents/` 中匹配的执行者
 
 ## 与 superpowers 的编排(未安装则忽略本节)
 
-1. 需求定稿(what/why)走 requirements-flow;实现设计(how)走 brainstorming,以 `docs/requirements/*/final/*.md` 为输入
-2. code review 走 superpowers 流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+1. final 需求已经确认 what/why,不要用 brainstorming 重复澄清目标与范围
+2. S 级跳过 brainstorming/writing-plans;M 级只对未决高影响 how 选择性使用;L 级可使用完整流程
+3. 所有 Superpowers 结论必须回写 `docs/design/`,临时 spec/plan 不是唯一事实源
+4. code review 使用适合风险等级的流程,叠加 `.ai/skills/code-review.md` 的项目检查项
 
 ## 项目信息
 

package/templates/common/.ai/README.md

@@ -8,11 +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/` — 方法论层:requirements-flow、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/memory/project-state.md

@@ -11,7 +11,7 @@
 
 ## 需求进度
 
-| 版本 | 需求 | 状态(draft/finalized/in-progress/done) | 备注 |
+| 版本 | 需求 | 状态(draft/finalized/designed/in-progress/done) | 备注 |
 |---|---|---|---|
 
 ## 已知遗留问题

package/templates/common/.ai/memory/session-log.md

@@ -1,6 +1,6 @@
 # Session 日志
 
-> 高频追加文件:每完成一个任务节点/关键决策,带时间戳追加一条;只增不改。
+> 工程节点追加文件:完成可独立验收的功能/阶段、做出关键决策或会话切换时追加;细碎代码步骤合并记录,只增不改。
 > 超过约 200 行时,把旧条目压缩进 project-state.md 的「归档的 session 摘要」。
 > 跨工具(Claude Code ↔ Codex)切换前,必须确认本文件已落盘并 commit。
 

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

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

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

@@ -1,22 +1,32 @@
-# 架构方法论(语言无关)
+# 架构方法论（语言无关）
 
 ## 模块边界
 
-- 每个模块用一句话说清职责;说不清 = 边界有问题
-- 模块间只通过显式接口通信;不看内部实现也能正确使用
-- 依赖单向:上层可依赖下层,禁止反向依赖与循环依赖
+- 每个模块用一句话说明职责；无法说明通常意味着边界混乱。
+- 模块间只通过显式接口通信，依赖保持单向并避免循环。
+- 只为真实变化或隔离需求建立抽象，不为未知未来预留扩展点。
 
-## 接口契约格式(定稿时写入 final/*.md 的「接口契约」章节)
+## 两层契约
 
-每个接口写清:
+### 外部行为契约（需求阶段）
 
-- **名称与语义**:做什么,明确不做什么
-- **输入**:参数、类型、边界值约定
-- **输出**:返回结构、错误路径(每种失败如何表达给调用方)
-- **幂等/并发**:重复调用的后果,是否需要去重或加锁
-- **兼容**:后续变更如何不破坏既有调用方
+记录参与者、输入、输出、失败表达、副作用、兼容性和可观察验收结果，不固定内部实现。
 
-## 跨技术栈落地
+### 技术边界契约（how 阶段）
 
-本文件只写原则。具体项目的模块清单、依赖层级、数据规范写在
-`.ai/memory/project-state.md` 或 `features/` 对应档案里,由 agent 按本原则裁剪到当前技术栈。
+仅为跨模块、服务、进程、持久化或事件边界的接口写清：
+
+- 名称、职责与明确不负责的内容
+- 输入输出及类型/模式
+- 错误、超时、重试与降级
+- 状态变化、事务边界、一致性、幂等和并发
+- 版本、兼容和迁移策略
+- 可观测信号与契约测试
+
+私有实现细节不需要逐函数建档。
+
+## 项目基线与功能增量
+
+- `docs/architecture/` 保存系统、数据、质量属性和部署基线。
+- `docs/design/` 只记录功能相对基线的 how 与增量影响。
+- 实现完成后的稳定决策摘要进入 `.ai/memory/features/`，不要复制整份设计文档。

package/templates/common/.ai/skills/code-review.md

@@ -2,7 +2,7 @@
 
 > 不注册为 skill;供 superpowers 的 code review 流程作为附加检查项引用。
 
-- **契约一致**:实现与 `final/*.md` 的接口契约、验收标准逐条对照
+- **契约一致**:实现与 `final/*.md` 的外部行为契约、验收标准及适用的 `docs/design/` 技术接口逐条对照
 - **错误路径**:失败表达与契约声明一致,没有吞掉错误
 - **记忆同步**:功能行为变化已更新 `features/` 对应档案
 - **范围**:未引入需求「不做什么」里排除的内容

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

@@ -17,5 +17,7 @@
 
 - 主 agent 必须逐条回应「接受并修改」或「给出理由反驳」,不允许沉默跳过
 - 全部处理完毕才算通过
-- Claude Code 侧:由 critic subagent 独立上下文执行,只给文档路径,不给对话历史
-- Codex 侧:同上下文自检,刻意抵制为自己刚写内容辩护的倾向
+- S 级低风险需求可在同上下文按四类清单做一次精简自检,不启动独立 agent
+- M/L 级需求、架构基线和高影响技术设计优先由独立 critic 执行,只给文档路径与本方法,不给对话历史
+- 工具不支持独立上下文时才降级为同上下文自检,并刻意抵制为自己刚写内容辩护
+- 启用模型路由时，M/L 对抗性检查和最终审查使用 premium reviewer；只传 handoff、正式文档路径、diff 和验证证据