gsd-lite 0.3.1 → 0.3.5

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "gsd",
       "source": "./",
       "description": "AI orchestration tool — GSD management shell + Superpowers quality core. 5 commands, 4 agents, 5 workflows, MCP server, context monitoring.",
-      "version": "0.3.1",
+      "version": "0.3.4",
       "keywords": ["orchestration", "mcp", "tdd", "task-management"],
       "category": "Development workflows"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd",
-  "version": "0.3.1",
+  "version": "0.3.5",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "author": {
     "name": "sdsrss",

package/commands/prd.md

@@ -126,149 +126,10 @@ argument-hint: File path to requirements doc, or inline description text
 进入执行主循环。phase = 管理边界，task = 执行边界。
 
 <execution_loop>
+参考 `references/execution-loop.md` 获取完整 9 步执行循环规范 (11.1-11.9) 及依赖门槛语义。
 
-### 11.1 — 加载 phase 计划
-
-```
-for each pending phase:
-  加载 phase 计划 + todo DAG
-```
-
-### 11.2 — 选择 runnable task
-
-选择条件:
-- `lifecycle` 属于 `{pending, needs_revalidation}`
-- `requires` 中每个依赖都满足对应 gate
-- 不被 unresolved blocker 阻塞
-- 未超过 retry 上限
-
-如果 0 个 runnable task 且 phase 未完成:
-```
-├── 全部 blocked → workflow_mode = awaiting_user，展示所有 blocker
-└── 全部等待 review → 触发 batch review (L1) 或等待 L2 review 完成
-```
-
-### 11.3 — 构建 executor 上下文 + 串行派发
-
-executor 上下文传递协议 (orchestrator → executor):
-```
-├── task_spec:           从 phases/*.md 提取当前 task 的规格段落
-├── research_decisions:  从 research_basis 引用的 decision 摘要
-├── predecessor_outputs: 前置依赖 task 的 files_changed + checkpoint_commit
-├── project_conventions: CLAUDE.md 路径 (executor 自行读取)
-├── workflows:           需加载的工作流文件路径 (如 tdd-cycle.md)
-└── constraints:         retry_count / level / review_required
-```
-
-派发 `executor` 子代理执行单个 task。
-
-### 11.4 — 处理 executor 结果
-
-严格按 agent result contract 处理:
-```
-├── checkpointed → 写入 checkpoint commit + evidence refs → 进入审查 (11.5)
-├── blocked      → 写入 blocked_reason / unblock_condition
-│                  → 编排器检查 decisions 数组，能自动回答则重新派发
-│                  → 不能回答 → workflow_mode = awaiting_user，向用户转达
-├── failed       → retry_count + 1
-│                  → 未超限 → 重新派发 executor
-│                  → 超限 (3次) 或返回 [FAILED] 且错误指纹重复
-│                    或修复尝试未收敛 → 触发 debugger (见下方)
-```
-
-**Debugger 触发流程:**
-1. 编排器派发 `debugger` 子代理，传入: 错误信息 + executor 修复尝试记录 + 相关代码路径
-2. debugger 返回: 根因分析 + 修复方向建议
-3. 编排器决定:
-   - 带修复方向重新派发 executor
-   - 标记 task failed
-   - 标记 phase failed
-
-**Decisions 累积:**
-- executor 返回 `[DECISION]` → 编排器追加到 `state.json` 的 `decisions` 数组
-- 每条 decision 记录: `id` / `task` / `summary` / `phase`
-- decisions 跨 task、跨 phase、跨 `/clear` + `/gsd:resume` 持久保留
-- 编排器收到 `[BLOCKED]` 时，先查 `decisions` 数组尝试自动回答
-
-### 11.5 — 分层审查
-
-```
-├── L0: checkpoint commit 后可直接 accepted (无需 reviewer)
-├── L1: phase 结束后批量 reviewer 审查
-│       → 派发 reviewer 子代理，scope = phase
-└── L2: checkpoint commit 后立即独立审查
-        → 派发 reviewer 子代理，scope = task
-        → 未 accepted 前不释放其下游依赖
-```
-
-**审查级别运行时重分类:**
-- executor 报告 `contract_changed: true` + 涉及 auth/payment/public API → 自动升级为 L2
-- executor 标注 `[LEVEL-UP]` → 编排器采纳
-- 不主动降级 (安全优先)
-
-### 11.6 — 处理 reviewer 结果
-
-```
-├── 无 Critical → 更新 accepted 状态 + evidence refs
-└── 有 Critical → 标记返工 task + 失效传播 → 重新审查 (最多 3 轮)
-```
-
-**返工失效传播规则:**
-- 返工修改了 contract / schema / shared behavior:
-  → 所有直接和间接依赖 task → `needs_revalidation`
-  → 清空其旧 `evidence_refs`
-  → 已 accepted 则退回到 `checkpointed` 或 `pending_review`
-- 返工只影响局部实现、外部契约未变:
-  → 下游 task 保持现状
-  → 但受影响验证范围必须重跑并刷新 evidence
-- 触发判定: `contract_changed` (executor 运行时报告) 是主触发源
-  `invalidate_downstream_on_change` (planner 静态标记) 是预判辅助
-  → executor 报告 `contract_changed: true` → 一定传播
-  → planner 标记但 executor 报告 false → 不传播 (以运行时实际为准)
-
-### 11.7 — Phase handoff gate
-
-<HARD-GATE id="phase-handoff">
-所有条件必须满足才能进入下一 phase:
-- [ ] 所有 required task = `accepted`
-- [ ] required review = `passed`
-- [ ] critical issues = 0
-- [ ] tests/lint/typecheck 满足计划验证条件
-- [ ] 方向校验: 当前阶段产出是否仍与 plan.md 中的项目目标一致？
-
-→ 全部满足 → 自动进入下一阶段
-→ 任一不满足 → 标注问题，尝试修复，3 次失败停止
-→ 方向漂移 → workflow_mode = awaiting_user，展示偏差让用户决定
-</HARD-GATE>
-
-### 11.8 — 批量更新 state.json
-
-阶段完成后，编排器批量更新 state.json:
-- 更新 phase lifecycle → `accepted`
-- 更新 phase_handoff 信息
-- 归档旧 phase 的 evidence (只保留当前 phase 和上一 phase)
-- 推进 `current_phase` 到下一个 pending phase
-
-**规则:** 只有编排器写 state.json，避免并发竞态。
-
-### 11.9 — 上下文检查
-
-每次派发子代理前和阶段切换时检查上下文健康度:
-
-```
-remaining < 35%:
-  1. 保存完整状态到 state.json
-  2. workflow_mode = awaiting_clear
-  3. 输出: "上下文剩余 <35%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
-  4. 停止执行
-
-remaining < 25%:
-  1. 紧急保存状态到 state.json
-  2. workflow_mode = awaiting_clear
-  3. 输出: "上下文即将耗尽，已保存进度。请立即执行 /clear 然后 /gsd:resume"
-  4. 立即停止
-```
-
+编排器必须严格按照该参考文档中的步骤顺序执行:
+加载 phase → 选择 task → 构建上下文 → 派发 executor → 处理结果 → 审查 → phase handoff → 批量更新 → 上下文检查
 </execution_loop>
 
 ## STEP 12 — 全部完成

package/commands/resume.md

@@ -68,7 +68,7 @@ description: Resume project execution from saved state with workspace validation
   - requires 中每个依赖都满足对应 gate
   - 未超过 retry 上限
 - 构建 executor 上下文 → 派发 executor 子代理
-- 继续自动执行主路径 (按 start.md STEP 11 执行循环)
+- 继续自动执行主路径 (按 references/execution-loop.md 执行循环)
 
 ---
 

package/commands/start.md

@@ -146,164 +146,12 @@ argument-hint: Optional feature or project description
 进入执行主循环。phase = 管理边界，task = 执行边界。
 
 <execution_loop>
+参考 `references/execution-loop.md` 获取完整 9 步执行循环规范 (11.1-11.9) 及依赖门槛语义。
 
-### 11.1 — 加载 phase 计划
-
-```
-for each pending phase:
-  加载 phase 计划 + todo DAG
-```
-
-### 11.2 — 选择 runnable task
-
-选择条件:
-- `lifecycle` 属于 `{pending, needs_revalidation}`
-- `requires` 中每个依赖都满足对应 gate
-- 不被 unresolved blocker 阻塞
-- 未超过 retry 上限
-
-如果 0 个 runnable task 且 phase 未完成:
-```
-├── 全部 blocked → workflow_mode = awaiting_user，展示所有 blocker
-└── 全部等待 review → 触发 batch review (L1) 或等待 L2 review 完成
-```
-
-### 11.3 — 构建 executor 上下文 + 串行派发
-
-executor 上下文传递协议 (orchestrator → executor):
-```
-├── task_spec:           从 phases/*.md 提取当前 task 的规格段落
-├── research_decisions:  从 research_basis 引用的 decision 摘要
-├── predecessor_outputs: 前置依赖 task 的 files_changed + checkpoint_commit
-├── project_conventions: CLAUDE.md 路径 (executor 自行读取)
-├── workflows:           需加载的工作流文件路径 (如 tdd-cycle.md)
-└── constraints:         retry_count / level / review_required
-```
-
-派发 `executor` 子代理执行单个 task。
-
-### 11.4 — 处理 executor 结果
-
-严格按 agent result contract 处理:
-```
-├── checkpointed → 写入 checkpoint commit + evidence refs → 进入审查 (11.5)
-├── blocked      → 写入 blocked_reason / unblock_condition
-│                  → 编排器检查 decisions 数组，能自动回答则重新派发
-│                  → 不能回答 → workflow_mode = awaiting_user，向用户转达
-├── failed       → retry_count + 1
-│                  → 未超限 → 重新派发 executor
-│                  → 超限 (3次) 或返回 [FAILED] 且错误指纹重复
-│                    或修复尝试未收敛 → 触发 debugger (见下方)
-```
-
-**Debugger 触发流程:**
-1. 编排器派发 `debugger` 子代理，传入: 错误信息 + executor 修复尝试记录 + 相关代码路径
-2. debugger 返回: 根因分析 + 修复方向建议
-3. 编排器决定:
-   - 带修复方向重新派发 executor
-   - 标记 task failed
-   - 标记 phase failed
-
-**Decisions 累积:**
-- executor 返回 `[DECISION]` → 编排器追加到 `state.json` 的 `decisions` 数组
-- 每条 decision 记录: `id` / `task` / `summary` / `phase`
-- decisions 跨 task、跨 phase、跨 `/clear` + `/gsd:resume` 持久保留
-- 编排器收到 `[BLOCKED]` 时，先查 `decisions` 数组尝试自动回答
-
-### 11.5 — 分层审查
-
-```
-├── L0: checkpoint commit 后可直接 accepted (无需 reviewer)
-├── L1: phase 结束后批量 reviewer 审查
-│       → 派发 reviewer 子代理，scope = phase
-└── L2: checkpoint commit 后立即独立审查
-        → 派发 reviewer 子代理，scope = task
-        → 未 accepted 前不释放其下游依赖
-```
-
-**审查级别运行时重分类:**
-- executor 报告 `contract_changed: true` + 涉及 auth/payment/public API → 自动升级为 L2
-- executor 标注 `[LEVEL-UP]` → 编排器采纳
-- 不主动降级 (安全优先)
-
-### 11.6 — 处理 reviewer 结果
-
-```
-├── 无 Critical → 更新 accepted 状态 + evidence refs
-└── 有 Critical → 标记返工 task + 失效传播 → 重新审查 (最多 3 轮)
-```
-
-**返工失效传播规则:**
-- 返工修改了 contract / schema / shared behavior:
-  → 所有直接和间接依赖 task → `needs_revalidation`
-  → 清空其旧 `evidence_refs`
-  → 已 accepted 则退回到 `checkpointed` 或 `pending_review`
-- 返工只影响局部实现、外部契约未变:
-  → 下游 task 保持现状
-  → 但受影响验证范围必须重跑并刷新 evidence
-- 触发判定: `contract_changed` (executor 运行时报告) 是主触发源
-  `invalidate_downstream_on_change` (planner 静态标记) 是预判辅助
-  → executor 报告 `contract_changed: true` → 一定传播
-  → planner 标记但 executor 报告 false → 不传播 (以运行时实际为准)
-
-### 11.7 — Phase handoff gate
-
-<HARD-GATE id="phase-handoff">
-所有条件必须满足才能进入下一 phase:
-- [ ] 所有 required task = `accepted`
-- [ ] required review = `passed`
-- [ ] critical issues = 0
-- [ ] tests/lint/typecheck 满足计划验证条件
-- [ ] 方向校验: 当前阶段产出是否仍与 plan.md 中的项目目标一致？
-
-→ 全部满足 → 自动进入下一阶段
-→ 任一不满足 → 标注问题，尝试修复，3 次失败停止
-→ 方向漂移 → workflow_mode = awaiting_user，展示偏差让用户决定
-</HARD-GATE>
-
-### 11.8 — 批量更新 state.json
-
-阶段完成后，编排器批量更新 state.json:
-- 更新 phase lifecycle → `accepted`
-- 更新 phase_handoff 信息
-- 归档旧 phase 的 evidence (只保留当前 phase 和上一 phase)
-- 推进 `current_phase` 到下一个 pending phase
-
-**规则:** 只有编排器写 state.json，避免并发竞态。
-
-### 11.9 — 上下文检查
-
-每次派发子代理前和阶段切换时检查上下文健康度:
-
-```
-remaining < 35%:
-  1. 保存完整状态到 state.json
-  2. workflow_mode = awaiting_clear
-  3. 输出: "上下文剩余 <35%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
-  4. 停止执行
-
-remaining < 25%:
-  1. 紧急保存状态到 state.json
-  2. workflow_mode = awaiting_clear
-  3. 输出: "上下文即将耗尽，已保存进度。请立即执行 /clear 然后 /gsd:resume"
-  4. 立即停止
-```
-
+编排器必须严格按照该参考文档中的步骤顺序执行:
+加载 phase → 选择 task → 构建上下文 → 派发 executor → 处理结果 → 审查 → phase handoff → 批量更新 → 上下文检查
 </execution_loop>
 
-### 依赖门槛语义 (Gate-aware dependencies)
-
-```json
-{ "kind": "task",  "id": "2.2", "gate": "checkpoint" }     // 低风险内部串接
-{ "kind": "task",  "id": "2.3", "gate": "accepted" }        // 默认安全门槛
-{ "kind": "phase", "id": 2,     "gate": "phase_complete" }  // 跨 phase 依赖
-```
-
-- `checkpoint` — 允许依赖未独立验收的实现检查点；只适合低风险内部串接
-- `accepted` — 默认安全门槛；适合共享行为、公共接口、L2 风险任务
-- `phase_complete` — 跨 phase 依赖；只有 phase handoff 完成后才释放
-- 默认值: 如果 planner 没显式放宽，则依赖按 `accepted` 处理
-
 ## STEP 12 — 最终报告
 
 全部 phase 完成后，输出最终报告:

package/hooks/gsd-context-monitor.cjs

@@ -9,7 +9,10 @@
 // 3. When remaining context drops below thresholds, injects a warning
 //    via hookSpecificOutput.additionalContext
 //
-// Thresholds:
+// Only active when GSD project is running (has_gsd = true in bridge file).
+// Non-GSD sessions exit early — Claude's auto-compaction handles context.
+//
+// Thresholds (GSD sessions only):
 //   WARNING  (remaining <= 35%): Agent should wrap up current task
 //   CRITICAL (remaining <= 25%): Agent must stop and save state
 //
@@ -33,11 +36,13 @@ process.stdin.on('end', () => {
   clearTimeout(stdinTimeout);
   try {
     const data = JSON.parse(input);
-    const sessionId = data.session_id;
+    const rawSessionId = data.session_id;
 
-    if (!sessionId) {
+    if (!rawSessionId) {
       process.exit(0);
     }
+    const sessionId = String(rawSessionId).replace(/[^a-zA-Z0-9_-]/g, '');
+    if (!sessionId) process.exit(0);
 
     const tmpDir = os.tmpdir();
     const metricsPath = path.join(tmpDir, `gsd-ctx-${sessionId}.json`);
@@ -56,9 +61,10 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
-    // Ignore stale metrics
+    // Ignore stale metrics (treat missing timestamp as stale)
     const now = Math.floor(Date.now() / 1000);
-    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+    const metricAge = now - (metrics.timestamp || 0);
+    if (metricAge > STALE_SECONDS) {
       process.exit(0);
     }
 
@@ -94,20 +100,19 @@ process.stdin.on('end', () => {
     // Use bridge data to avoid extra filesystem check
     const isGsdActive = metrics.has_gsd === true;
 
+    // Non-GSD sessions: don't interfere — let Claude's auto-compaction handle it
+    if (!isGsdActive) {
+      process.exit(0);
+    }
+
     let message;
     if (isCritical) {
-      message = isGsdActive
-        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. `
-          + 'Context is nearly exhausted. Complete current task checkpoint immediately, '
-          + 'set workflow_mode = awaiting_clear via gsd-state-update, and tell user to /clear then /gsd:resume.'
-        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. `
-          + 'Context is nearly exhausted. Inform the user that context is low and ask how they want to proceed.';
+      message = `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. `
+        + 'Context is nearly exhausted. Complete current task checkpoint immediately, '
+        + 'set workflow_mode = awaiting_clear via gsd-state-update, and tell user to /clear then /gsd:resume.';
     } else {
-      message = isGsdActive
-        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. `
-          + 'Context is getting limited. Avoid starting new complex work. Complete current task then save state.'
-        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. `
-          + 'Be aware that context is getting limited. Avoid unnecessary exploration or starting new complex work.';
+      message = `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. `
+        + 'Context is getting limited. Avoid starting new complex work. Complete current task then save state.';
     }
 
     const output = {
@@ -118,7 +123,8 @@ process.stdin.on('end', () => {
     };
 
     process.stdout.write(JSON.stringify(output));
-  } catch {
+  } catch (e) {
+    if (process.env.GSD_DEBUG) process.stderr.write(`gsd-context-monitor: ${e.message}\n`);
     process.exit(0);
   }
 });

package/hooks/gsd-session-init.cjs

@@ -53,7 +53,7 @@ try {
   };
 
   // Atomic write to avoid corruption
-  const tmpPath = settingsPath + '.gsd-tmp';
+  const tmpPath = settingsPath + `.gsd-tmp-${process.pid}`;
   fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + '\n');
   fs.renameSync(tmpPath, settingsPath);
 } catch {

package/hooks/gsd-statusline.cjs

@@ -17,7 +17,8 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input);
     const model = data.model?.display_name || 'Claude';
     const cwd = data.workspace?.current_dir || process.cwd();
-    const session = data.session_id || '';
+    const session = String(data.session_id || '').replace(/[^a-zA-Z0-9_-]/g, '');
+    if (!session) process.exit(0); // Reject empty session ID to avoid bridge file collision
     const remaining = data.context_window?.remaining_percentage;
 
     // Current GSD task from state.json
@@ -64,26 +65,27 @@ process.stdin.on('end', () => {
             }));
             fs.renameSync(tmpBridge, bridgePath);
           }
-        } catch {
-          // Silent fail — bridge is best-effort
+        } catch (e) {
+          if (process.env.GSD_DEBUG) process.stderr.write(`gsd-statusline: bridge write failed: ${e.message}\n`);
         }
       }
 
