Report

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

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

报告路径

需求级（优先）

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

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

项目级（兜底）

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

路径详细规范见 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。

头部必填

复合要求的报告引用 review-checklist 已审阅的同一ConditionEvidenceMatrixV1，分别报告设计覆盖与实际执行结果，不另造分母、状态或证据。候选模块只验证声明结构，普通报告不因引用它就成为候选或取得语义通过。验证责任引用test-router的D/A/I/H矩阵，保留适用性、候选/环境/版本/run、证据与限制；H不自动增加批准对象。任一未运行、partial或unknown保持原状态，不用汇总“全部通过”抹掉未验证项。旧报告不为新条件段重写历史。

markdownCopy code
# [标题]

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

命名规则

示例：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，不补造生成回执。生成后的语义审阅核对本次请求、已执行动作、证据和结论，不把无关正文或通过话术当作任务完成。

报告触发治理 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 投影；生产代码优先调用 composeFinalArtifactDeliveryEnvelope 串起 manifest、visible set、delivery attempts 与 envelope，任务目录 delivery-manifest.json 需要对外可见时先经 createVisibleManifestFromTaskDeliveryManifest 投影，不得直接手写最终清单。默认用户面显示最终报告、直接交付物和 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
• 命中专家产物、用户操作说明、重要方案或推荐结论时，报告必须引用 ExpertOutputQualityGate、OperationExplanationContractV1、CodeTruthEvidenceMatrixGate、SolutionFitAgainstRepoGate 与唯一推荐证据；不得只写“已优化表述”或用文档自洽替代 repo 事实。
• analyze / audit / self-fix / dev / fix 报告中，若出现多个可执行建议、多个后续路径、方案对比或用户决策点，必须新增 ## 推荐结论 或 ## 推荐方案：推荐项有且仅有 1 个，并说明“推荐理由”；无后续动作时写 推荐：无后续动作 与原因
• UniqueNextStepRecommendationGate（PF-172 / SC5）：完成态 / 收口的 ## 后续建议 与用户可见「下一步」必须是 唯一主动作。禁止写成「做 A 或做 B」或同级双 bullet 让用户再选；非推荐路径只能写在「不推荐」小节并说明劣于推荐的理由。机器负向：scripts/lib/discipline-execution-probe.js 的 classifyNextStepOrForkSample（or-fork = fail）
• 若最终采纳的是用户原始方案，报告中也必须写明“经独立验证后采纳”及其证据来源，避免形成“顺从结论”的假象
• 报告中的治理落账编号必须与当前 active-root 台账和 Hook/人工复证一致；不能仅因正文出现 PI/PF/VL/GR/ISSUE 编号就写“已记录”。复合意图逐项列证据，record.none 列独立 challenge evidence。
• audit / analyze / self-fix 的汇总型报告默认采用“两层问题清单”：先列根因级问题，再展开逐文件完整落点；边界/非缺陷结论单独成节，不混入缺陷编号
• 报告写入后必须执行 compliance Skill §5 二次验证（V1~V6）
• dev / fix 报告在最终宣告完成前，必须显式体现“ECR 执行闭环复审”这一正式阶段（默认 reviewClass=R2 + ReviewGradeCard），并与 CP1/CP2/CP3、关键产物、报告、daily tasks、SUMMARY、diff/commit、测试/扫描证据和 dirty 边界完成 1 轮复审对照；若发现阻断性问题，不得直接以“已完成”收尾
• 跨会话、跨 Agent、多批次、summary/compact 前、用户要求“传递上下文”或未完成任务的报告必须包含 ContextHandoffCard；已完成且无需交接时写 ContextHandoffCard: N/A + skipReason
• 主动建议或 C08 强制新会话时，最终回复与报告须含 NewSessionContinuationCard；内部字段保留 taskId/项目/CP/真相源/风险/验证，用户可复制的 copyReadyPrompt 固定为 继续<displayName>任务。CP pending 不得写成 confirmed，resolver 命中也不得替代文件复水化
• 长任务报告附录推荐 SessionTimingCard（startedAt/endedAt、阶段耗时、waiting-user / waiting-external 分列；命中预算时附 cycleId 与 budget 消耗）
• 长任务 / Auto / 多批次报告条件段：ExecutionBudget（maxWallClock 与触顶 StopSnapshot）、ExternalWaitAccounting、LongTaskAuthorization（PI-118 / PF-137）；未触发写 N/A + skipReason
• WorkspaceSyncStatus（PI-109 / PF-129）：凡改规范源 / Skill / 部署消费者 / Profile 部署面，最终回复与报告必须写 workspaceRoot、updateCommand、hostsSynced（如 .github/.claude/.agents/.codex/AGENTS.md）、result（synced / skipped+reason / blocked）、evidence；禁止只写「源码已改」却不说明工作区部署是否同步
• CompletionEvidenceGate：dev/fix/self-fix 宣告「已完成 / 已收口」前，报告必须同时具备：① ECR 矩阵或显式 N/A 理由；② 适用时的 WorkspaceSyncStatus；③ 测试/validate 关键证据或阻塞说明；④ dirty 边界说明；⑤ 存在派生资产时的 PostStageDerivedArtifactFreshnessGate staged candidate receipt 与 post-commit clean-tree replay。最终回复必须以 FinalValidationSummaryV1 短矩阵列出命令/exitCode、runId 或关键计数、workspace sync、dirty boundary、release action boundary；缺任一适用项不得写「已完成」
• EnforcementHonesty（R5）：完成态报告或最终回复须含「拦截与流程诚实摘要」表（host / hard 事件 / Stop 决策 / processGaps）；模板见 compliance Skill；枚举含 pr1-skipped、cp2-unconfirmed-write、entry-check、stage-report-missing、progress-overclaim、ecr-missing 等。测试绿 ≠ ECR：npm run test:* 通过不能代替 N6 ECR 段与 DoD 对账表
• PostDeliverySelfCheck（条件）：长任务结束、宣称完成、或用户质疑慢/漏/不专业时，最终回复前轻量自检：耗时分列是否诚实、完成证据是否齐全、是否越界宣称「完整/零遗漏」、可泛化改进是否已走 Improvement Intake。纯 chat / 中间进度可 N/A。禁止每条短回复强制全量打分写 PI
• 最终确认清单 / 可吸纳包 / 实施 backlog（analyze 收敛交付）必须附 FindingThemeCoverageMatrix（ABS-17）：每行 sourceId → mappedTo | residualId | EX | disposition；禁止仅用主题合并清单宣称「完整/零遗漏」；用户确认主题包后若有 residual，状态标 partial-confirmed 并列出 residual pack。命中规范吸纳时必须同时附 source-existence verification 证据、ProbeNecessity / enforcementLevel（回答「不按流程谁会红」）与并列 可关账清单；禁止只按台账 open/pending absorption 输出 absorb；禁止 checklist-only 假吸纳
• dev / fix 报告的 ECR 必须核对本轮真实触发的条件产物、TestRoute、Owner 证据、进度/记忆/台账、部署同步和 dirty 边界；未触发项按 schema 写 N/A + skipReason
• 方案/复审阶段出现 blocker 时，报告必须引用完整 BlockerSnapshot；同阶段安全独立检查未执行时记录 stopReason / skippedChecks / recoveryEntry，不得只报告首个红项后声称该阶段已完整审查
• 报告宣称“不再依赖其他模型审查 / 审查质量已内化”时，必须列出需求候选、技术方案候选、CP gate、复审清单、脚本探针和宿主投影的同步证据；仅改 Prompt 或仅跑外部报告复核不够。
• backlog intake、治理落账、规范吸纳、历史分层、用户建议采纳、跨会话恢复、Profile、发布、安全审查或专家 Owner 等条件语义，统一从 report-schema.json 与 ../spec-governance/gate-registry.json 生成对应段；报告只记录 gateGroup / result / evidence / skipReason 并链接 Owner 产物
• 命中 evidence-freshness 时追加 EvidenceFreshness 条件段：记录 mode、status、strong claim count、downgradeRequired、rerunRequired、summary-only 边界、artifact anchor / final validation summary binding 与生产入口命令 exitCode；不复制 receipt 全文
• 任何条件段都不得复制版本化 Gate/Owner 名录；新增能力先更新 registry/schema、Owner 与验证探针，再由报告消费者引用
• 报告涉及规范源、Skill、Hook、CLI、MCP、模板、部署副本、路径规则或 validate 语义变更时，仍需列出 SCV-0~SCV-7 证据；外部 finding intake 不得把报告结论当作已验证事实
• 控制面报告若出现新增探针、黄色偏离或部署同步，必须单独写出部署同步证据与其他证据来源，不能只在摘要里带过
• 报告末尾引用本次会话记忆路径
• 回复末尾由 user-visible-output-contract 输出“完成交付文件”：每项使用语义 displayName、purposeText、userAction，并强制 路径列（默认 workspace-relative portable，见 PF-175 路径列规则），按 decision→result→evidence→optional 顺序。ArtifactLinkSet 只作兼容投影；Rich clickable 不在路径列外重复 绝对路径： 行，只有用户要求、链接失败、工作区外、歧义或无法定位时路径列/fallback 用绝对路径（详见 02-output-paths.instructions.md）
• Dialogue-Primary Closeout（对话内可读收口）：完成态 / analyze·audit 收敛的阅读主入口是最终回复，不是打开报告源码。最终回复须含叙事最小包（结果一句话 + ≥1 实质要点）+（完成态）FinalValidationSummary + 唯一步 + 交付清单；报告仍强制落盘（chat 豁免）。禁止仅链接/详见报告/纯矩阵收口；analyze 有报告链接但无可读结论 → link-only-thin（classifyAnalysisArtifactDeliverySample）。userAction 默认「深读时打开归档报告」，禁止默认「请用 Typora/浏览器预览」。机检：classifyDialogueNarrativeSample / hasReadableNarrativeSnippet

行数与拆分

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

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

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

跨会话报告

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

模板引用