/report

name: report
description: 生成并写入工作流执行报告。适用于 dev/fix/analyze/audit/self-fix（chat 豁免）。

跨工作流稳定字段、条件段和 workflow overlay 的机器可读唯一事实源为同目录 `report-schema.json`。本 Skill 负责生成流程和人读解释；Gate 结果只记录 `gateGroup / result / evidence / skipReason`，不得在报告模板复制完整 Gate 目录。

报告可先保存当前草稿并精确修补。标题、模板及编号缺口作质量提示，不能否认真实文件写入或阻断原任务；已交付历史报告仍须保留。留痕暂不可用时保存可恢复正文和失败原因，继续其他可执行工作，后续补写并读回；未实际写入不得宣称“已记录”。Stop 不为形式缺口强迫重复回合。

报告路径

需求级（优先）

任务关联到 `requirements/` · `bugs/` · `optimizations/` 目录时：

<任务目录>/reports/<agent>/YYYYMMDD/NN--<简述>.md

项目级（兜底）

reports/<子目录>/<agent>/YYYYMMDD/NN--<简述>.md

| 工作流 | 默认子目录 | |--------|:----------:| | dev | `requirements/` | | dev (optimization) | `optimizations/` | | dev (scenario-test) | `scenario-tests/` | | fix | `bugs/` | | analyze | `analysis/` | | audit | `audit/` | | self-fix | `self-fix/` |

> 路径详细规范见 [`02-output-paths.instructions.md`](../../instructions/02-output-paths.instructions.md)。 > 当 `<工作区根>/.devcodex/layout.json` 启用 `workspace-namespace` 时，本文中的任务目录与项目级 `reports/...` 均以当前 **`<active-root>`** 为根。

报告索引维护预览

`scripts/lib/report-index.js` 当前只有测试与 benchmark 消费者，尚未接入正式的 CLI/MCP reader 或 writer，因此属于 **maintenance/preview**，不能作为普通报告、 resume、ECR 或 ContextRead 的已发布依赖，也不能据其状态要求用户刷新上下文。

普通工作流应在下列白名单根内做有界的 canonical Markdown 路径盘点，选定具体文件后 再读取正文：`<active-root>/reports/**` 与 `<active-root>/{requirements,bugs,optimizations,scenario-tests}/<task>/reports/**`。 不得先把整个 report corpus 正文装入上下文。

只有显式的索引维护、测试或 benchmark 可以直接调用内部模块，并遵守以下预览契约：

• 默认只发现 `primary-report`；`evidence`、`artifact`、`generated-copy` 与

`unknown` 必须显式筛选，unknown 保留 warning。

• 查询和 hydration 保持 zero-write；只有维护路径可调用 `rebuildReportIndex`。
• `fresh` 仅表示 metadata 路径已协调，不代表正文已验证；pointer 损坏、陈旧或

出现未登记文件时，只允许内存中的 path/stat reconcile。

• 多页查询必须绑定 `snapshotCursor`；截断正文只能声明

`metadata-reconciled`，不得声明全文内容已验证。

• 在正式 reader、writer、repair owner、宿主契约与 package 验证全部落地前，

Profile 和用户文档只能把该能力标为 maintenance/preview。

头部必填

# [标题]

> **项目**: [项目名]
> **类型**: [类型]
> **子类型**: [子类型]（无子类型时省略此行）
> **创建日期**: YYYY-MM-DD HH:MM
> **Agent**: [agent-id]
> **状态**: 进行中 / 已完成

命名规则

| 组件 | 规则 | |------|------| | `NN` | 当日序号，从 `01` 起递增（扫描同目录取 max+1）| | `--` | **双横杠**（非单横杠），分隔序号与简述（[FC4](../compliance/SKILL.md) 检查） | | `<简述>` | 2~5 个中文词或英文单词，连字符分隔 |

示例：`01--v4规范全面审查.md`、`02--intent修复后再审.md`

工作流 overlay 与条件段

跨工作流稳定字段、条件段和各 workflow overlay 的机器可读事实源为同目录 `report-schema.json`。生成前实际读取本次 workflow 对应 Prompt 正文及 schema，以其字段和扩展点组织当前任务内容；记录 templateRef/templateDigest 与生成依据。先写 `baseFields`，再按最终 workflow 合并一个 overlay；不得在本 Skill、Prompt 或模板中复制完整 Gate 目录。仅在 prewrite 自动绑定模板、结构检查通过或碰巧出现相同标题，均不能证明内容由模板生成。历史报告保留原依据，无法证明时写 UNVERIFIED，不补造生成回执。生成后的语义审阅核对本次请求、已执行动作、证据和结论，不把无关正文或通过话术当作任务完成。

| workflow | overlay 重点 | |----------|--------------| | `dev` / `fix` | 需求或问题追踪、实现/根因、TestRoute、文档同步；repair task 追加双层修复协作与零残留扫描 | | `audit` / `analyze` | 覆盖声明、轮次、CRS、PCV、推断边界与未读集合 | | `optimization` | baseline、candidate、归因和回归预算 | | `scenario-test` | 场景矩阵、环境、服务生命周期清理和结果 |