-      // Also write to .gsd/.context-health for MCP server reads (skip if unchanged)
+      // Also write to .gsd/.context-health for MCP server reads (atomic, skip if unchanged)
       try {
         const healthPath = path.join(gsdDir, '.context-health');
-        const current = fs.readFileSync(healthPath, 'utf8').trim();
-        if (current !== String(remaining)) {
-          fs.writeFileSync(healthPath, String(remaining));
-        }
-      } catch {
-        // File doesn't exist yet or .gsd/ missing — ensure dir exists then atomic write
+        let needsHealthWrite = true;
         try {
+          const current = fs.readFileSync(healthPath, 'utf8').trim();
+          if (current === String(remaining)) needsHealthWrite = false;
+        } catch { /* file doesn't exist yet */ }
+        if (needsHealthWrite) {
           fs.mkdirSync(gsdDir, { recursive: true });
-          const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}.tmp`);
+          const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}-${Date.now()}.tmp`);
           fs.writeFileSync(tmpHealth, String(remaining));
-          fs.renameSync(tmpHealth, path.join(gsdDir, '.context-health'));
-        } catch { /* silent */ }
+          fs.renameSync(tmpHealth, healthPath);
+        }
+      } catch (e) {
+        if (process.env.GSD_DEBUG) process.stderr.write(`gsd-statusline: context-health write failed: ${e.message}\n`);
       }
 
       // Progress bar (10 segments)
