docs: integrate systemic issue analysis requirements

2026-09-23 02:42:58 +00:00
parent 5c35f32e22 380584b86b
commit 958dd44fee
6 changed files with 101 additions and 2 deletions
@@ -27,3 +27,9 @@ CURRENT 是带时间的活跃协调快照；Git/机器状态用于核验实际
 ## Herdr v1.2 局部修订

 用户已授权采纳经研究修正的资源分工与自动审批。Herdr roster 的角色/额度/客户端参数由 `herdr-v1.2` 取代旧路由，仅在明确使用 Herdr 时激活，不扩展通用会话工作流。具体来源、验证与生效集成见[本轮任务](../archive/ops/2026-09-21-herdr-orchestration-v12.md)。已通过 dev 合并提交 `8c5e3477585fe27a485343dac97a670d95cf8905` 生效；profile/dry-run、入口保护和 Kimi 原子计数有隔离验收，真实 Herdr pane 启动未在本轮执行，不将其记为已实测。
+
+## 系统问题分析局部修订
+
+修订 ID：`systemic-issue-analysis-2026-09-23-r1`；owner：`Codex`；state：`approved`（尚未合入 dev）；工具能力：`manual`。用户明确要求将“由个案追查同类根因、潜在问题，研究并提出方案”加入规范，授权与验证见 [任务记录](./short-term/2026-09-23-systemic-issue-analysis.md)。
+
+核心行为唯一来源为 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求)，验证范围由 [验证契约](./2026-09-21-validation-contract.md#问题修复的回归范围) 定义，[分析模板](./templates/audit-note.md) 承载证据。客户端继续引用统一入口。生效条件为本修订经受控集成进入 dev，并在任务记录登记实际集成提交；当前任务 worktree 中的修改不代表全仓已生效，不新增业务实施或环境操作授权。
@@ -15,6 +15,12 @@

 多类变更取并集。按 [模块开发标准](../system-design/2026-09-20-module-development-standards.md) 追加边界与 registry parity 等范围门禁。开发阶段可用 stub；交付验收不能冒充真实执行。纯文档无需产品 PI 或全量 Go，也不为形式重建服务。

+## 问题修复的回归范围
+
+Bug/系统问题修复先按 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求) 确定问题类别和影响范围，再从上表选择验证层级。验收须包含：原始复现案例；通过同一机制的其他输入、措辞或入口；相关边界/异常路径；应保持不变的正常行为。场景按实际因果链选择，不机械穷举；不适用或未覆盖的项记录理由与风险。
+
+验证机制和预期行为，不以硬编码原句、固定回复文本或单个样例通过代替回归。能在修复前复现失败的场景记录修复前后对照；不能复现时说明证据限制。报告逐项区分通过、失败、未运行与待验证；只提供分析/方案时列出验收设计，不声称已经运行或修复。
+
 ## 产品 PI 基线与精确追加

 优先入口：`./scripts/run-nightly-real-pi.sh`。调用前核验并从获授权配置提供（不在命令/报告贴凭证值）：
@@ -12,6 +12,7 @@

 | owner | task | branch | worktree | mutex | status |
 |---|---|---|---|---|---|
+| Codex | systemic-issue-analysis-2026-09-23 | feature/systemic-issue-analysis-2026-09-23 | .worktrees/systemic-issue-analysis-2026-09-23 | systemic-issue-analysis-docs | blocked |
 | Codex | modular-contract-standard-2026-09-22 | feature/modular-contract-standard-2026-09-22 | .worktrees/modular-contract-standard-2026-09-22 | modular-contract-docs | done |
 | Codex | herdr-orchestration-v12 | feature/herdr-orchestration-v12 | .worktrees/herdr-orchestration-v12 | herdr-policy+scripts | done |
 | Codex | 2026-09-21-agent-governance-implementation | feature/agent-governance-implementation | .worktrees/agent-governance-implementation | agent-governance | done |
