gsd-lite 0.1.0

package/src/tools/verify.js

@@ -0,0 +1,89 @@
+import { stat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCb);
+
+// M-2: Detection priority — first lockfile match wins (pnpm > yarn > npm > bun)
+const LOCKFILE_MAP = {
+  'pnpm-lock.yaml': 'pnpm',
+  'yarn.lock': 'yarn',
+  'package-lock.json': 'npm',
+  'bun.lockb': 'bun',
+};
+
+export async function detectPackageManager(cwd = process.cwd()) {
+  for (const [file, pm] of Object.entries(LOCKFILE_MAP)) {
+    try {
+      await stat(join(cwd, file));
+      return pm;
+    } catch {}
+  }
+  return null;
+}
+
+function summarizeOutput(output, lines) {
+  return String(output || '').trim().split('\n').slice(-lines).join('\n');
+}
+
+async function runCommand(command, args, cwd) {
+  try {
+    const { stdout } = await execFile(command, args, {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 120000,
+    });
+    return { exit_code: 0, summary: summarizeOutput(stdout, 3) };
+  } catch (err) {
+    return {
+      exit_code: typeof err.code === 'number' ? err.code : (err.status || 1),
+      summary: summarizeOutput(err.stderr || err.stdout || err.message || '', 5),
+    };
+  }
+}
+
+export async function runTests(pm, cwd, pattern) {
+  const args = ['test'];
+  if (pattern) args.push('--', pattern);
+  return runCommand(pm, args, cwd);
+}
+
+async function hasPackageScript(cwd, scriptName) {
+  try {
+    const pkg = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf-8'));
+    return typeof pkg.scripts?.[scriptName] === 'string';
+  } catch {
+    return false;
+  }
+}
+
+export async function runLint(pm, cwd) {
+  if (!await hasPackageScript(cwd, 'lint')) {
+    return { exit_code: 0, summary: 'skipped: no lint script found' };
+  }
+  return runCommand(pm, ['run', 'lint'], cwd);
+}
+
+export async function runTypeCheck(cwd) {
+  // M-8: Only run tsc if tsconfig.json exists
+  try {
+    await stat(join(cwd, 'tsconfig.json'));
+  } catch {
+    return { exit_code: 0, summary: 'skipped: no tsconfig.json found' };
+  }
+  return runCommand('npx', ['tsc', '--noEmit'], cwd);
+}
+
+export async function runAll(cwd = process.cwd()) {
+  const pm = await detectPackageManager(cwd);
+  if (!pm) {
+    const errResult = { exit_code: -1, summary: 'No package manager detected' };
+    return { lint: errResult, typecheck: errResult, test: errResult };
+  }
+  return {
+    lint: await runLint(pm, cwd),
+    typecheck: await runTypeCheck(cwd),
+    test: await runTests(pm, cwd),
+  };
+}

package/src/utils.js

