report

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

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

报告路径

需求级（优先）

任务关联到 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。 当 <工作区根>/.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 检查）
<简述>	2~5 个中文词或英文单词，连字符分隔

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

工作流 overlay 与条件段

跨工作流稳定字段、条件段和各 workflow overlay 的机器可读事实源为同目录 report-schema.json。生成报告时先写 baseFields，再按最终 workflow 合并一个 overlay；不得在本 Skill、Prompt 或模板中复制完整 Gate 目录。

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 有效性、汇合协议、单写者和未关闭风险；报告不得把子会话完成冒充最终完成。
• 命中 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 写成可复用。

最终回复是独立交付 surface：报告必须先登记到 ArtifactDeliveryManifestV1，再由 UserFacingArtifactSetV1 投影。默认用户面显示最终报告、直接交付物和 required evidence；session/daily/SUMMARY/task/checkpoint/raw receipt/manifest/ledger 默认 internal-only，但仍写入并参与 ECR。可见回复证据使用 verified-present / verified-missing / unverified，legacy 文本最多 unverified-legacy，不可观察时不得断言缺失。

输出规则

• 每次会话必须写入报告文件（chat 豁免，C05/S05）
• 报告中每条建议/问题必须附五项验证（合理性 + 可实施性 + 收益 + 验证状态 + 影响范围）— 与 17-compliance §1 输出验证保持一致
• MeasuredVerificationStandard（V84 / SC14）：报告中凡将 validate、targeted test、npm run test:core / npm test、性能数字或命令输出标为 ✅已验证，必须写生产入口命令与 exitCode；自写隔离 harness 或未复用 validate.js 的 createCanonicalAwareReader 时只能标 非权威实验 / ⚠️待验证(生产路径)，不得写成「V# 失败/通过」或「今日 core 红/绿」。用户可见摘要须分列权威路径与实验路径，完成态最终回复还必须投影 FinalValidationSummaryV1 或等价短矩阵。
• EvidenceFreshness：报告、分析、审查、推荐结论、CP 可确认声明、外部 finding 采纳和完成态强声明命中 evidence-freshness gateGroup 时，必须记录 ClaimEvidenceIndexV1、EvidenceFreshnessReceiptV1 或 StaleEvidenceLintDecisionV1 摘要。memory/SUMMARY/历史报告/外部审查文字只能作为 summary-only / navigation hint；缺 fresh evidence 的强主张必须降级为 WARN/UNVERIFIED 或在 enforce 场景阻断。机器实现：scripts/lib/evidence-freshness-receipt.js；生产入口：npm run test:evidence-freshness。
• ExternalReviewClaimVerificationGate（PF-164）：对外部/他 Agent 审阅的复核报告必须含 inputClaims、ClaimVerificationMatrix、项目证据、验证状态、disposition、unverifiedBoundaries 与可点击详细报告链接；只写总评或建议视为不合格。Owner 细节见 audit-report；机器分类见 scripts/lib/external-review-claim-verification.js。
• RequiredCandidateEvidenceGate：dev/fix 报告若覆盖 CP1/CP2 候选或确认前复审，必须记录 CandidateReviewBundleV1 分类、缺失字段、阻断快照和相关命令（如 npm run test:candidate-review-bundle）。外部审查发现只通过 EscapeAbsorptionQueue / ClaimVerificationMatrix / 本地证据进入结论，禁止直接吸纳。
• OptimizationEvidenceFamily（PF-168/169/170）：
  • 优化需求/方案问题表：须证据等级 A/B/C + 可复现命令；未验证不得写「完整必须优化清单」（classifyOptimizationBacklogEvidenceSample）
  • 非 chat 方案审阅/深度分析：须落 reports/** 并给可点击链接；禁止仅对话长文宣称分析完成（classifyAnalysisArtifactDeliverySample）
  • 残留可优化清单：须证据等级 + 预期收益/影响风险/前置条件（classifyResidualOptimizationListSample）
  • 机器实现：scripts/lib/optimization-backlog-evidence.js

行数与拆分

• C13 只约束新建 DevCodex 规范资产 .md；报告不因 C13 强制压缩或拆分，超长报告按可读性、索引导航和项目规范决定是否拆分

写入工具选择（v1.9.4+）

新建报告预计 ≥ 200 行 → Write 单次写入（避免 Edit 多段写入被 session limit 截断；详见 16-report.instructions.md §写入工具选择）。已有报告小修订 → Edit。

跨会话报告

场景	处理
同一任务跨多会话	每次会话创建独立报告文件，不追加到前一份
修复后再审	独立文件，头部引用原始审查报告路径
Token 中断恢复	新报告标注"恢复自会话 NN"

⚠️ dev / fix 的“修复后再审/再次实施”并不自动等于收敛；仍须满足 ECR 执行闭环复审规则，确认最后一次阻断性修正后已有 1 轮无新增阻断问题的复审。

模板引用

报告类型	模板
分析报告	prompts/report-analysis.prompt.md
审查报告	prompts/report-audit.prompt.md
规范自修复报告	prompts/report-audit.prompt.md（结构相同，路径映射 self-fix/）
开发报告	prompts/report-dev.prompt.md
开发报告（性能优化）	prompts/report-optimization.prompt.md
开发报告（场景测试）	prompts/report-scenario-test.prompt.md
修复报告	prompts/report-fix.prompt.md