@@ -0,0 +1,59 @@
+---
+title: "Bug 与系统问题的同类根因分析规范"
+task_id: systemic-issue-analysis-2026-09-23
+status: blocked
+created: 2026-09-23
+updated: 2026-09-23
+owner: Codex
+task_type: implementation
+task_tier: small
+policy_revision: "agent-governance-2026-09-21-r1 @ 5c35f32e225a482d5838e6d771778fb754f75506"
+branch: feature/systemic-issue-analysis-2026-09-23
+worktree: .worktrees/systemic-issue-analysis-2026-09-23
+base_dev_sha: "5c35f32e225a482d5838e6d771778fb754f75506"
+write_scope: ["AGENTS.md", ".doc/ops/templates/audit-note.md", ".doc/ops/2026-09-21-validation-contract.md", ".doc/ops/2026-09-21-policy-registry.md", ".doc/ops/short-term/2026-09-23-systemic-issue-analysis.md", ".doc/ops/CURRENT.md"]
+allowed_environments: []
+mutex: "认领路径的 agentctl path 租约；提交另持 git:index"
+review_state: approved
+integration_state: pending
+deployment: not_required
+cleanup: pending
+cleanup_owner: "owner 退出后的独立集成/维护执行者"
+cleanup_trigger: "dev 集成与证据保存完成且 owner 退出后复查"
+remote_sync: not_requested
+---
+
+# Bug 与系统问题的同类根因分析规范
+
+## 用户目标与授权
+
+2026-09-23 本会话用户要求“规范中加入一些要求”，报告 bug 或系统问题后应尝试找到这类问题的原因、潜在问题，思考研究并提出方案；以“今天天气怎么样”的异常回复作为示例，强调不能只改一个提问或细节。这是规范修改授权，天气问题只是说明，不构成产品缺陷诊断或业务修复任务。
+
+交付终点：完成统一规范、配套模板与验证要求并检查一致性；在仓库门禁允许时本地集成。禁止修改业务代码、产品提示词、运行环境、.env，禁止推送或处理他人未提交现场。
+
+## 当前证据与变更
+
+- 已阅读 AGENTS、PROJECT、CURRENT、文档地图、worktree 操作规范、验证契约、规范登记和收口清单。
+- 当前已有授权/验证规则，但没有从个案归纳共用机制、横向排查和形成方案的明确要求；分析模板只有现象和根因占位。
+- AGENTS 新增四步要求和天气示例，限制有证据关联的扩展，区分研究/实施授权。
+- 分析模板补充事实、同类范围、证据分级与方案验收；验证契约补充问题类别回归；规范登记保留 approved/manual，待真实集成生效。
+- CODEX、CLAUDE、GEMINI、ANTIGRAVITY、KIMI 与四个 Cursor 规则均转发统一入口，无需另复制规则。
+
+## 验证计划与结果
+
+纯文档：检查 diff、修改文档的相对链接及新增锚点、状态和客户端入口一致性；人工按天气示例、无法复现、仅个案证据、已授权修复四种情形检查规则是否可执行。不运行产品测试，不声称验证过未来 Agent 行为。
+
+- 基于 base_dev_sha 的工作区差异：`git diff --check` 退出 0；人工审阅全部规范差异通过。
+- Python pathlib/re 扫描上述 5 个修改文档的 Markdown 相对链接：`PASS: 5 changed documents; 34 relative links; new anchors resolve`；目标存在，新增两个锚点可解析。
+- 人工情景审阅通过：天气示例从机制出发而非预设根因；无法复现须保留假设/缺口及验证方法；仅个案须给范围依据；已授权修复可继续，不新增重复审批。
+- 客户端入口一致性通过：所有已读入口仍引用 AGENTS/统一验证契约，无重复新规则。
+- 本次只验证文档结构与要求一致性，未执行产品测试；输出无业务内容或凭证，无需脱敏。review_state=approved 指本轮自审，不代表独立评审。
+- 文档修改与验证已完成；status=blocked 仅因 dev 集成的干净工作区前置条件尚未满足。
+
+## 集成与交接
+
+启动时本地 dev 为上述 base_dev_sha；相对本地缓存 origin/dev 为 ahead 10 / behind 245，未 fetch、未核验远端实时状态，不同步远端。
+
+主目录已有未跟踪 `.codegraph/`；操作规范要求主目录干净，agentctl integrate 在推进 dev 前调用 clean_source（包含未跟踪文件），因此当前不满足集成前置条件。不移动、删除或隐藏既有文件，不绕过门禁。待该现场由其 owner 处理后，从最新 dev 创建候选、重读规范差异、验证并受控集成；更新本记录及规范登记的生效提交/状态。
+
+任务与 worktree 保留供集成，不清理。影响限于工程 Agent 的问题处理要求；FEATURE-MATRIX、发布门禁和产品运行版本无变化。
@@ -22,11 +22,25 @@ severity: medium

 ## 现象