@@ -0,0 +1,73 @@
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+
+export function getGsdDir(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (true) {
+    const candidate = join(dir, '.gsd');
+    try {
+      const s = statSync(candidate);
+      if (s.isDirectory()) return candidate;
+    } catch {}
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function getStatePath(startDir = process.cwd()) {
+  const gsdDir = getGsdDir(startDir);
+  if (!gsdDir) return null;
+  return join(gsdDir, 'state.json');
+}
+
+export function getGitHead(cwd = process.cwd()) {
+  try {
+    return execSync('git rev-parse --short HEAD', {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function ensureDir(dirPath) {
+  await mkdir(dirPath, { recursive: true });
+}
+
+/**
+ * Read and parse a JSON file.
+ * Returns { ok: true, data } on success, { ok: false, error } on failure.
+ */
+export async function readJson(filePath) {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    return { ok: true, data: JSON.parse(content) };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Atomically write JSON data (write to .tmp then rename).
+ */
+export async function writeJson(filePath, data) {
+  const tmpPath = filePath + '.tmp';
+  await ensureDir(dirname(filePath));
+  await writeFile(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  await rename(tmpPath, filePath);
+}
+
+/**
+ * Atomically write text content (write to .tmp then rename). [I-3]
+ */
+export async function writeAtomic(filePath, content) {
+  const tmpPath = filePath + '.tmp';
+  await ensureDir(dirname(filePath));
+  await writeFile(tmpPath, content, 'utf-8');
+  await rename(tmpPath, filePath);
+}

package/uninstall.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Plugin uninstaller for GSD-Lite
+
+import { existsSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+const CLAUDE_DIR = join(homedir(), '.claude');
+const RUNTIME_DIR = join(CLAUDE_DIR, 'gsd-lite');
+
+function log(msg) { console.log(msg); }
+
+function removeDir(path, label) {
+  if (existsSync(path)) {
+    rmSync(path, { recursive: true, force: true });
+    log(`  ✓ Removed ${label}`);
+  }
+}
+
+export function main() {
+  log('GSD-Lite Uninstaller\n');
+
+  log('Removing files...');
+
+  removeDir(join(CLAUDE_DIR, 'commands', 'gsd'), 'commands/gsd/');
+  // Agents now namespaced under gsd/ [I-5]
+  removeDir(join(CLAUDE_DIR, 'agents', 'gsd'), 'agents/gsd/');
+  removeDir(join(CLAUDE_DIR, 'workflows', 'gsd'), 'workflows/gsd/');
+  removeDir(join(CLAUDE_DIR, 'references', 'gsd'), 'references/gsd/');
+  removeDir(RUNTIME_DIR, 'gsd-lite runtime/');
+
+  // Remove hook file
+  const hookFile = join(CLAUDE_DIR, 'hooks', 'context-monitor.js');
+  if (existsSync(hookFile)) {
+    rmSync(hookFile);
+    log('  ✓ Removed hooks/context-monitor.js');
+  }
+
+  // Deregister MCP server and hooks [M-10]
+  const settingsPath = join(CLAUDE_DIR, 'settings.json');
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    let changed = false;
+    if (settings.mcpServers && settings.mcpServers['gsd-lite']) {
+      delete settings.mcpServers['gsd-lite'];
+      changed = true;
+    }
+    // Remove top-level statusLine if GSD's
+    if (settings.statusLine?.command?.includes('context-monitor.js')) {
+      delete settings.statusLine;
+      changed = true;
+    }
+    if (settings.hooks) {
+      // Remove legacy StatusLine string entry
+      if (typeof settings.hooks.StatusLine === 'string'
+          && settings.hooks.StatusLine.includes('context-monitor.js')) {
+        delete settings.hooks.StatusLine;
+        changed = true;
+      }
+      // Remove GSD PostToolUse entry from array
+      if (Array.isArray(settings.hooks.PostToolUse)) {
+        const len = settings.hooks.PostToolUse.length;
+        settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(e =>
+          !e.hooks?.some(h => h.command?.includes('context-monitor.js')));
+        if (settings.hooks.PostToolUse.length < len) changed = true;
+        if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+      } else if (typeof settings.hooks.PostToolUse === 'string'
+          && settings.hooks.PostToolUse.includes('context-monitor.js')) {
+        delete settings.hooks.PostToolUse;
+        changed = true;
+      }
+    }
+    if (changed) {
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      log('  ✓ MCP server + hooks deregistered from settings.json');
+    }
+  } catch {}
+
+  log('\n✓ GSD-Lite uninstalled.');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/workflows/debugging.md

@@ -0,0 +1,187 @@
+# 4 阶段根因分析
+
+> 本文档是 debugger 内联规则的扩展指南，按需加载。
+> 冲突时以 `gsd-debugger.md` 内联规则为准。
+
+---
+
+## 铁律 (与 debugger 一致)
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+
+如果你还没完成 Phase 1，你不能提出修复方案。
+
+---
+
+## 触发条件
+
+debugger 由编排器在以下情况派发:
+
+- executor 对同一 task 连续 3 次返回 `failed`
+- executor 返回 `[FAILED]` 且错误指纹重复
+- 编排器判断 executor 的 bug 修复尝试没有收敛
+
+编排器传入: 错误信息 + executor 的修复尝试记录 + 相关代码路径
+
+---
+
+## Phase 1: 根因调查
+
+**目标:** 理解问题，不是解决问题。
+
+### 步骤 1: 仔细阅读错误信息
+
+- 完整阅读 error message + stack trace (不要只看第一行)
+- 区分根因错误 vs 衍生错误 (通常最底部的 cause 最重要)
+- 提取关键信息: 错误类型、发生位置、输入数据
+
+### 步骤 2: 可靠复现
+
+- 用相同的输入 / 环境复现问题
+- 确保**每次都能触发**，而非偶发
+- 记录复现步骤 (作为 evidence)
+- 如果不能复现 → 检查环境差异 (版本、配置、数据状态)
+
+### 步骤 3: 检查最近变更
+
+- `git diff` — 最近修改了什么？
+- `git log --oneline -10` — 近期提交历史
+- 新依赖引入了吗？版本对吗？
+- 配置文件变更？环境变量变更？
+
+### 步骤 4: 追踪数据流
+
+- 坏数据从哪里来？逐层回溯
+- 在关键节点打日志 / 断点，观察数据变化
+- 画出数据流路径: 输入 → 处理A → 处理B → 输出
+- 找到第一个数据变"坏"的位置
+
+---
+
+## HARD-GATE: 根因调查 → 模式分析
+
+**根因调查必须完成后才能进入 Phase 2。**
+没有根因证据，不允许提出任何修复方案。
+
+完成标准:
+- [ ] 错误已可靠复现
+- [ ] 已阅读完整错误信息和 stack trace
+- [ ] 已检查最近变更
+- [ ] 已追踪数据流到出错点
+- [ ] 有初步根因方向 (即使不确定)
+
+---
+
+## Phase 2: 模式分析
+
+**目标:** 通过对比找到问题模式。
+
+### 步骤 1: 找到类似的可工作代码
+
+- 同项目中类似功能 (能正常工作的)
+- 同框架的官方示例
+- 之前的工作版本 (`git log` / `git stash list`)
+
+### 步骤 2: 系统对比
+
+- 逐行对比工作代码 vs 出错代码
+- 列出**所有**不同点，不管看起来是否相关
+- 关注: 导入路径、参数顺序、类型声明、配置项、初始化顺序
+
+### 步骤 3: 不要假设 "那个不重要"
+
+- 每一个差异都可能是根因
+- 特别是那些"看起来无关紧要"的差异 — 这往往是盲点
+- 记录每个差异及其可能的影响
+
+---
+
+## Phase 3: 假设测试
+
+**目标:** 验证你的根因假设。
+
+### 步骤 1: 明确陈述假设
+
+格式: "我认为 **X** 是根因，因为 **Y** (证据)"
+
+- 假设必须可证伪 — 如果不能被推翻，它不是好假设
+- 不要同时测试多个假设
+
+### 步骤 2: 最小变更测试
+
+- **一次只改一个变量**
+- 改变最小化 — 不要顺手重构
+- 观察结果:
+  - 问题消失 → 假设可能成立，进一步验证
+  - 问题仍在 → 假设被推翻，恢复变更，提出新假设
+
+### 步骤 3: 验证循环
+
+```
+假设 → 最小变更 → 观察
+  ├── 有效 → Phase 4 (实施修复)
+  └── 无效 → 恢复变更 → 新假设 → 重复
+```
+
+**注意:** 如果已经测试了 2+ 个假设都无效 → 质疑你的前提假设，重新审视 Phase 1 的数据。
+
+---
+
+## Phase 4: 实施修复
+
+**目标:** 修复根因 (不是症状)。
+
+### 步骤 1: 写失败测试
+
+- 写一个测试来复现这个 bug
+- 运行测试，确认它失败
+- 这个测试同时也是回归保护
+
+### 步骤 2: 修复根因
+
+- 修复你在 Phase 3 验证的根因
+- 不是绕过 / 特殊处理 / 补丁式修复
+- 问自己: "这个修复解决的是**为什么出错**，还是**出错后怎么办**？"
+
+### 步骤 3: 验证修复
+
+- 新测试通过 (bug 被修复)
+- 全部已有测试通过 (无回归)
+- 手动验证 (如适用)
+
+### 3 次修复失败规则
+
+> 3 次修复失败 → 停止。质疑架构。报告给编排器。
+
+- 同一个 bug，3 次修复尝试都失败了
+- 说明你可能在修错东西，或者问题出在更深的架构层
+- 返回 `outcome: "failed"`, `architecture_concern: true`
+
+---
+
+## 常见根因模式
+
+| 模式 | 症状 | 真实根因 |
+|------|------|----------|
+| 环境不一致 | "在我机器上能跑" | Node 版本 / 依赖版本 / 环境变量差异 |
+| 初始化顺序 | 间歇性失败 | 异步初始化未 await / 依赖注入顺序 |
+| 类型不匹配 | 静默错误 | `string` vs `number` / `null` vs `undefined` |
+| 竞态条件 | 偶发失败 | 并发访问共享状态 / 缺少锁 |
+| 缓存失效 | 旧数据 | 缓存 key 不匹配 / TTL 未设置 / 缓存层级冲突 |
+| 隐式依赖 | 移动代码后崩溃 | 全局状态 / 文件路径假设 / 环境变量 |
+| 边界溢出 | 极端输入崩溃 | 未校验输入范围 / 整数溢出 |
+
+---
+
+## 红旗 / 停止信号
+
+遇到以下情况时**立即停止当前动作**:
+
+| 红旗 | 为什么危险 | 正确做法 |
+|------|------------|----------|
+| "快速修一下先" | 你在跳过根因调查 | 回到 Phase 1 |
+| "应该是 X 的问题" | 没有证据的假设 | 先调查，再假设 |
+| "再试一个修复" (已 2+) | 你在盲目尝试 | 停止，质疑架构 |
+| "这个问题太复杂了" | 可能需要拆分 | 报告给编排器 |
+| 修复 A 引出 bug B | 症状修复，根因未解 | 回到 Phase 1 重新调查 |
+| 修复越来越大 | 你在补丁叠补丁 | 停止，质疑设计 |

package/workflows/deviation-rules.md

@@ -0,0 +1,128 @@
+# 偏差处理规则
+
+> 本文档是 executor 内联 `<deviation_rules>` 的扩展指南，按需加载。
+> 冲突时以 `gsd-executor.md` 内联规则为准。
+
+---
+
+## 决策树: 执行中遇到偏差时
+
+```
+执行 task 时发现偏差
+  │
+  ├── Bug (不影响架构)?
+  │     └── AUTO-FIX: 直接修复，不中断
+  │
+  ├── 缺少导入/类型声明?
+  │     └── AUTO-ADD: 直接补充，不中断
+  │
+  ├── 需要架构变更?
+  │     └── ANNOTATE: 标注到 summary + decisions
+  │         → 返回 orchestrator 决策
+  │         → 不自行实施架构变更
+  │
+  └── 同一 task 3 次修复失败?
+        └── STOP: 返回 outcome="failed"
+            → 由编排器决定:
+              ├── 派发 debugger 分析根因
+              ├── 标记 task failed
+              └── 标记 phase failed
+```
+
+---
+
+## 四种偏差类型详解
+
+### AUTO-FIX: 自动修复 Bug
+
+**条件:** bug 不影响架构设计，是实现层的错误。
+
+示例:
+- off-by-one 错误
+- 拼写错误导致的引用失败
+- 逻辑条件反转 (`>` 写成 `<`)
+- 异步函数忘记 `await`
+- null/undefined 未检查
+
+处理: 修复 → 运行测试 → checkpoint commit → 在 summary 中简要提及
+
+### AUTO-ADD: 自动补充遗漏
+
+**条件:** 缺少的是声明性内容，不涉及行为设计决策。
+
+示例:
+- 缺少 `import` 语句
+- 缺少 TypeScript 类型声明
+- 缺少 `export`
+- 缺少必要的依赖声明 (`package.json`)
+
+处理: 补充 → 验证编译/类型检查通过 → 不需要单独 checkpoint
+
+### ANNOTATE: 架构变更标注
+
+**条件:** 修改会影响系统架构、模块边界或共享契约。
+
+示例:
+- 需要新增数据库表/字段
+- 需要修改 API 端点的 request/response 结构
+- 需要引入新的依赖模块
+- 需要改变模块间的调用关系
+- 需要修改共享类型定义
+
+处理:
+1. **不自行实施** — 只标注，不改
+2. 在 `decisions` 中添加: `[DECISION] 发现需要架构变更: ...`
+3. 在 `summary` 中描述变更需求和理由
+4. 返回给 orchestrator，由其决定是否批准并调整计划
+
+### STOP: 3 次失败停止
+
+**条件:** 同一错误指纹 (file+line 或 msg[:50]) 出现 3 次。
+
+处理:
+1. 返回 `outcome: "failed"`
+2. 附上 3 次尝试的记录 (每次: 假设 + 修改 + 结果)
+3. 编排器决定下一步:
+   - 派发 debugger → 系统性根因分析
+   - 标记 task failed → 跳过 (如非关键)
+   - 标记 phase failed → 停止执行 (如关键路径)
+
+---
+
+## `contract_changed` 判定指南
+
+executor 完成 task 后必须在 result 中报告 `contract_changed` 字段。
+
+| 场景 | `contract_changed` | 理由 |
+|------|---------------------|------|
+| 改了函数/方法签名 (参数、返回类型) | `true` | 调用方需要适配 |
+| 改了 API endpoint 的 request/response schema | `true` | 前端/客户端需要适配 |
+| 改了数据库 schema (表结构、字段) | `true` | migration + 依赖代码需要适配 |
+| 改了共享类型定义 / 接口 | `true` | 所有使用方需要适配 |
+| 只改了内部实现逻辑，不影响外部调用方 | `false` | 封装边界内，无外部影响 |
+| 拿不准时 | `true` | **安全优先** |
+
+`contract_changed: true` 的后果:
+- 编排器触发下游失效传播 (`needs_revalidation`)
+- 如果涉及 auth/payment/public API → 审查级别自动升级为 L2
+
+---
+
+## 审查级别重分类规则
+
+executor 执行时可能发现实际影响面与 planner 预判不同，可以建议重分类:
+
+### 升级 (executor 可建议)
+
+- 在 `decisions` 中标注: `[LEVEL-UP] 建议升级为 L2 因为 ...`
+- 编排器采纳建议
+
+### 自动升级 (编排器自动)
+
+- `contract_changed: true` + 涉及 auth/payment/public API → 自动升级为 L2
+
+### 降级 (不允许)
+
+- 编排器不主动降级
+- planner 标了 L2 但实际很简单 → 仍按 L2 审查
+- 原则: **安全优先**

package/workflows/research.md

@@ -0,0 +1,139 @@
+# 研究工作流
+
+> 本文档是 researcher 内联规则的扩展指南，按需加载。
+> 冲突时以 `gsd-researcher.md` 内联规则为准。
+
+---
+
+## 源优先级 (与 researcher 一致)
+
+```
+1. Context7 MCP   — 最新文档，无幻觉 (最优先)
+2. 官方文档       — Context7 覆盖不足时
+3. WebSearch      — 对比和趋势 (补充)
+```
+
+选择原则:
+- Context7 能回答 → 不查 WebSearch
+- 官方文档有明确说明 → 不依赖社区经验
+- 多个源矛盾 → 以版本最新、权威性最高的为准
+
+---
+
+## 研究触发规则 (智能判断)
+
+| 场景 | 决策 | 理由 |
+|------|------|------|
+| 新项目 | **必须研究** | 技术栈选型需要依据 |
+| 涉及新技术栈 | **必须研究** | 不熟悉的领域需要 pitfall 分析 |
+| 简单 bug 修复 | **跳过研究** | 已有代码即上下文 |
+| 已有研究且未过期 | **跳过研究** | 复用缓存 |
+| 用户明确要求 | **研究** | 用户意图优先 |
+| 已有研究但需求方向变了 | **增量研究** | 只研究新方向，不重做已有部分 |
+
+编排器在 `/gsd:start` 或 `/gsd:prd` 流程中根据上述规则判断是否派发 researcher。
+
+---
+
+## 研究过期规则 (TTL)
+
+**默认启发式，不是固定定律。**
+
+| 领域 | 默认 TTL | 理由 |
+|------|----------|------|
+| 前端框架 / 云服务 / 安全 | 3 天 | 高波动，API 变化频繁 |
+| 中等波动领域 (通用 Web 开发) | 7 天 | 默认值 |
+| 稳定后端 / 企业内部 / 基础设施 | 14-30 天 | 低波动，变化缓慢 |
+
+**立即过期触发:**
+- `package.json` 主依赖大版本有变更 → 立即过期
+- 用户说"重新研究" → 强制过期
+
+**TTL 存储在** `state.json` 的 `research.expires_at` 字段。
+
+---
+
+## 缓存策略与 Decision ID
+
+### Decision ID 生成
+
+每个关键推荐生成一个 decision id，格式: `decision:<topic>`
+
+示例:
+- `decision:jwt-rotation` — JWT 刷新策略选型
+- `decision:orm-choice` — ORM 工具选型
+- `decision:deploy-platform` — 部署平台选型
+
+Decision ID 供 plan/task 的 `research_basis` 字段引用，建立研究→计划的追溯链。
+
+### 研究刷新后的 Decision ID 处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| 新研究 decision 与旧 ID 相同且结论一致 | 保留引用，更新 `expires_at` |
+| 新研究 decision 与旧 ID 相同但结论变了 | 标记所有引用该 decision 的 task 为 `needs_revalidation` |
+| 旧 decision ID 在新研究中不再存在 | 标记引用 task 为 `needs_revalidation` + 警告编排器 |
+| 新研究产生了全新 decision ID | 不影响已有 task，供后续 planning 使用 |
+
+---
+
+## 输出结构
+
+研究结果写入 `.gsd/research/` 目录:
+
+### STACK.md — 技术栈推荐
+
+- 推荐的技术栈组合 + 理由
+- 版本建议 (具体版本号)
+- 替代方案对比
+- 每项标注置信度 + 来源
+
+### ARCHITECTURE.md — 架构模式
+
+- 推荐的架构模式 (标识 ⭐)
+- 备选方案 + 优劣对比
+- 与当前项目的适配分析
+
+### PITFALLS.md — 领域陷阱
+
+- 来自真实项目经验的陷阱
+- 每个陷阱: 描述 + 规避方案 + 置信度
+- 按严重程度排序
+
+### SUMMARY.md — 研究摘要
+
+- 关键发现摘要
+- 路线图建议
+- volatility 评估
+- `expires_at` 过期时间
+- key decision ids 索引
+
+---
+
+## 置信度标注
+
+每个发现/推荐必须标注:
+
+| 置信度 | 含义 | 来源要求 |
+|--------|------|----------|
+| **HIGH** | 可直接采用 | 官方文档 / Context7 明确说明 |
+| **MEDIUM** | 建议采用，但需验证 | 社区广泛使用 / 多源一致 |
+| **LOW** | 参考用，需要进一步调查 | 单一来源 / 经验推测 |
+
+来源标注格式: `[Context7]` / `[官方文档]` / `[社区经验]`
+
+---
+
+## 结果契约 (与 researcher 一致)
+
+```json
+{
+  "decision_ids": ["decision:jwt-rotation", "decision:orm-choice"],
+  "volatility": "medium",
+  "expires_at": "2026-03-17T10:30:00Z",
+  "sources": [
+    { "id": "src1", "type": "Context7", "ref": "Next.js auth docs" },
+    { "id": "src2", "type": "官方文档", "ref": "Prisma migration guide" }
+  ]
+}
+```