gsd-lite 0.3.2 → 0.3.6

package/hooks/gsd-statusline.cjs

@@ -7,6 +7,25 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
+/**
+ * Walk from startDir up to filesystem root looking for a .gsd directory.
+ * Returns the absolute path to .gsd if found, or null.
+ */
+function findGsdDir(startDir) {
+  let dir = startDir;
+  while (true) {
+    const candidate = path.join(dir, '.gsd');
+    try {
+      fs.statSync(candidate);
+      return candidate;
+    } catch {
+      const parent = path.dirname(dir);
+      if (parent === dir) return null; // reached filesystem root
+      dir = parent;
+    }
+  }
+}
+
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);
 process.stdin.setEncoding('utf8');
@@ -17,13 +36,14 @@ 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
     let task = '';
     let hasGsd = false;
-    const gsdDir = path.join(cwd, '.gsd');
+    const gsdDir = findGsdDir(cwd);
     try {
       const state = JSON.parse(fs.readFileSync(path.join(gsdDir, 'state.json'), 'utf8'));
       hasGsd = true;
@@ -64,26 +84,30 @@ 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)
-      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
+      // Also write to .gsd/.context-health for MCP server reads (atomic, skip if unchanged)
+      // Only write if a .gsd directory was found — never create .gsd from the hook
+      if (gsdDir) {
         try {
-          fs.mkdirSync(gsdDir, { recursive: true });
-          const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}.tmp`);
-          fs.writeFileSync(tmpHealth, String(remaining));
-          fs.renameSync(tmpHealth, path.join(gsdDir, '.context-health'));
-        } catch { /* silent */ }
+          const healthPath = path.join(gsdDir, '.context-health');
+          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}-${Date.now()}.tmp`);
+            fs.writeFileSync(tmpHealth, String(remaining));
+            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 +132,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.2",
+  "version": "0.3.6",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "type": "module",
   "bin": {

package/references/evidence-spec.md

@@ -0,0 +1,166 @@
+# 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. 遍历所有 evidence 条目
+2. 对每条 evidence 调用 `parseScopePhase(entry.scope)` 提取 phase 编号
+3. 如果 `phaseNum !== null && phaseNum < currentPhase` -> 标记为待归档
+4. 其余保留 (包括 scope 无法解析的条目)
+
+规则: 仅保留当前 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`

package/references/execution-loop.md

@@ -0,0 +1,162 @@
+# Execution Loop -- Canonical Specification
+
+本文件是执行循环的唯一 source of truth。所有 command 文件 (start.md, prd.md, resume.md) 引用此文件。
+
+---
+
+### 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)
+- 推进 `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. 立即停止
+```
+
+---
+
+## 依赖门槛语义 (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` 处理

package/references/review-classification.md

@@ -0,0 +1,84 @@
+# 审查级别分类参考
+
+## 静态分类 (计划时)
+
+| 级别 | 适用场景 | 审查方式 |
+|------|---------|---------|
+| L0 | 无运行时语义变化 (docs/config/style) | checkpoint 后直接 accepted |
+| L1 | 普通编码任务 (默认) | phase 结束后批量审查 |
+| L2 | 高风险 (auth/payment/public API/DB migration) | checkpoint 后立即独立审查 |
+
+## 运行时重分类
+
+触发条件 (L1 -> L2 升级):
+1. executor 报告 `contract_changed: true` 且 task name 匹配敏感关键词
+2. executor decisions 中包含 `[LEVEL-UP]` 标注 (字符串或 `decision.summary` 中包含)
+
+敏感关键词正则 (`SENSITIVE_KEYWORDS`):
+
+```
+/\b(auth|payment|security|public.?api|login|token|credential|session|oauth)\b/i
+```
+
+规则: 只升不降 (安全优先)。当前级别为 L2 或 L3 时直接保持不变。
+
+## 决策树
+
+```
+task.level 当前值?
+├── L2 或 L3 -> 保持不变 (不降级)
+└── L0 或 L1
+    ├── executor decisions 含 [LEVEL-UP]? -> 升级为 L2
+    ├── contract_changed: true + task.name 匹配敏感关键词? -> 升级为 L2
+    └── 否 -> 保持当前级别
+```
+
+来源: `reclassifyReviewLevel()` in `src/tools/state.js`
+
+## 审查流程
+
+### L0 流程
+
+```
+executor checkpointed
+  -> handleExecutorResult 检测 reviewLevel === 'L0'
+  -> auto_accepted = true
+  -> 编排器直接 accepted (persist lifecycle: 'accepted', done +1)
+  -> 释放下游依赖
+```
+
+不派发 reviewer。`review_required: false` 的 task 同样走此路径。
+
+### L1 流程
+
+```
+executor checkpointed
+  -> workflow_mode 保持 'executing_task'
+  -> 继续执行其他 task
+  -> phase 内所有 runnable task 完成后
+  -> selectRunnableTask 返回 { mode: 'trigger_review' }
+  -> 编排器设置 workflow_mode = 'reviewing_phase'
+  -> 派发 reviewer (scope='phase', review_level='L1-batch')
+  -> 批量审查所有 checkpointed task (排除 L0)
+```
+
+### L2 流程
+
+```
+executor checkpointed
+  -> handleExecutorResult 检测 reviewLevel === 'L2' && review_required !== false
+  -> 设置 current_review = { scope: 'task', scope_id: task.id, stage: 'spec' }
+  -> workflow_mode = 'reviewing_task'
+  -> 派发 reviewer (scope='task', review_level='L2')
+  -> 审查通过后才释放下游依赖
+```
+
+## Reviewer 结果处理
+
+| 审查结果 | 编排器行为 |
+|----------|-----------|
+| 无 critical issues | accepted_tasks 标记为 `accepted`; phase_review.status = `accepted` |
+| 有 critical issues | rework_tasks 标记为 `needs_revalidation`; phase_review.status = `rework_required` |
+| critical + `invalidates_downstream` | 触发 `propagateInvalidation`: 所有下游依赖 task -> `needs_revalidation` + 清空 evidence_refs |
+
+来源: `handleReviewerResult()` in `src/tools/orchestrator.js`, `reviewer.md` in `agents/`