ccgx-workflow 2.4.1 → 2.5.0

package/templates/commands/verify-work.md

@@ -81,7 +81,7 @@ pending_checks:
 
 ## 工作流程（lifecycle）
 
-### Step 0 — Resume 检测
+### Step 0 — Resume 检测 `[Gate: pre-flight]`
 
 ```bash
 TASK_ID="${1:-$(detect-task-id)}"  # detect-task-id 见下
@@ -93,7 +93,8 @@ UAT_FILE="${UAT_DIR}/UAT.md"
 1. 命令参数 `$ARGUMENTS`（用户显式给）
 2. `.context/state.md` 当前 phase 字段
 3. `git rev-parse --abbrev-ref HEAD` 分支名（取最后一段）
-4. 用 `verify-work-$(date +%Y%m%d-%H%M)` 兜底
+4. **[Gate: pre-flight 阻断分支]** 优先级 1-3 全失败且 `git diff --name-only HEAD` 为空 → 输出阻断提示并**停止**，要求用户显式传 task-id（`/ccg:verify-work <task-id>`），不产生任何部分工作——与 GATE_REGISTRY `verify-work-entry` 的 failurePath（"task-id 无法推断且无 git diff → 阻断"）对齐
+5. 有 git diff 时才启用 `verify-work-$(date +%Y%m%d-%H%M)` 时间戳兜底
 
 ```bash
 if [ -f "$UAT_FILE" ]; then
@@ -136,15 +137,15 @@ fi
 
 按 git diff 性质开门（决策矩阵）：
 
-| 变更性质 | 触发判据 | 门组 |
-|---------|---------|------|
-| 新模块 | `git status` 显示新增目录 | verify-module → verify-security → verify-quality |
-| 小改动 | diff ≤ 30 行 | verify-quality → verify-change |
-| 常规改动 | diff 30-200 行 | verify-change → verify-quality → verifier agent |
-| 安全敏感 | 触及 auth/crypto/input/secret/sql 关键字 | verify-security → verify-change → verifier agent |
-| 重构 | 含 `refactor:` commit | verify-change → verify-quality → verify-security |
+| 变更性质 | 触发判据 | 门组 | Gate 类型 |
+|---------|---------|------|----------|
+| 新模块 | `git status` 显示新增目录 | verify-module → verify-security → verify-quality | revision-loop（verify-security critical → abort 覆盖） |
+| 小改动 | diff ≤ 30 行 | verify-quality → verify-change | revision-loop |
+| 常规改动 | diff 30-200 行 | verify-change → verify-quality → verifier agent | revision-loop |
+| 安全敏感 | 触及 auth/crypto/input/secret/sql 关键字 | verify-security → verify-change → verifier agent | revision-loop（verify-security critical → abort 覆盖） |
+| 重构 | 含 `refactor:` commit | verify-change → verify-quality → verify-security | revision-loop（verify-security critical → abort 覆盖） |
 
-每门返回结构化 `{ gate, status, counts, top_findings, artifacts }`，**FAIL with critical** 立即 short-circuit 用户先修，进 Step 5 前不继续问 UAT。
+每门返回结构化 `{ gate, status, counts, top_findings, artifacts }`，**FAIL with critical** 立即 short-circuit 用户先修，进 Step 5 前不继续问 UAT。`[Gate: abort——停 UAT、UAT.md 状态保留、修复后 resume]`
 
 #### 2b. Cold-start smoke 自动注入
 
@@ -231,11 +232,30 @@ gaps:
 
 #### 5b. 并行 spawn diagnose
 
+按 debug.md 阶段 2 的 spawn 契约调度 `debug-session-manager`（fresh context，只找根因不修）：
+
 ```
-Agent(subagent_type="ccg:debug", task=<symptom>, run_in_background=true)
+Agent({
+  subagent_type: "debug-session-manager",
+  run_in_background: true,
+  prompt: `你是 debug-session-manager。完整执行多轮 hypothesis 循环，最终返回 ≤ 200 token 紧凑摘要。
+
+## 输入
+
+slug: uat-<task-id>-G-<n>
+mode: find_root_cause_only
+workdir: <Bash pwd 取的项目绝对路径>
+symptoms: |
+  <gap.symptom 用户原话 + 复现上下文>
+
+## 工作要求
+
+（同 debug.md 阶段 2 prompt 模板：.context/debug/<slug>.md 持久 hypothesis 链、
+每个 hypothesis 必须 falsifiable、cap 3 refuted 升级、摘要严格三选一）`
+})
 ```
 