@@ -108,7 +110,7 @@ process.stdin.on('end', () => {
     } else {
       process.stdout.write(`\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
     }
-  } catch {
-    // Silent fail
+  } catch (e) {
+    if (process.env.GSD_DEBUG) process.stderr.write(`gsd-statusline: ${e.message}\n`);
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-lite",
-  "version": "0.3.1",
+  "version": "0.3.5",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "type": "module",
   "bin": {

package/references/evidence-spec.md

@@ -0,0 +1,167 @@
+# Evidence 系统规格参考
+
+## 概述
+
+Evidence 是 GSD-Lite 的验证证据系统，用于记录 task 和 phase 的执行/审查证据。存储在 `state.json` 的 `evidence` 字段中，以 key-value 对象形式组织。
+
+## Evidence 对象结构
+
+`state.evidence` 是一个扁平对象，key 为 evidence ID，value 为 evidence 数据对象。
+
+```json
+{
+  "evidence": {
+    "ev:test:phase-1": {
+      "id": "ev:test:phase-1",
+      "scope": "task:1.2",
+      "type": "test",
+      ...
+    },
+    "ev:lint:2.3": {
+      "id": "ev:lint:2.3",
+      "scope": "task:2.3",
+      "type": "lint",
+      ...
+    }
+  }
+}
+```
+
+### 必需字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | string | 非空 | evidence 唯一标识符 |
+| `scope` | string | 非空 | 作用域标识，格式见下方 |
+
+### 验证规则
+
+`addEvidence()` 入参校验:
+- `id` 必须是非空字符串
+- `data` 必须是非 null 的普通对象
+- `data.scope` 必须是字符串
+
+`state.evidence` 整体校验 (`validateState()`):
+- 必须是普通对象 (isPlainObject)
+
+## ID 格式约定
+
+Evidence ID 采用 `ev:<type>:<scope>` 格式:
+
+```
+ev:test:phase-1       # phase 级测试证据
+ev:lint:phase-2       # phase 级 lint 证据
+ev:test:users-update  # task 级测试证据
+ev:typecheck:phase-2  # phase 级类型检查证据
+```
+
+此格式为约定 (convention)，由 executor/reviewer 生成时遵守。系统不强制校验 ID 格式。
+
+## Scope 格式
+
+Scope 标识 evidence 所属的作用域。核心格式为 `task:X.Y`:
+
+```
+task:1.2   -> phase 1, task 2
+task:2.3   -> phase 2, task 3
+task:3.1   -> phase 3, task 1
+```
+
+### parseScopePhase 解析
+
+`parseScopePhase(scope)` 从 scope 字符串提取 phase 编号:
+
+- 正则: `/^task:(\d+)\./`
+- `"task:1.2"` -> 返回 `1`
+- `"task:2.3"` -> 返回 `2`
+- `"phase:1"` -> 返回 `null` (不匹配 task: 前缀)
+- `null`/`undefined` -> 返回 `null`
+
+此函数用于 evidence 归档时判断 evidence 所属 phase。
+
+来源: `parseScopePhase()` in `src/tools/state.js`
+
+## 容量限制与自动裁剪
+
+### MAX_EVIDENCE_ENTRIES
+
+- 硬限制: `200` 条
+- 定义位置: `src/tools/state.js` 顶层常量
+
+### 自动裁剪触发
+
+`addEvidence()` 每次添加 evidence 后检查:
+
+```
+if (Object.keys(state.evidence).length > MAX_EVIDENCE_ENTRIES) {
+  -> 调用 _pruneEvidenceFromState(state, currentPhase, gsdDir)
+}
+```
+
+### 裁剪逻辑
+
+`_pruneEvidenceFromState(state, currentPhase, gsdDir)`:
+
+1. 计算阈值: `threshold = currentPhase - 1`
+2. 遍历所有 evidence 条目
+3. 对每条 evidence 调用 `parseScopePhase(entry.scope)` 提取 phase 编号
+4. 如果 `phaseNum !== null && phaseNum < threshold` -> 标记为待归档
+5. 其余保留 (包括 scope 无法解析的条目)
+
+规则: 保留当前 phase 和前一个 phase 的 evidence，归档更早 phase 的 evidence。
+
+## 归档生命周期
+
+### 归档路径
+
+`.gsd/evidence-archive.json`
+
+### 归档流程
+
+```
+_pruneEvidenceFromState()
+  -> 分离 toArchive / toKeep
+  -> 读取现有 evidence-archive.json (不存在则 {})
+  -> Object.assign(archive, toArchive) 合并
+  -> writeJson(archivePath, archive) 写入归档文件
+  -> state.evidence = toKeep 更新内存中的 state
+```
+
+### 触发时机
+
+1. `addEvidence()` — 当 evidence 数量超过 MAX_EVIDENCE_ENTRIES 时自动触发
+2. `phaseComplete()` — phase 完成后主动触发 (在 phase lifecycle 转换为 accepted 之后)
+3. `pruneEvidence()` — 显式调用的外部接口
+
+### 归档特性
+
+- 归档是追加式的: 新归档条目与已有归档 merge
+- 归档后 state.evidence 中的对应条目被移除
+- 归档文件持久保存，不会被自动清理
+
+## Evidence 来源
+
+### Executor 结果
+
+`handleExecutorResult()` 处理 executor 返回的 evidence:
+
+1. `result.evidence` 数组写入 task 的 `evidence_refs`
+2. 对数组中每个符合条件的条目 (有 `id` 和 `scope` 字符串字段) 调用 `addEvidence()` 存入 `state.evidence`
+3. outcome 为 `checkpointed` / `blocked` / `failed` 时均会保存 evidence_refs
+
+### Reviewer 结果
+
+`handleReviewerResult()` 处理 reviewer 返回的 evidence:
+
+1. 同样遍历 `result.evidence` 数组
+2. 对符合条件的条目调用 `addEvidence()` 存入 `state.evidence`
+
+### Task 上的 evidence_refs
+
+每个 task 对象有 `evidence_refs` 数组字段:
+- 类型: `Array` (validateState 要求)
+- 初始值: `[]`
+- 更新时机: executor checkpointed / blocked / failed 时从 result.evidence 覆写
+- 清空时机: `propagateInvalidation()` 或 reviewer 标记 rework 时清空为 `[]`
+
+来源: `addEvidence()`, `_pruneEvidenceFromState()`, `pruneEvidence()`, `phaseComplete()` in `src/tools/state.js`; `handleExecutorResult()`, `handleReviewerResult()` in `src/tools/orchestrator.js`