feat(harness): FAQ Batch A IMP-B-01/02 — CI stderr 与 task_validate

.github/pull_request_template.md

@@ -0,0 +1,36 @@
+## Summary
+
+<!-- 行为变更一句话；若涉 api/ 契约，写明影响面 -->
+
+---
+
+## 自检验收清单（合并前须满足）
+
+> **Ink 轨**：高敏书面复检见 `docs/harness/reviews/` 或 `docs/tasks/reinspect_results/`；**本清单不替代** `human_gate_check`。
+
+- [ ] 本地：`pytest tests -m "not intent_eval and not intent_benchmark"` 通过
+- [ ] PR 上 **pytest** + **tech-graph** + **tech-graph-contract**（若触达）Required 全绿
+- [ ] 若改 `api/` / SSE / 契约：已更新 task **§行为变更 Delta** + `_manifest` / 契约 fixture（**同 PR**）
+- [ ] 若改结构图：已更新 `.ai.md` 且 `graph_export --check` 通过
+- [ ] 高敏变更（`api/`、`test_strategy: required`）：**独立复检** 已落盘或本 PR 链 `reinspect_results/`
+
+### Blocking 提示（须人判断 · 非 PR 关键词过闸）
+
+| 类型 | 例 | 须 |
+| --- | --- | --- |
+| **对外契约** | 改响应字段、SSE 事件名、路由 | task Delta + 50 + 契约 CI |
+| **运行锚点** | 改 env 名、端点、部署前提 | manifest + 任务单声明 |
+| **主依赖** | 主框架大版本、copyleft 新依赖 | 人读 changelog/LICENSE + 扩大回归 |
+
+---
+
+## Test plan
+
+- [ ] （作者填写：关键手动场景或 pytest 路径）
+
+---
+
+## 关联
+
+- Task：`docs/tasks/active/` 或 `done/` 路径
+- 审查：`docs/harness/reviews/`（如有）

.github/workflows/tech-graph.yml

@@ -41,3 +41,58 @@ jobs:
 
       - name: Tech graph token estimate (Gate A appendix)
         run: python tools/tech_graph_token_estimate.py --json