-（可观测症状）
+（预期/实际行为、原始案例、触发条件、环境与复现结果）

 ## 根因分析

-（证据路径、代码引用）
+Bug/系统问题按 [AGENTS 分析要求](../../../AGENTS.md#bug-与系统问题的分析要求) 填写；其他审查按实际范围裁剪。
+
+（问题类别、因果链、共用机制、现有防护为何未发现；证据路径/代码引用；区分已证实、假设和证据缺口）
+
+## 同类问题与影响范围
+
+| 关联场景/入口 | 与原例共用的机制 | 检查方法与证据 | 判定及影响 |
+|---|---|---|---|
+| | | | 已确认缺陷 / 潜在风险 / 本次未发现异常 / 未验证 |
+
+（说明排查边界、未覆盖项及理由；仅个案问题也需依据）
+
+## 方案与验收
+
+（处理选项、推荐理由、修复位置、实施步骤、风险；临时止血的局限和根治安排；原例/同类变体/边界与异常路径/正常行为的预期结果和验证方法。详见 [验证契约](../2026-09-21-validation-contract.md#问题修复的回归范围)。已有独立方案时链接，不复制全文；明确本轮是研究还是已授权实施。）

 ## 严重度

@@ -27,6 +27,19 @@

 例外须写 owner、原因、覆盖条款、范围、期限/退出条件和恢复动作。紧急热修仅可延后启动阅读，24 小时内补证；不豁免 worktree、安全与验收边界。

+### Bug 与系统问题的分析要求
+
+用户报告 bug、异常行为或系统问题时，将具体案例作为问题入口，先研究它暴露的机制与问题类别，再提出方案；不得以只让原句、原数据或单一路径通过作为问题已解决的依据。
+
+1. **还原事实与根因**：记录预期/实际行为、触发条件和环境，沿相关实现与运行链路追查原因及为何现有防护未发现它。区分已证实根因、待验证假设与证据缺口；无法复现时给出下一步验证方法，不把猜测当结论。
+2. **排查同类与关联问题**：按共用的判断逻辑、接口、状态、数据流或配置检查其他入口、相近场景和边界条件，记录已查范围、相关缺陷、潜在风险与未覆盖项。扩展范围须有机制或证据联系；范围仅限个案时也须说明依据，不无边界扩成全系统重构。
+3. **形成可审方案**：基于研究说明问题类别、因果链、影响范围、处理选项与推荐理由，给出修复位置、实施步骤、风险和验收方法。优先修正共用机制；个案特判或临时止血须说明适用理由、局限及后续根治安排。
+4. **按问题类别验收**：依 [验证契约](./.doc/ops/2026-09-21-validation-contract.md#问题修复的回归范围) 覆盖原例、同类变体与正常行为。分析与方案写入任务或 [分析主文档](./.doc/ops/templates/audit-note.md)，明确哪些问题已确认、哪些待验证；研究完成不等于修复完成。
+
+例如“今天天气怎么样”回复异常，应调查意图识别、上下文/地点/时间解析、实时信息获取、工具调用与失败反馈中有证据关联的环节，并检查其他措辞和共用机制的查询；这些是排查方向，不是预设根因或要求逐项全查。不得仅硬编码这句话的回复。
+
+上述研究遵守既有授权与环境边界。用户只要求分析/方案时交付可审方案；已授权修复时在授权范围内继续实施和验证，同类排查不自动授权扩大业务实施范围。
+
 ## 3. 写入、集成与环境边界

 - 主目录用于 `dev` 集成与运行；所有新增开发、配置、规范和文档修改在 `.worktrees/` 中的 `feature/<task-id>` / `fix/<task-id>`。主目录跟踪文件仅经受控集成更新；`.git`、任务 worktree、运行数据和获授权运维配置除外。禁止递归 chmod 主目录。