-debug agent 找根因，输出 `.context/uat/<task-id>/diagnose-G-<n>.md`。
+manager 返回 `ROOT_CAUSE_FOUND` / `CHECKPOINT_REACHED` 摘要后，主线把根因写入 `.context/uat/<task-id>/diagnose-G-<n>.md`。
 
 #### 5c. spawn planner --gaps
 
@@ -253,7 +273,7 @@ Agent(subagent_type="plan-checker", plan=<fix-plan>)
 
 返回 `{ findings, hasBlocker, counts }`。
 
-#### 5e. max-3-loop 收敛
+#### 5e. max-3-loop 收敛 `[Gate: revision-loop max3 → escalation]`
 
 ```
 loop_count += 1
@@ -273,6 +293,8 @@ else:
 
 **3 轮上限是硬规约**——与 plan-review-convergence / code-review-fix 一致。
 
+**stall detection（提前升级）**：本轮 critical/BLOCKER 数 ≥ 上一轮 → 不等 3 轮直接升级（`resolveVerifyGateAction` 语义：连续两轮 issue 数不下降说明收敛环已失效）。
+
 ### Step 6 — 终态报告
 
 所有 check 已答（含 skip）+ 所有 gap 状态 ∈ {fixed, deferred}：
@@ -327,6 +349,7 @@ else:
 | `src/utils/uat-session.ts:inferIssueSeverity` | Step 5a 严重度推断 |
 | `src/utils/uat-session.ts:decideConvergence` | Step 5e max-3-loop 判定 |
 | `src/utils/plan-checker.ts:runPlanChecker` | Step 5d 修复计划静态校验 |
+| `src/utils/verify-orchestrator.ts:resolveVerifyGateAction` | Step 5e 类型化失败路径（advance/revise/escalate + stall detection） |
 
 ## 硬性约束
 

package/templates/commands/verify.md

@@ -35,6 +35,7 @@ $ARGUMENTS
 - 提取首个 `--gate=<value>` 或 `--gate <value>`
 - 剩余非 flag 参数作为 `<path>`
 - 未指定 gate → 默认 `all`
+- **[Gate: pre-flight]** `--gate` 值不在 `{change, quality, security, module, all}` 内 → 报错并打印枚举（"--gate 必须是 change | quality | security | module | all 之一"），不进入路由分发
 
 ## 路由规则
 
@@ -46,6 +47,39 @@ $ARGUMENTS
 | `module` | 读取并执行 `~/.claude/skills/ccg/tools/verify-module/SKILL.md` | 沿用旧 verify-module skill 的脚本 |
 | `all` | 调用 `/ccg:verify-work` 编排器 | 按 git diff 变更类型自动选门 |
 
+## Gates Taxonomy（4 类关卡与失败路径）
+
+全工作流的每个检查点都归属唯一的 gate 类型，失败时按该类型的确定性路径处理：
+
+| 类型 | 语义 | 失败行为 | 恢复方式 |
+|------|------|---------|---------|
+| **pre-flight** | 操作开始前验前置条件 | 阻断入口，**不产生任何部分工作** | 补前置条件后重试 |
+| **revision-loop** | 评估产出质量，不足则带具体反馈回喂 producer | max 3 轮迭代；**stall detection：连续两轮 issue 数不下降 → 提前升级**；轮次耗尽无条件升级 | 反馈修复后重跑 |
+| **escalation** | 浮出无法自动解决的问题给人决策 | 暂停工作流、给选项（force / guide / abort）、等人选路 | 人选定路径后继续 |
+| **abort** | 为止损立即终止 | **保留状态**、报告原因 | 人查根因修复后从 checkpoint 重启 |
+
+选型启发：先 pre-flight；检查发生在产出之后 = revision-loop；revision 解不了 = escalation；继续有害 = abort。
+
+### 每门分类表
+
+| Gate | 类型 | critical 覆盖 | maxLoops | 失败路径 |
+|------|------|--------------|----------|---------|
+| `execute-entry` | pre-flight | — | — | `.claude/plan/<name>.md` 缺失 → 阻断入口，提示先跑 `/ccg:plan`；不产生部分工作 |
+| `spec-impl-entry` | pre-flight | — | — | OPSX artifacts 缺失 → 阻断入口，提示先跑 `/ccg:spec-plan` |
+| `verify-work-entry` | pre-flight | — | — | task-id 无法推断且无 git diff → 阻断，要求显式传 task-id |
+| `verify-change` | revision-loop | — | 3 | findings 回喂修复→重跑；3 轮或 stall → escalation 三选 |
+| `verify-quality` | revision-loop | — | 3 | 同 verify-change |
+| `verify-module` | revision-loop | — | 3 | 缺文档/结构 → 补齐重跑；3 轮 → escalation |
+| `verify-security` | revision-loop | **abort** | 3 | critical 漏洞 → abort（停止交付、保留 UAT/job 状态、报原因、修复后 resume）；非 critical → revision-loop |
+| `plan-checker` | revision-loop | — | 3 | BLOCKER 回喂 planner（仅修 BLOCKER）；3 轮或 stall → escalation force/guide/abort |
+| `requirements-coverage` | escalation | — | — | 未覆盖 REQ-ID → 阻断 planning 完成 + AskUserQuestion 三选：re-plan 补覆盖（推荐）/移到下一 phase/force 接受并记录 |
+| `verify-wave` | revision-loop | — | 3 | critical → 修订轮（仅修 critical）；stall 或 3 轮 → escalation |
+| `uat-convergence` | revision-loop | — | 3 | diagnose→planner --gaps→plan-checker 收敛环；3 轮 → escalation 三选 |
+
+**单一真相源**：`src/utils/verify-orchestrator.ts` 的 `GATE_REGISTRY`（含 `getGateClassification` / `resolveVerifyGateAction` helper）。本表是其人类可读镜像，分类变更只在 helper 改。
+
+> **脚注**：本表是**全工作流 gate taxonomy 镜像**，不是 `--gate` 可路由集合——`--gate` 仅接受 `{change, quality, security, module, all}`。表内其余 gate 由各自命令在其工作流内触发（如 `requirements-coverage` 由 `/ccg:plan` 与 `/ccg:spec-plan` 触发，`execute-entry` 由 `/ccg:execute` 触发）。
+
 ## 兼容性
 
 旧的 `/ccg:verify-change` / `/ccg:verify-quality` / `/ccg:verify-security` / `/ccg:verify-module` 仍可工作（由 Skill Registry 自动生成），但 SKILL.md 已标记 `deprecated_in: 1.0.0`、`replaced_by: /ccg:verify --gate=<name>`。建议新工作流使用本统一命令。
@@ -60,6 +94,7 @@ $ARGUMENTS
 ## 注意事项
 
 - 本命令不**重新实现**校验逻辑，纯路由层。所有逻辑仍在 4 个 verify-* SKILL.md 中维护。
+- **[Gate: pre-flight]** `--gate=module` 未提供 `<path>` → 阻断并提示用法（`/ccg:verify --gate=module <模块路径>`），不进入子门执行。
 - `--gate=all` 是 `/ccg:verify-work` 的别名，未来可能合并。
 - 如脚本需要传 `--mode`（如 verify-change 的 `--mode staged`），通过 `path` 之后的额外参数透传：`/ccg:verify --gate=change -- --mode staged`。
 

package/templates/commands/workflow.md

@@ -41,52 +41,37 @@ subagent_freshness: required
 
 **调用通道路由（CCG codeagent 退役，v2.2.0+）**
 
-1. **优先 plugin spawn**（默认）：plugin 已装 → `Agent(subagent_type="<codex:codex-rescue|gemini:gemini-rescue>")`。session 复用通过 prompt 内 `--resume` flag 表达（subagent 映射为 codex/gemini `--resume-last`，**注意是 last，不是 by-id**）。
+1. **优先 Bash 直调 plugin 快路径**（默认）：plugin 已装 → 用 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 占位符 + `--prompt-file` Bash 直调（review.md 同款），绕开 sonnet wrapper silent-fallback；**仅 `gemini-ccgx` fork 走 gemini-batch 29s 快路径，上游 + repatch 仍走 companion(ACP) 慢路径**（Windows 实测 5+min 卡死风险仍在）。session 复用加 `--resume-last`（**注意是 last，不是 by-id**）。
 2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → Bash 调用，保留 `resume <SESSION_ID>` 显式会话管理。
 
-**判定**：preflight `Bash` 跑 `node ~/.claude/.ccg/scripts/check-plugins.cjs`（解析 Claude Code 权威 `installed_plugins.json`）。exit `0` + stdout `{"codex":"<ver>","gemini":"<ver>"}` → 通道 A（plugin 默认）；非 `0` → 通道 B（wrapper BC fallback）。
+**判定**：preflight `Bash` 跑 `node ~/.claude/.ccg/scripts/check-plugins.cjs`（解析 Claude Code 权威 `installed_plugins.json`）。exit `0` + stdout `{"codex":"<ver>","gemini":"<ver>"}` → 通道 A（Bash 直调快路径，默认）；非 `0` → 通道 B（wrapper BC fallback）。
 
 ---
 
-**通道 A — plugin spawn（默认）**：
+**通道 A — Bash 直调 plugin 快路径（默认）**：
 
-**预备动作**：spawn 前主线先 Read 对应阶段的角色提示词（见下方表），把内容拼入 `<role>` 块。
+> 占位符 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 由 install 渲染为 `node <ccgx-call-plugin.mjs 绝对路径> <vendor> --json`。LLM 只需 Write tmpfile + 追加 `--prompt-file <tmpfile>` 运行，**不写 `Agent(...)`、不内联 role 全文**。
 
 ```