报告触发治理 Gate 时，读取 `../spec-governance/gate-registry.json` 确认 `gateGroup` 与 Owner Skill，只记录 `gateGroup / result / evidence / skipReason`。Gate 的专属字段、完整证据和验证路线归目标 Owner Skill；报告通过链接引用，不复制成跨版本长表。

条件段按 `report-schema.json#conditionalSections` 生成：

• 跨会话、多批次、中断或残余风险未关闭时写 `ContextHandoffCard`。
• dev/fix 改变项目现实且命中 Profile 影响时写 `ProfileImpactCheck`。
• 只有正式 release workflow 才写 `ReleaseVerification`。
• 新增或改变 Rule/Skill、Prompt、MCP Resource/Resource Template/Tool、Task 增强 Tool、CLI 或 Hook 时写 `CapabilitySurfaceDecision`：只引用中央 `decisionRef / status / identity / preferredSurface / validationRoute` 和 Owner 证据，不复制判定矩阵；缺失或陈旧时报告必须降级为 `BLOCK/UNVERIFIED`。
• 命中 `host-capability-routing` 时，在既有治理证据或 handoff 中追加 compact `HostCapabilityRoutingRef`：`instructionRefId / decisionId / catalogVersion+digest / selectedPortableDecision / nativeEligibility.status / fallback.reasonCode`。不得复制原始消息或 catalog row；portable `plan_first` 不得写成 native Plan 已进入，宿主 approval/permission/YOLO mode 不得写成 CP/Auto。
• 所有非空用户消息保留 `GovernanceIntakeDecision`；未命中台账写入时也要给出独立 `skipEvidence`。
• 命中 `requirementParallelOrchestration` 时写并行编排摘要：`RequirementIndependenceDecisionV1` 分类、`SharedSurfaceLockMapV1` 锁、`ParallelLaunchCardV1` 有效性、`HostSubagentDispatchPlanV1` 的 capability/economics/fanout/depth/serial fallback、`AgentWorkLeaseV1` 数量、accepted/quarantined/serial takeover、固定汇合顺序、root retest、owned resource cleanup 和未关闭风险。没有实际宿主 spawn/wait/interrupt direct evidence 时必须写 UNVERIFIED + serial fallback；报告不得把工具可见、child 完成或 child 测试通过冒充宿主并行 PASS、正式验证通过或任务完成。
• 命中 `agent-turn-liveness` 时写 `TurnLivenessRecovery`：只引用 Owner 的状态/lease/ACK/terminal/checkpoint、HostContractRoute、fault matrix 与 sidecar lifecycle 证据；必须区分 host-native、Hook-event 和 sidecar，不能把 PostToolUse 落盘冒充模型续接或终态。
• 命中增量项目分析时写 `ProjectKnowledge`：只记录 V2 snapshot/plan/receipt/binding identity、inventory Merkle、changed/affected/lens-gap/reused、5% oracle、claim authority/range 验证、V1 read-only migration 状态、batch accepted pointer 与 final/provisional 边界，禁止把快照或声明正文复制到报告或 SUMMARY；结构化 bootstrap 不得表述为人工逐文件深读。
• 命中 formal retry/cancel/restart 时写 `ExecutionAttemptLedger`：分列 qualification、failureSignature、source/evidence delta、FirstPassYield、command/external/user/model timing、StopSnapshot 与 terminal/finalizer；不得把等待时间混成执行性能。
• 任何 repair task 写 `RepairPreventionAssessment`：引用 Owner 的 assessment identity/decision/mode，分列 `immediateClosureEvidence` 与 `prospectiveEvidencePlan`，并记录 rollback/sunset；不得用本次测试通过宣称长期 prevention effective。
• 正式复审/ECR 写 `ReviewExecution`：引用 `ReviewExecutionPlanV1`、fresh receipt digests、EvidenceSaturation、唯一 `ReviewStateSnapshotV1.snapshotDigest` 与 `StageTimingV1`；报告不得重新推导 review counts 或把 failed/inconclusive receipt 写成可复用。
• **ReviewGradeCard（C19↔R）**：CP 确认后前置复审与 ECR 在报告中须记录 `c19Label`（轻量/标准/全面/发布安全）与 `reviewClass`（R0~R4）、`riskClass`/`riskFlags`、`contentPack`、`result`；默认 ECR 为 **R2（标准）**，禁止写「永远轻量一眼通过」而无 `skipReason` 的 R1 降级；R3/R4 须引用 checklist 或独立证据口径。

最终回复是独立交付 surface：报告必须先登记到 `ArtifactDeliveryManifestV1`，再由 `UserFacingArtifactSetV1` 投影；生产代码优先调用 `composeFinalArtifactDeliveryEnve