+
+  task_validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Detect task file changes
+        id: tasks
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE="${{ github.base_ref }}"
+            git fetch origin "$BASE" --depth=1 2>/dev/null || true
+            CHANGED="$(git diff --name-only "origin/${BASE}...HEAD" -- 'docs/tasks/' || true)"
+          else
+            CHANGED="$(git diff --name-only HEAD~1 HEAD -- 'docs/tasks/' || true)"
+          fi
+          if [ -n "$CHANGED" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "Task paths changed:"
+            echo "$CHANGED"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "No docs/tasks/ changes; skipping task_validate."
+          fi
+
+      - name: Harness task validate (changed active tasks)
+        if: steps.tasks.outputs.changed == 'true'
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE="${{ github.base_ref }}"
+            FILES="$(git diff --name-only "origin/${BASE}...HEAD" -- 'docs/tasks/active/*.md' || true)"
+          else
+            FILES="$(git diff --name-only HEAD~1 HEAD -- 'docs/tasks/active/*.md' || true)"
+          fi
+          if [ -z "$FILES" ]; then
+            echo "No active task .md changes."
+            exit 0
+          fi
+          for f in $FILES; do
+            if [[ "$f" == *_AGENT_PROMPT* ]]; then
+              continue
+            fi
+            echo "Validating $f"
+            python tools/harness_task_validate.py "$f"
+          done

docs/harness/README.md

@@ -17,6 +17,9 @@
 | commit / 关账 | `HANDOFF_AUTO_COMMIT`、`HANDOFF_CLOSE_TRACE` |
 | task 字段 | `HARNESS_V2_PLAN.md` §5 |
 | 流程 | `SDD_HAT_FLOW.md` |
+| **FAQ 改进 · 09 PLAN** | [`prompts/PROMPT_FAQ改进_09PLAN_理解_v1_zh.md`](prompts/PROMPT_FAQ改进_09PLAN_理解_v1_zh.md) |
+| **冷/温/热 术语** | [`guides/GUIDE_冷温热层_对内术语_v1_zh.md`](guides/GUIDE_冷温热层_对内术语_v1_zh.md) |
+| **manifest/contract CI 红** | [`guides/RUNBOOK_graph_contract_ci_red_v1.md`](guides/RUNBOOK_graph_contract_ci_red_v1.md) |
 | 新 invoke | `invokes/` |
 | **Harness 裁决共识（已接受）** | [`../diary/2026-05-22-harness-evaluation-improvement-response.md`](../diary/2026-05-22-harness-evaluation-improvement-response.md) **§九** |
 

docs/harness/guides/GUIDE_冷温热层_对内术语_v1_zh.md

@@ -0,0 +1,45 @@
+# 冷 / 温 / 热 · 对内术语（FAQ 纠偏）
+
+| 项 | 内容 |
+| --- | --- |
+| **用途** | 22/10 帽、task 编写、Agent 对话 — **纠正公众稿读者常见误读** |
+| **公众真值** | 卷三 §11.2.1（已发表）；本文件 **不** 另起定义 |
+| **来源** | FAQ F1 + [`SUMMARY`](../../../../ai_coding_governance/narrative/reviews/SUMMARY_三卷读者FAQ_完整结论_20260530_v1_zh.md) §2 |
+
+---
+
+## 1. 对照表（复制进 review 时可摘一行）
+
+| 层 | ✅ 正文真义 | ❌ 常见误读（勿用） |
+| --- | --- | --- |
+| **冷层** | **结构地图** = 卷二技术图谱；task **图谱入口** | 「框架、数据库、基础设施层」 |
+| **温层** | **协作轨迹** = 任务单 + 书面签收 + 关账摘要 | 「API 签名、模块边界、契约层」 |
+| **热层** | **运行时事件记忆**（远期；日常不必做） | 「函数内部、UI 样式、热代码」 |
+
+**一句**：冷 = **改哪里（地图）**；温 = **谁审、怎么关账（轨迹）**；热 = **线上事件网（远期）** — **不是** 按变更频率给模块贴标签。
+
+---
+
+## 2. 与后端落地的关系
+
+| 读者误读导致的错误做法 | Ink 实际 |
+| --- | --- |
+| 在 graph 节点上标 cold/warm/hot | **不做**；图谱管流程与模块边界 |
+| 温层 = 函数签名 CI | **契约** 靠 `_manifest` + `contract_check` + pytest |
+| 冷层 = README/env  alone | env/端点 是 **manifest 锚点**，属于 **Verify**；冷层叙事仍指 **结构地图** |
+
+---
+
+## 3. Agent 自检（开工前答三问）
+
+1. 本轮 **图谱入口** 指向哪张 **子图/主图**？（冷层落点）  
+2. 本轮 **任务单 + 审查落盘** 是否齐全？（温层落点）  
+3. 是否误把「改 API 签名」说成「改温层」？→ 应说 **对外契约变更** + Delta + 50。
+
+---
+
+## 修订记录
+
+| 版本 | 日期 | 说明 |
+| --- | --- | --- |
+| v1.0 | 2026-05-30 | IMP-B-20 · FAQ 纠偏 |

docs/harness/guides/RUNBOOK_graph_contract_ci_red_v1.md

@@ -0,0 +1,67 @@
+# Runbook · 图谱 manifest / contract CI 红字
+
+> **用途**：开发者或 22 帽审查时，对照 CI stderr 三段式（位置 · 文档声明 · 当前代码 · 下一步）快速修复。  
+> **关联**：IMP-B-01 · FAQ F20 卷四主失败分支 · `tech-graph.yml` / `tech-graph-contract.yml`
+
+---
+
+## 1. 何时打开本文
+
+| CI job | 命令 | 典型触发 |
+|--------|------|----------|
+| `manifest_check` | `python tools/tech_graph_manifest_check.py` | 改 `api/`、`supabase/sql/` 未同步 `_manifest.json` |
+| `contract_check` | `python tools/tech_graph_contract_check.py` | 改 SSE 事件/字段未同步 `_contract_manifest.json` |
+| `graph export --check` | `python tools/tech_graph_graph_export.py --check` | 改 `.ai.md` 未 export `graph.json` |
+
+stderr 首行以 `❌` 开头，每条 drift 含 **位置 / 文档声明 / 当前代码**。
+
+---
+
+## 2. 修复路径（路径 A · 推荐）
+
+1. 在 **active task** 的 `§行为变更（Delta）` 写明 ADDED/MODIFIED（触达 `api/` 时 `test_strategy: required` + 50 落盘）。  
+2. **同 PR** 更新：
+   - `_manifest.json`（端点 / RPC / 表 / env / anchors）
+   - `_contract_manifest.json`（SSE 契约，若涉 Unified Chat）
+   - 受影响 `docs/_tech_graph/*.ai.md` → `python tools/tech_graph_graph_export.py`
+3. 本地跑与 CI 相同命令（见 stderr 末尾）。  
+4. `pytest tests -m "not intent_eval and not intent_benchmark"` 绿后再 push。
+
+**禁止**：merge 后再开单独 PR 只改图谱（FAQ 已拒）。
+
+---
+
+## 3. 修复路径（路径 B · 误改）
+
+```bash
+git checkout -- api/   # 或 git revert 指定 commit
+python tools/tech_graph_manifest_check.py
+python tools/tech_graph_contract_check.py
+```
+
+确认 stderr 无 `❌` 后再 push。
+
+---
+
+## 4. 常见 drift 对照
+
+| stderr 位置前缀 | 文档侧 | 代码侧 | 下一步 |
+|-----------------|--------|--------|--------|
+| `manifest.endpoints` | `_manifest.json` endpoints | `api/index.py` 路由装饰器 | 补/删 manifest 条目或回滚路由 |
+| `manifest.supabase.tables` | manifest tables | `.table("…")` / SQL CREATE | 同步表名清单 |
+| `contract.sse.*` | `_contract_manifest.json` | `api/unified_chat.py` 等 | 同步 allowed_events / payload keys |
+| `manifest.anchors` | anchors path+symbol | 源文件 def/class | 修正锚点或符号名 |
+
+---
+
+## 5. 22 帽审查粘贴
+
+CI 日志中 `--- 问题 N/M ---` 至 `Runbook:` 行可直接贴入 `reviews/` R1，无需重写。
+
+---
+
+## 修订记录
+
+| 版本 | 日期 | 说明 |
+| --- | --- | --- |
+| v1.0 | 2026-05-31 | IMP-B-01 初版；链 tech_graph_ci_stderr |

docs/harness/prompts/PROMPT_FAQ改进_09PLAN_理解_v1_zh.md

@@ -0,0 +1,97 @@
+# Prompt · 理解 FAQ 改进方案（09 PLAN）并执行 Batch A
+
+> **用途**：后端 Agent **开工前** 读本文 + 链内文档，理解「三卷发表后读者 FAQ → Ink 后端改进项」全貌，再动 `api/` / CI / Harness。  
+> **真值规划**：治理仓 [`ai_coding_governance/09_PLAN_Ink后端改进方案_可推广_v1_zh.md`](../../../../ai_coding_governance/09_PLAN_Ink后端改进方案_可推广_v1_zh.md)  
+> **合成结论**：[`SUMMARY_三卷读者FAQ_完整结论_20260530_v1_zh.md`](../../../../ai_coding_governance/narrative/reviews/SUMMARY_三卷读者FAQ_完整结论_20260530_v1_zh.md)
+
+---
+
+## 你的角色
+
+你是 **Ink 后端（ai-ink-brain-api-python）** 执行 Agent。当前任务类型：**FAQ 驱动的工程补齐**（非重写方法论）。  
+**Open Folder**：本仓根。跨仓只读治理仓 `ai_coding_governance/narrative/reviews/` 与 `09_PLAN`，**禁止**改工作区 `Projects/docs/harness/`。
+
+---
+
+## 必须先建立的结论（30 秒）
+
+1. **方法论不 redesign**：Harness 三支柱、`.ai.md`→export 双轨图谱、manifest/contract CI、`human_gate` + 50 — **保持不变**。  
+2. **读者误读要纠**：冷/温/热 ≠ 架构/契约/实现 → 见本仓 [`../guides/GUIDE_冷温热层_对内术语_v1_zh.md`](../guides/GUIDE_冷温热层_对内术语_v1_zh.md)。  
+3. **本批要做**：降低合并摩擦 + CI 红字可读 + 模板可复制 — **IMP-B Batch A**（见下）。  
+4. **明确不做**：`graph.auto.json` 全仓扫描、PR `/approve` 唯一合闸、维护成本归零、merge 模型 KPI。
+
+---
+
+## 阅读顺序（按序打开）
+
+| 序 | 文档 | 目的 |
+|----|------|------|
+| 1 | 本仓 [`AGENTS.md`](../../../AGENTS.md) | 地图与禁止项 |
+| 2 | [`docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) | 契约/目录/安全 |
+| 3 | 治理仓 **SUMMARY** §2、§5、§10 | FAQ 合成结论与五条原则 |
+| 4 | 治理仓 **09_PLAN** §1～§3 | 缺口、IMP-B 全表、批次 A/B/C |
+| 5 | 本仓 **active task** | [`docs/tasks/active/task_backend_improve_batch_a_p0_v1.md`](../../tasks/active/task_backend_improve_batch_a_p0_v1.md)（**draft** · Batch A） |
+| 6 | 动 CI/契约时：[`GUIDE_续卷编写_Ink后端真值对照_v1_zh.md`](../../../../ai_coding_governance/narrative/GUIDE_续卷编写_Ink后端真值对照_v1_zh.md) §3 | workflow/命令真值 |
+
+**不必读**：`docs/diary/` 全文、`invokes/` 扁平扫描、Public 公众稿粘贴版。
+
+---
+
+## FAQ → 后端改进项（IMP-B 全表 · 状态以 task 为准）
+
+### Batch A · P0（优先）
+
+| ID | 做什么 | 交付物 |
+|----|--------|--------|
+| IMP-B-01 | manifest/contract CI **三段式 stderr** + Runbook | `tools/tech_graph_*_check.py` · `docs/harness/guides/RUNBOOK_graph_contract_ci_red_v1.md` |
+| IMP-B-02 | 改 task 时 CI 跑 `task_validate` | `verify-fast.yml` 或 `tech-graph.yml` |
+| IMP-B-10 | Ink 轨 **PR 模板** | `.github/pull_request_template.md` |
+| IMP-B-11 | **22 帽 Blocking 表** | `prompts/hats/22-task-audit.md` §Blocking |
+| IMP-B-20 | **冷/温/热术语卡** | `docs/harness/guides/GUIDE_冷温热层_对内术语_v1_zh.md` |
+
+### Batch B · P1
+
+IMP-B-03 L2 manifest SPEC 关账 · IMP-B-04 领域 Linter · IMP-B-12 Test plan 分层 · IMP-B-13 存量 task 抽样 · IMP-B-21 合并入口图 · IMP-B-30/31 failure-cases + 复盘模板
+
+### Batch C · P2
+
+IMP-B-05 增量 manifest · IMP-B-14 Delta→spec · IMP-B-22 卷四对内样例 PR
+
+---
+
+## 执行纪律（FAQ 约束）
+
+| 约束 | 要求 |
+|------|------|
+| 成本 | 新流程 **不** 使稳态额外耗时 >15%；不加专职岗 |
+| 高敏 | 动 `api/` → `test_strategy: required` + **50 落盘**；小团队可角色兼任，**不可删步骤** |
+| 合并 | **同 PR** 提交代码 + manifest/`.ai.md`（若触达）；禁止 merge 后 bot 单独改图 |
+| 签收 | 闸在 **`reviews/` / `reinspect_results/` + human_gate**；PR 模板 **辅助**，不替代 |
+| 测试 | 合并前：`pytest tests -m "not intent_eval and not intent_benchmark"` |
+
+---
+
+## 开工检查清单
+
+- [ ] 已读 active task 的 **非范围** 与 **验收**  
+- [ ] 改动范围 **仅** task 所列 IMP-ID  
+- [ ] 未引入 FAQ **已拒绝** 方案（见 SUMMARY §3 拒绝列）  
+- [ ] 若改 CI：本地或 PR 上 **故意红一次** 验证 stderr/Runbook  
+- [ ] 关账：22 review 落盘 + pytest 绿 + task → done 流程
+
+---
+
+## 输出要求
+
+1. **变更摘要**：按 IMP-ID 列出文件与行为。  
+2. **未做项**：Batch A 中本轮 **刻意不做** 的 ID 及原因。  
+3. **公众稿**：**不** 把本 Prompt 或 governance reviews 整段复制进 PR/对外仓库。  
+4. **图谱**：若动 `api/` 或锚点，同步 `_manifest` / 契约 fixture / `.ai.md`（同 PR）。
+
+---
+
+## 修订记录
+
+| 版本 | 日期 | 说明 |
+| --- | --- | --- |
+| v1.0 | 2026-05-30 | FAQ Batch A kickoff；链 09_PLAN + SUMMARY |

docs/harness/prompts/hats/22-task-audit.md

@@ -40,6 +40,20 @@
 | 1 | 验收含：`PR 上 pytest workflow 全绿` + 本地等价命令 | ☐ |
 | 2 | 40 自检 / PR 链接可核对（终轮 22 不得无证明签收） | ☐ |
 
+### §Blocking · 高敏须人判断（FAQ F8 · IMP-B-11）
+
+> **非** PR `/approve` 过闸；**是** 22/50 审查时对照。小团队可 **角色兼任**，**不可省略步骤**。
+
+| 类型 | 例 | 22 须确认 |
+| --- | --- | --- |
+| **对外契约** | 改 `api/` 响应/SSE/路由 | task **Delta** + **50 落盘**（`required`） |
+| **运行锚点** | 改 `_manifest` env/端点/部署前提 | 与 **manifest_check** 一致；task 已声明 |
+| **主依赖** | FastAPI 等大版本、GPL 类新依赖 | changelog/LICENSE **人读**；回归范围足够 |
+
+| # | 检查项 | 通过 |
+|---|--------|------|
+| 1 | 若触达 Blocking 任一行 → 上表已核对，缺项 **阻塞** | ☐ |
+
 ### §3.3 独立复检（50）触发
 
 | 变更类型 | `test_strategy` | 50 |