gsd-lite 0.3.2 → 0.3.6

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.6",
       "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.6",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "author": {
     "name": "sdsrss",

package/agents/debugger.md

@@ -1,7 +1,7 @@
 ---
 name: debugger
 description: Systematic debugging with root cause analysis
-tools: Read, Write, Edit, Bash, Grep, Glob
+tools: Read, Bash, Grep, Glob
 ---
 
 <role>
@@ -54,11 +54,11 @@ Phase 3 假设测试:
   2. 最小变更测试 (一次只改一个变量)
   3. 验证: 有效 → Phase 4 / 无效 → 新假设
 
-Phase 4 实施修复:
-  1. 写失败测试 (复现 bug)
-  2. 修复根因 (不是症状)
-  3. 验证测试通过 + 无回归
-  → 3 次修复失败 → 停止。质疑架构。报告给编排器。
+Phase 4 修复方向建议:
+  1. 提出修复方案 (针对根因，不是症状)
+  2. 建议失败测试用例 (供 executor 实现)
+  3. 评估修复影响范围 (哪些下游可能受影响)
+  → 3 次修复方向均被 executor 验证无效 → 停止。标记 architecture_concern: true。报告给编排器。
 </four_phases>
 
 <result_contract>

package/agents/researcher.md

@@ -39,3 +39,12 @@ tools: Read, Write, Bash, WebSearch, WebFetch, mcp__plugin_context7_context7__*
 ```
 </result_contract>
 </research_output>
+
+<uncertainty_handling>
+## 遇到不确定性时
+子代理不能直接与用户交互。遇到不确定性时:
+1. 来源冲突 → 报告双方立场及置信度，让编排器决定。在 result 中标注 "[DECISION] 选择了X因为Y"
+2. 所有来源不可用 (Context7 + WebSearch + 官方文档均失败) → 返回 "[BLOCKED] 需要: 研究来源不可用，请提供替代信息或缩小范围"
+3. 研究范围过广无法收敛 → 返回 "[BLOCKED] 需要: 研究范围过广，请指定重点领域"
+4. 发现结论与已有 decisions 矛盾 → 在 result 中标注冲突，让编排器决定是否更新 decision
+</uncertainty_handling>

package/commands/prd.md

@@ -100,12 +100,16 @@ argument-hint: File path to requirements doc, or inline description text
 
 → 自审修正后再展示给用户
 
+<HARD-GATE id="plan-confirmation">
 ## STEP 9: 展示计划，等待用户确认
 
 - 展示完整分阶段计划
 - 用户指出问题 → 调整 → 再展示
 - 用户确认 → 继续
 
+⛔ 不得在用户确认前执行 STEP 10-12。未确认 = 不写文件、不执行代码。
+</HARD-GATE>
+
 ## STEP 10: 生成文档
 
 - 创建 .gsd/ 目录
@@ -126,149 +130,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

@@ -35,17 +35,18 @@ description: Resume project execution from saved state with workspace validation
      - 不一致 → 覆写 `workflow_mode = reconcile_workspace`
 
 2. **计划版本校验:**
-   - 如果本地 plan.md 或 phases/*.md 被手动修改，且 `plan_version` 不匹配
+   - 如果本地 plan.md 或 phases/*.md 被手动修改 (mtime > last_session)
    - → 覆写 `workflow_mode = replan_required`
 
-3. **研究过期校验:**
+3. **方向漂移校验:**
+   - 如果当前或任何未完成 phase 的 `phase_handoff.direction_ok === false`
+   - → 覆写 `workflow_mode = awaiting_user`
+
+4. **研究过期校验:**
    - 如果 `research.expires_at` 已过期 (早于当前时间)
+   - 或 research.decision_index 中有条目的 expires_at 已过期
    - → 覆写 `workflow_mode = research_refresh_needed`
 
-4. **工作区冲突校验:**
-   - 运行 `git status` 检查是否存在冲突或脏工作区
-   - 存在未解决的合并冲突 → 覆写 `workflow_mode = awaiting_user`
-
 5. **全部通过:**
    - 保持原 `workflow_mode` 不变
 
@@ -68,7 +69,7 @@ description: Resume project execution from saved state with workspace validation
   - requires 中每个依赖都满足对应 gate
   - 未超过 retry 上限
 - 构建 executor 上下文 → 派发 executor 子代理
-- 继续自动执行主路径 (按 start.md STEP 11 执行循环)
+- 继续自动执行主路径 (按 references/execution-loop.md 执行循环)
 
 ---
 
@@ -176,6 +177,14 @@ description: Resume project execution from saved state with workspace validation
 
 ---
 
+### `planning` — 计划中断
+
+- 计划编制过程中被中断
+- 告知用户: "项目仍在计划阶段。请运行 /gsd:start 或 /gsd:prd 重新启动计划流程"
+- 不自动执行
+
+---
+
 ### `failed` — 已失败
 
 - 展示失败信息:

package/commands/start.md

@@ -30,7 +30,7 @@ argument-hint: Optional feature or project description
 ## STEP 4 — 需求追问
 
 用户回答后，跟进追问直到需求清晰:
-- 使用 `references/questioning.md` 技巧 (挑战模糊、具象化、发现边界)
+- 使用 Read 工具读取 `references/questioning.md`，按其中的技巧进行提问 (挑战模糊、具象化、发现边界)
 - 每个问题提供选项，标识 ⭐ 推荐选项
 - 多轮对话直到需求清晰 (通常 2-4 轮)
 - 每轮最多 3-5 个问题，避免过度追问
@@ -113,12 +113,17 @@ argument-hint: Optional feature or project description
 
 → 自审修正后再展示给用户。
 
+<HARD-GATE id="plan-confirmation">
 ## STEP 9 — 用户确认计划
 
 展示计划给用户，等待确认:
 - 用户指出问题 → 调整计划 → 重新展示
 - 用户确认 → 继续
 
+⛔ 不得在用户确认前执行 STEP 10-12。未确认 = 不写文件、不执行代码。
+</HARD-GATE>
+
+<HARD-GATE id="docs-written">
 ## STEP 10 — 生成文档
 
 1. 创建 `.gsd/` 目录
@@ -141,169 +146,24 @@ argument-hint: Optional feature or project description
 - `phases/*.md` 是 task 规格的唯一 source of truth
 - `plan.md` 不包含 task 级细节，避免与 `phases/*.md` 重复
 
+□ state.json 已写入且包含所有 canonical fields
+□ plan.md 已写入
+□ phases/*.md 已写入 (每个 phase 一个文件)
+□ 所有 task 都有 lifecycle / level / requires / review_required
+→ 全部满足才可继续
+</HARD-GATE>
+
 ## STEP 11 — 自动执行主路径
 
 进入执行主循环。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/commands/stop.md

@@ -11,8 +11,9 @@ description: Save current state and pause project execution
 
 ## STEP 1: 保存完整状态
 
-读取并更新 `.gsd/state.json`:
+读取 `.gsd/state.json`:
 - 如果文件不存在 → 告知用户 "未找到 GSD 项目状态，无需停止"，停止
+- 如果 `workflow_mode` 已是 `completed` 或 `failed` → 告知用户 "项目已终结 ({workflow_mode})，无需停止"，停止
 
 确保以下信息已保存到 state.json:
 - `current_phase` / `current_task` — 当前执行位置

package/hooks/context-monitor.js

@@ -31,10 +31,10 @@ export function postToolUse(basePath) {
     const gsdDir = join(basePath || process.cwd(), '.gsd');
     const health = parseInt(readFileSync(join(gsdDir, '.context-health'), 'utf-8'), 10);
 
-    if (health < 25) {
+    if (health <= 25) {
       return `🛑 CONTEXT EMERGENCY (${health}% remaining): Save state NOW. Set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
     }
-    if (health < 35) {
+    if (health <= 35) {
       return `⚠️ CONTEXT LOW (${health}% remaining): Complete current task, save state, set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
     }
   } catch (err) {

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,20 +61,25 @@ 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);
+    }
+
+    // Non-GSD sessions: don't interfere — let Claude's auto-compaction handle it
+    const isGsdActive = metrics.has_gsd === true;
+    if (!isGsdActive) {
       process.exit(0);
     }
 
     // Debounce logic
     const warnPath = path.join(tmpDir, `gsd-ctx-${sessionId}-warned.json`);
     let warnData = { callsSinceWarn: 0, lastLevel: null };
-    let firstWarn = true;
 
     try {
       warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
-      firstWarn = false;
     } catch {
       // No prior warning state — first warning this session
     }
@@ -79,35 +89,33 @@ process.stdin.on('end', () => {
     const isCritical = remaining <= CRITICAL_THRESHOLD;
     const currentLevel = isCritical ? 'critical' : 'warning';
 
-    // Severity escalation bypasses debounce
+    // Atomic debounce state write helper
+    const writeWarnData = (data) => {
+      const tmpFile = warnPath + `.${process.pid}-${Date.now()}.tmp`;
+      fs.writeFileSync(tmpFile, JSON.stringify(data));
+      fs.renameSync(tmpFile, warnPath);
+    };
+
+    // Severity escalation bypasses debounce (lastLevel null = first warning, always fire)
     const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
-    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
-      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+    if (warnData.lastLevel !== null && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      writeWarnData(warnData);
       process.exit(0);
     }
 
     // Reset debounce
     warnData.callsSinceWarn = 0;
     warnData.lastLevel = currentLevel;
-    fs.writeFileSync(warnPath, JSON.stringify(warnData));
-
-    // Use bridge data to avoid extra filesystem check
-    const isGsdActive = metrics.has_gsd === true;
+    writeWarnData(warnData);
 
     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 +126,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 {