-# 新会话调用
-Agent({
-  subagent_type: "<codex:codex-rescue|gemini:gemini-rescue>",
-  description: "简短描述",
-  prompt: `<role>
-${roleContent}  // 主线 Read 后的角色提示词内容
-</role>
+# 新阶段调用：Write tmpfile（≤2KB，让模型自己 Read 角色文件）+ Bash 直调
+Write({ file_path: ".context/tmp/ccg-workflow-<phase>-<vendor>-$JOB.txt", content: `# 任务：<阶段名>
 
-<workdir>{{WORKDIR}}</workdir>
+工作目录：{{WORKDIR}}（你已在此，可直接用 Bash/Read）
+角色定义见 <对应阶段角色提示词路径，见下方表>，**先用 Read 工具读取再开始**。
+**必须前台执行，禁止 --background / --wait**（ccgx 编排层已用 Agent run_in_background 包裹，插件内再 background = 双重后台，stop-gate / status / cancel 全盲）。
 
-<task>
 需求：<增强后的需求（如未增强则用 $ARGUMENTS）>
-上下文：<前序阶段收集的项目上下文、分析结果等>
-</task>
+上下文：<前序阶段关键文件路径 + 结论，不塞大段源码>
+<期望输出格式 / JSON schema>` })
 
-<structured_output_contract>
-<期望输出格式 / JSON schema>
-Return ≤200 token structured summary.
-</structured_output_contract>`
-})
-
-# 复用会话（同一 Claude session 内的连续阶段）
-Agent({
-  subagent_type: "<codex:codex-rescue|gemini:gemini-rescue>",
-  description: "简短描述",
-  prompt: `--resume
+Bash({ command: `{{CODEX_BASH_TASK 或 GEMINI_BASH_TASK}} --prompt-file .context/tmp/ccg-workflow-<phase>-<vendor>-$JOB.txt`, description: "简短描述", run_in_background: true })
 
-<task>
-<delta 指令（仅本阶段变化，不重述前序上下文，由 codex/gemini thread 自带历史）>
-</task>`
-})
+# 复用会话（同任务连续阶段，只发 delta）：加 --resume-last
+Bash({ command: `{{CODEX_BASH_TASK 或 GEMINI_BASH_TASK}} --resume-last --prompt-file .context/tmp/ccg-workflow-<phase>-<vendor>-delta-$JOB.txt`, description: "简短描述 (resume)", run_in_background: true })
+# delta tmpfile 只写本阶段变化指令，不重述前序上下文（codex/gemini thread 自带历史）。
 ```
 
-**通道 B — wrapper BC fallback**（plugin 未装时）：
+**通道 B — wrapper BC fallback**（plugin 未装时；wrapper 的 `ROLE_FILE:` 由 `invoke-model.mjs` 解析故保留）：
 
 ```
 # 新会话
