---

name: issue-pr-traceability-standard description: 需求事实来源（Source of Truth）与 Issue/PR 溯源关联标准。用于确定"这次要做什么"的权威载体、把 Issue → 分支 → commit → PR → CI → 部署 → tag 串成双向可导航的溯源链、约束 Agent 自行取用上下文（而不是要人类粘贴需求与报错日志）、以及处理范围漂移与跨仓需求扇出。任何"派发一个任务就自主开工"的闭环执行都必须先遵守本标准。

Issue/PR 关联与需求事实来源标准

其他工程标准回答的是**"怎么做、做到哪、怎么验"**；本标准回答更靠前的一个问题： "这次到底要做什么，以谁说的为准，上下文从哪来。"

没有这一层，闭环执行就退化成"人类反复粘贴需求和报错日志"—— Agent 有自主性，却没有权威输入。

0. 边界：与其他标准的分工

本标准与既有标准交叉互补、互不重复。属于下表右列的内容，去对应标准查，本文不再复述：

主题	归属
分支类型 / PR 目标矩阵 / 合并与发布 / tag 规则	project-development-standard
PR 正文必填项、跨仓 companion PR 互链与合并顺序	project-development-standard
角色权限边界、红线、越权与泄露应急响应	ai-agent-collaboration-standard
CI/CD 编排、脚本外置、假绿防治的流水线侧实现	ci-cd-workflow-spec
环境路由、OIDC/Vault 鉴权与密钥分层	multi-environment-delivery-and-release
Terraform / Ansible 的写法与状态隔离	infrastructure-as-code-spec、config-as-code-spec
闭环循环本身的推进、重规划与回滚编排	harness-workflow

本标准只管四件事：需求的权威载体、溯源链的标识符落点、自取上下文的义务、需求与验收的对应关系。

一个容易混淆的对照：config-as-code-spec 里的"CMDB 是交付目标的事实来源"回答"改哪台机器"； 本标准的"Issue 是需求的事实来源"回答"为什么要改"。两者是不同的轴，不冲突。

1. 需求事实来源

1. Issue（或等价的任务单）是唯一权威需求载体。 对话记录、口头交代、截图、聊天里的补充要求， 都不是事实来源——它们是尚未回写的输入。
2. 无 Issue 不开工。 收到没有 Issue 的任务时，先创建 Issue 并取得确认，再进入执行循环。 紧急止损可以先动手，但必须在同一轮内补登 Issue 并写明"事后补登"。
3. Issue 必须包含（缺一项就不具备开工条件，应先补全而不是猜）：
   • 目标：要达成的用户或工程结果，一句话说清；
   • 验收标准：可机器判定的条目（见 §4），不是"跑通了就行"；
   • 影响范围：涉及哪些仓库、哪些环境；
   • 约束：不能动什么、必须兼容什么。
4. 冲突时以 Issue 为准。 对话里出现与 Issue 不一致的新要求， 先回写 Issue，再据此执行；不得凭对话直接改代码而让 Issue 停留在旧版本。 回写这一步本身就是"人类确认"的载体。

2. 溯源链

一次交付必须形成双向可导航的链条，任一环都能反查需求，也能从需求正查到产物：

Issue ──▶ branch ──▶ commit ──▶ PR ──▶ CI run ──▶ deploy record ──▶ tag
  ▲                                                                  │
  └──────────────────── 关闭时回写证据 ◀──────────────────────────────┘

标识符的落点（只规定放哪、不重复各标准已定义的格式）：

环节	承载需求标识的位置
分支	分支名带 Issue 编号（前缀仍按 project-development-standard 的类型矩阵）
commit	正文或 trailer 引用 Issue 编号；一个逻辑变更一个 commit
PR	正文用关闭关键字关联 Issue；跨仓时同时指向父 Issue
CI run	由 PR 关联自然获得，不额外标注
部署记录	记录本次部署对应的 PR / tag，可反查回 Issue
tag	发布说明列出本次包含的 Issue 清单

断链即缺陷：出现"改了代码但查不到需求"或"Issue 关了但找不到落地 PR"时，按缺陷处理并补链。

3. 自取上下文：不得要求人类粘贴

红线：Agent 不得向人类索取自己有权限、有工具取到的信息。 需求正文、既有实现、变更历史、CI 失败日志——这些都属于必须自取的范畴。

需要什么	自取方式（示例，按实际工具链替换）
需求正文与讨论	gh issue view <n> --comments
关联 PR 的现状与评审意见	gh pr view <n> --comments
变更历史与既有约定	git log、git diff、读仓内既有实现与邻近测试
CI 结论	gh pr checks <n>
CI 失败详情	gh run view <id> --log-failed
仓库结构与边界	仓内 AGENTS.md / README / Repo Map

允许向人类索取的，只有三类：权限之外的信息、判断题（方案取舍、风险接受）、 以及授权（闸门确认）。除此之外张口要资料，视为违反本标准。

4. 验收标准即证据契约

1. Issue 的验收标准必须写成可机器判定的条目——可以是命令与期望结果、可复查的 URL/编号、 可断言的探针，而不是主观描述。
2. 关闭 Issue 需要证据链：PR 编号 + CI 结论 + （涉及部署时）部署记录。缺证据不得关闭。
3. 退出码 0 不等于验收通过。 流水线侧如何防假绿属于 ci-cd-workflow-spec； 本标准只要求：验收标准必须写成"能证伪"的形式—— 一条无论做没做都会通过的验收标准，等于没有验收标准。
4. 部分完成时不关闭：拆出剩余项到新 Issue 并互相引用，而不是关掉再说。

5. 范围漂移控制

• 实际要做的事超出 Issue 时：先更新 Issue（或拆新 Issue），再继续动手。 禁止让 PR 悄悄变宽而 Issue 停在原描述——那会让溯源链名存实亡。
• 一个 Issue 一条主线。顺手发现的问题另开 Issue，不塞进当前 PR。
• 需求被否决或作废：关闭 Issue 并写明原因，同时关掉其派生分支与 PR，不留悬空引用。

6. 跨仓需求扇出

一个需求跨多个仓库落地时：

• 建一个父 Issue 承载需求与验收标准，位置选在需求归属方（通常是发起变更的业务仓）；
• 每个仓各自开 PR，全部回指父 Issue；
• 各 PR 之间的互链、合并顺序、兼容窗口与回滚责任人，按 project-development-standard 的跨仓条款写；
• 父 Issue 只在所有子 PR 落地且验收证据齐备后关闭，不随第一个 PR 合并而关闭。

7. 禁止模式

• 凭对话记录开工，Issue 停留在旧版本或根本不存在。
• 要求人类粘贴 Issue 正文、报错日志、diff 或 CI 输出。
• 验收标准写成"功能正常""跑通即可"这类无法证伪的描述。
• PR 范围超出 Issue 而不回写。
• 拿"CI 绿了"当验收依据却拿不出对应的证据条目。
• 父 Issue 在子 PR 尚未全部落地时提前关闭。