@@ -106,7 +91,7 @@ Bash({
 })
 ```
 
-**角色提示词路径**（通道 A 主线 Read 后拼入 `<role>` 块；通道 B 仍用 `ROLE_FILE:` 写在 EOF 内）：
+**角色提示词路径**（通道 A 写入 tmpfile 让模型自己 Read；通道 B 仍用 `ROLE_FILE:` 写在 EOF 内由 invoke-model.mjs 解析）：
 
 | 阶段 | 后端 | 前端 |
 |------|-------|--------|
@@ -115,7 +100,7 @@ Bash({
 | 审查 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/reviewer.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/reviewer.md` |
 
 **会话复用模型差异**：
-- **通道 A（plugin）**：同 Claude session 内连续阶段用 `--resume`，自动接上一次同 backend 的 thread（codex/gemini 各自独立的 `--resume-last` 行为）。**不支持跨任务跳点 resume by ID**——若中间插了其他 codex 调用会串。
+- **通道 A（Bash 直调快路径）**：同任务连续阶段加 `--resume-last`，自动接上一次同 vendor 的 thread（codex 即刻可用；gemini 需 gemini-ccgx plugin ≥1.3.0——helper 有版本闸门，过旧会显式报错）。**通道 A 仅支持 `--resume-last`，不支持按 id resume**——若中间插了其他同 vendor 调用会串；`JSON.parse(stdout).threadId` 仅作审计记录，按 id resume 只有通道 B wrapper（invoke-model）可用。
 - **通道 B（wrapper）**：每次 spawn 返回 `SESSION_ID: xxx`，后续 `resume xxx` 任意复用（注意：是 `resume`，不是 `--resume`）。
 
 **并行调用 + 事件驱动等待**：
@@ -123,7 +108,7 @@ Bash({
 1. 同 message 内 spawn 多个 `Bash(run_in_background: true)` 并行任务
 2. spawn 完后主线说明已启动 task-id，**直接 turn end**，**不调 TaskOutput**
 3. Claude Code 引擎在每个 task 完成时自动发 `<task-notification>` system-reminder 触发主线新 turn
-4. 主线在新 turn 处理：从 `<output-file>` 路径 read stdout，按通道 schema parse 结果
+4. 主线在新 turn 处理：从 `<output-file>` 路径 read stdout，`JSON.parse(stdout).text`（通道 A）/ `--progress` 行（通道 B）
 5. **必须等所有相关 task 都收到通知**才进入下一阶段（按 task-id 计数已收齐）
 
 ⛔ **禁止**：
@@ -167,7 +152,7 @@ Bash({
 - {{BACKEND_PRIMARY}}：使用分析提示词，输出技术可行性、方案、风险
 - {{FRONTEND_PRIMARY}}：使用分析提示词，输出 UI 可行性、方案、体验
 
-用 `TaskOutput` 等待结果。**📌 保存 SESSION_ID**（`CODEX_SESSION` 和 `GEMINI_SESSION`）。
+事件驱动等待 task-notification（**不调 TaskOutput**），Read 各自 stdout 取结果。**📌 保存 SESSION_ID**（`CODEX_SESSION` 和 `GEMINI_SESSION`）。
 
 **务必遵循上方 `多模型调用规范` 的 `重要` 指示**
 
@@ -181,7 +166,7 @@ Bash({
 - {{BACKEND_PRIMARY}}：使用规划提示词 + `resume $CODEX_SESSION`，输出后端架构
 - {{FRONTEND_PRIMARY}}：使用规划提示词 + `resume $GEMINI_SESSION`，输出前端架构
 
-用 `TaskOutput` 等待结果。
+事件驱动等待 task-notification（**不调 TaskOutput**），Read 各自 stdout 取结果。
 
 **务必遵循上方 `多模型调用规范` 的 `重要` 指示**
 
@@ -203,7 +188,7 @@ Bash({
 - {{BACKEND_PRIMARY}}：使用审查提示词，关注安全、性能、错误处理
 - {{FRONTEND_PRIMARY}}：使用审查提示词，关注可访问性、设计一致性
 
-用 `TaskOutput` 等待结果。整合审查意见，用户确认后执行优化。
+事件驱动等待 task-notification（**不调 TaskOutput**）。整合审查意见，用户确认后执行优化。
 
 **务必遵循上方 `多模型调用规范` 的 `重要` 指示**
 

package/templates/hooks/ccg-loop-detector.cjs

@@ -16,7 +16,16 @@
 //     Repeated near-identical prompts within a short window are a strong loop
 //     indicator regardless of what the orchestrator is doing internally.
 //
-// State file: <workdir>/.ccg/.turns.json   (kept tiny: last 5 turns only)
+// State file: <os.tmpdir()>/ccg-turns-<session_id>.json  (kept tiny: last 5
+//   turns only). Keyed by session_id — DELIBERATELY NOT written into the
+//   project tree. Rationale: the turn window is a per-session, sub-10-minute
+//   signal with zero coupling to git / workspace / project identity, so it
+//   belongs in the OS temp dir — the same model already used by
+//   ccg-statusline.js and ccg-context-monitor.js. An earlier version wrote
+//   <cwd>/.ccg/.turns.json, whose unconditional mkdirSync seeded a stray .ccg
+//   directory in EVERY cwd (subdirs, monorepo packages, non-CCG projects) on
+//   every prompt — that pollution (and the project start-up failures it caused)
+//   is the bug this version fixes.
 //
 // Performance budget: <50 ms hot path. Hook fires every UserPromptSubmit; if
 // anything throws we exit 0 silently so the user message is never blocked.
@@ -25,8 +34,9 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
 
-const STATE_FILE = path.join('.ccg', '.turns.json');
 const MAX_TURNS = 5;             // sliding window
 const LOOP_THRESHOLD = 3;        // 3 similar in a row → loop
 // Bound the state-file read. .turns.json holds at most MAX_TURNS rows of
@@ -143,9 +153,29 @@ function composeWarning(loop) {
   ].join('\n');
 }
 
+// Derive a filesystem-safe key for the per-session state file.
+//   - Prefer Claude Code's session_id (UserPromptSubmit payloads supply it —
+//     see ccg-context-monitor.js `data.session_id` / ccg-session-state.cjs).
+//   - Reject any session_id containing a path separator or `..` so it can never
+//     escape os.tmpdir() (mirrors ccg-statusline.js / ccg-context-monitor.js).
+//   - Fall back to a stable sha256 of cwd when session_id is absent/unsafe, so
+//     loop detection keeps working without ever touching the project tree.
+function resolveStateKey(input) {
+  const sid = input && typeof input.session_id === 'string' ? input.session_id : '';
+  if (sid && !/[/\\]|\.\./.test(sid)) return sid;
+  const cwd = input && typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd();
+  return `cwd-${crypto.createHash('sha256').update(cwd).digest('hex').slice(0, 16)}`;
+}
+
+// Absolute path to the session-scoped turn-history file, always under the OS
+// temp dir — never under the project working directory.
+function resolveStatePath(input) {
+  return path.join(os.tmpdir(), `ccg-turns-${resolveStateKey(input)}.json`);
+}
+
 function readInput() {
-  // SessionStart / UserPromptSubmit pass JSON on stdin. We only need .prompt
-  // and .cwd. Failing to read is fine — we exit 0 silently.
+  // SessionStart / UserPromptSubmit pass JSON on stdin. We only need .prompt,
+  // .session_id and .cwd. Failing to read is fine — we exit 0 silently.
   let raw = '';
   try {
     raw = fs.readFileSync(0, 'utf-8');
@@ -174,10 +204,9 @@ function main() {
     return;
   }
 
-  // CCG state lives under the project root. Use the cwd Claude Code passed in;
-  // fall back to process.cwd() (which Claude Code sets for the hook anyway).
-  const cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd();
-  const statePath = path.join(cwd, STATE_FILE);
+  // Loop state is a per-session sliding window. It lives in os.tmpdir() keyed by
+  // session_id, NOT in the project tree — see resolveStatePath + file header.
+  const statePath = resolveStatePath(input);
 
   const fp = fingerprint(prompt);
   if (!fp) {
@@ -224,6 +253,8 @@ module.exports = {
   jaccard,
   detectLoop,
   composeWarning,
+  resolveStateKey,
+  resolveStatePath,
   // Constants exported so tests can document the contract.
   LOOP_THRESHOLD,
   WINDOW_MS,

package/templates/hooks/ccg-statusline.js

@@ -41,6 +41,141 @@ function readGitBranch(dir) {
   }
 }
 
+// --- project state (.context/STATE.json, P1-4 task-store projection) --------
+
+// Hard bound on STATE.json size — the projection is a handful of fields, so
+// anything bigger than 16KB is corrupt/abusive and gets ignored.
+const STATE_MAX_BYTES = 16384;
+// Staleness guard: a crashed orchestrator can leave active_phase behind.
+// After 24h without an update the segment silently disappears.
+const STATE_STALE_MS = 24 * 60 * 60 * 1000;
+// Lifecycle words worth showing next to "Phase N" (in-flight scenes only).
+const STATE_LIFECYCLE_WORDS = new Set([
+  'discussing', 'planning', 'executing', 'verifying', 'fixing', 'reviewing',
+]);
+
+/**
+ * Path-normalized directory equality. Windows paths are case-insensitive
+ * (C:\Users\X vs c:\users\x), so the $HOME stop guard must not compare raw
+ * strings.
+ */
+function isSameDir(a, b) {
+  if (!a || !b) return false;
+  try {
+    const na = path.resolve(a);
+    const nb = path.resolve(b);
+    if (process.platform === 'win32') return na.toLowerCase() === nb.toLowerCase();
+    return na === nb;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk upward from `dir` (max 10 levels, stopping at home / fs root) looking
+ * for `.context/STATE.json`. Returns the absolute path or null.
+ */
+function findProjectStateFile(dir) {
+  if (!dir || typeof dir !== 'string') return null;
+  try {
+    let cur = path.resolve(dir);
+    const home = os.homedir();
+    for (let i = 0; i < 10; i++) {
+      const candidate = path.join(cur, '.context', 'STATE.json');
+      if (fs.existsSync(candidate)) return candidate;
+      if (isSameDir(cur, home)) return null;
+      const parent = path.dirname(cur);
+      if (parent === cur) return null; // fs root
+      cur = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read + parse the nearest STATE.json. Returns the parsed object or null on
+ * any failure (missing, oversized, corrupt JSON, non-object). Never throws.
+ */
+function readProjectState(dir) {
+  try {
+    const file = findProjectStateFile(dir);
+    if (!file) return null;
+    const st = fs.statSync(file);
+    if (!st.isFile() || st.size > STATE_MAX_BYTES) return null;
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    // Frozen projection schema v1 — a foreign/newer schema version degrades
+    // cleanly to "no segment" rather than misrendering unknown semantics.
+    if (parsed.schema_version !== undefined && parsed.schema_version !== 1) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function isValidProgress(p) {
+  return !!p && typeof p === 'object'
+    && typeof p.total_phases === 'number' && p.total_phases > 0
+    && typeof p.completed_phases === 'number' && p.completed_phases >= 0;
+}
+
+function truncateAction(s, max) {
+  return s.length <= max ? s : s.slice(0, max) + '…';
+}
+
+/**
+ * Render the STATE.json segment ('' when nothing to show). Scene priority
+ * (GSD statusline contract):
+ *   1. active_phase set        → "Phase <n>[ <lifecycle-word>]"  (in-flight wins)
+ *   2. next_action set         → "next <cmd ≤40 chars>"          (idle recommendation)
+ *   3. progress 100% complete  → "✓ phases done"
+ *   4. otherwise               → ''  (output stays byte-identical to pre-P1-4)
+ * Scenes 1-2 get a "[done/total] " prefix when progress is valid.
+ * Staleness: updated_at missing/unparseable/older than 24h → ''.
+ */
+function formatStateSegment(state, nowMs) {
+  if (!state || typeof state !== 'object') return '';
+  try {
+    const ts = typeof state.updated_at === 'string' ? Date.parse(state.updated_at) : NaN;
+    if (!Number.isFinite(ts)) return '';
+    if (nowMs - ts > STATE_STALE_MS) return '';
+
+    const progressOk = isValidProgress(state.progress);
+    const prefix = progressOk
+      ? `[${state.progress.completed_phases}/${state.progress.total_phases}] `
+      : '';
+
+    // Scene 1: orchestrator in flight — a "next" recommendation would be
+    // misleading mid-run, so this scene always wins.
+    if (typeof state.active_phase === 'string' && state.active_phase.trim()) {
+      let seg = `Phase ${state.active_phase.trim()}`;
+      if (typeof state.status === 'string' && STATE_LIFECYCLE_WORDS.has(state.status.trim())) {
+        seg += ` ${state.status.trim()}`;
+      }
+      return prefix + seg;
+    }
+
+    // Scene 2: idle with a recommended next command.
+    if (typeof state.next_action === 'string' && state.next_action.trim()) {
+      return `${prefix}next ${truncateAction(state.next_action.trim(), 40)}`;
+    }
+
+    // Scene 3: everything done.
+    if (progressOk) {
+      const p = state.progress;
+      if (p.percent === 100 || p.completed_phases === p.total_phases) {
+        return '✓ phases done';
+      }
+    }
+
+    return '';
+  } catch {
+    return '';
+  }
+}
+
 // --- core renderer ----------------------------------------------------------
 
 function runStatusline() {
@@ -120,13 +255,18 @@ function runStatusline() {
       }
 
       // Compose CCG-style status line:
-      //   <model> | <ctx> | <branch> | <sid4>
+      //   <model> | <ctx> | <branch> | <state> | <sid4>
       const branch = readGitBranch(dir);
+      // P1-4: project lifecycle segment from .context/STATE.json (task-store
+      // projection). '' when no STATE.json — output then stays byte-identical
+      // to the pre-P1-4 statusline (backward-compat contract, test-locked).
+      const stateSeg = formatStateSegment(readProjectState(dir), Date.now());
       const sid4 = session && session.length >= 4 ? session.slice(-4) : '';
 
       const segments = [`\x1b[2m${model}\x1b[0m`];
       if (ctx) segments.push(ctx.trim());
       if (branch) segments.push(`\x1b[36m${branch}\x1b[0m`);
+      if (stateSeg) segments.push(`\x1b[35m${stateSeg}\x1b[0m`);
       if (sid4) segments.push(`\x1b[2m#${sid4}\x1b[0m`);
 
       process.stdout.write(segments.join(' │ '));
@@ -137,6 +277,6 @@ function runStatusline() {
 }
 
 // Export helpers for unit tests. Harmless when run as a script.
-module.exports = { readGitBranch };
+module.exports = { readGitBranch, findProjectStateFile, readProjectState, formatStateSegment };
 
 if (require.main === module) runStatusline();