@zhuan-ai/zhuanspec 2.16.2 → 2.16.4

package/dist/core/metrics/code-accuracy.d.ts

@@ -38,6 +38,66 @@ export declare function appendAccuracyDebugLog(changeDir: string, entry: Accurac
  * 判断是否为代码文件（需纳入准确率统计）
  */
 export declare function isCodeFile(filePath: string): boolean;
+/**
+ * Review 阶段自动修复 Skill 列表。
+ * 这些 Skill 在 review 阶段触发的代码编辑属于自动修复，
+ * 不应计入用户纠正（不影响 apply 阶段准确率）。
+ *
+ * 匹配规则：skill name 包含列表中任一子串即视为 autofix skill。
+ */
+export declare const REVIEW_AUTOFIX_SKILLS: string[];
+/**
+ * 纯确认/招呼类 prompt，不具备纠偏意图，不应触发用户纠正归因。
+ * 与 src/core/corrections/select-candidates.ts 中的 TRIVIAL_ACK_SET 保持同步。
+ */
+export declare const TRIVIAL_ACK_WORDS: ReadonlySet<string>;
+/**
+ * 判定 prompt 是否为琐碎确认/招呼（如"继续"、"好的"、"ok"等）。
+ *
+ * 规则：
+ *   1. 空字符串视为琐碎；
+ *   2. 规范化后命中 TRIVIAL_ACK_WORDS 视为琐碎；
+ *   3. 规范化后字符长度 ≤ 2 视为琐碎（如"好。"、"!!"）。
+ *
+ * 注：斜杠/感叹号开头的命令词（/zhuanspec:、!ls 等）已由 user-input-hook
+ * 在写入 correctionContext 前过滤，无需在此重复处理。
+ */
+export declare function isTrivialAckPrompt(text: string | null | undefined): boolean;
+/**
+ * 判断 correctionContext 是否代表一次有意义的用户纠正（非琐碎确认）。
+ *
+ * 接受的 source：
+ *   - correction-keyword：命中显式纠偏关键词，始终视为用户纠正；
+ *   - post-baseline-prompt：baseline 后任何用户提示，但 promptSnippet
+ *     必须不是琐碎确认词（如"继续"、"好的"）。
+ *
+ * 该函数用于 review 阶段判定 "用户提示词触发的纠正"，使其覆盖范围与 apply 阶段一致。
+ */
+export declare function isMeaningfulUserCorrection(correctionContext?: {
+    active: boolean;
+    source?: string;
+    promptSnippet?: string;
+} | null): boolean;
+/**
+ * 判定当前 review 阶段的编辑是否属于 Skill 自动修复（CR/单测），不应计入准确率。
+ *
+ * 判定逻辑：取最近一次 review 阶段的 skill 调用，若 skill name 匹配 REVIEW_AUTOFIX_SKILLS
+ * 且该 skill 调用晚于最近的有意义用户纠偏上下文（correctionContext.resolvedAt），则视为自动修复。
+ *
+ * "有意义的用户纠偏" 定义：
+ *   - source = 'correction-keyword'，或
+ *   - source = 'post-baseline-prompt' 且 promptSnippet 不是琐碎确认词
+ */
+export declare function isReviewAutoFixActive(skillCalls: Array<{
+    skill: string;
+    triggeredAt: string;
+    phase: string;
+}>, correctionContext?: {
+    active: boolean;
+    resolvedAt?: string;
+    source?: string;
+    promptSnippet?: string;
+}): boolean;
 export type TrackedPhase = 'techDesign' | 'propose' | 'apply' | 'review';
 export type TrackedKind = 'techSpec' | 'proposalDoc' | 'code';
 /**
@@ -150,6 +210,22 @@ export declare function snapshotAiBaseline(progress: ProgressData, changeDir: st
  * @returns true 表示本次调用创建了新快照，false 表示快照已存在或跳过
  */
 export declare function ensureAccuracySnapshot(changeDir: string): Promise<boolean>;
+/**
+ * 同 (promptId + filePath + phase) 历史 record 中的最大 editLines。
+ *
+ * 背景：用户一次 prompt 可能触发 AI 多次 Edit（重复修正同一区域）。
+ * 直接累加会造成虚高；取 max 反映“最终保留下来的最大一次改动”。
+ *
+ * promptId 为空时返回 0（冷启动，当前是首条，取 0 后累加全量 changeLines）。
+ */
+export declare function computePromptFileMaxLines(correctionEdits: ReadonlyArray<{
+    filePath: string;
+    editLines: number;
+    phase?: string;
+    triggeredBy?: {
+        promptId?: string;
+    };
+}>, promptId: string | undefined, filePath: string, phase: TrackedPhase): number;
 /**
  * 用户纠正行数累计（legacy——新代码优先用 record-progress.ts 内联的 correctionContext 逻辑）。
  *

package/dist/core/metrics/code-accuracy.js

@@ -62,6 +62,110 @@ export function isCodeFile(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     return CODE_FILE_EXTENSIONS.has(ext);
 }
+// ============================================================
+// Review 阶段自动修复 Skill 白名单
+// ============================================================
+/**
+ * Review 阶段自动修复 Skill 列表。
+ * 这些 Skill 在 review 阶段触发的代码编辑属于自动修复，
+ * 不应计入用户纠正（不影响 apply 阶段准确率）。
+ *
+ * 匹配规则：skill name 包含列表中任一子串即视为 autofix skill。
+ */
+export const REVIEW_AUTOFIX_SKILLS = [
+    'code-review-expert',
+    'generate-mockito-unit-test',
+];
+// ============================================================
+// 琐碎确认词识别（与 select-candidates.ts 保持一致）
+// ============================================================
+/**
+ * 纯确认/招呼类 prompt，不具备纠偏意图，不应触发用户纠正归因。
+ * 与 src/core/corrections/select-candidates.ts 中的 TRIVIAL_ACK_SET 保持同步。
+ */
+export const TRIVIAL_ACK_WORDS = new Set([
+    '是', '是的', '好', '好的', '嗯', '嗯嗯', '对', '行', '可以', '确认',
+    '同意', '继续', '没问题', '明白', '了解', '知道了', '收到', '辛苦', '辛苦了',
+    'ok', 'okay', 'k', 'yes', 'y', 'yep', 'yeah', 'sure', 'fine', 'cool',
+    'go', 'go on', 'plan approved', 'continue', 'thanks', 'thx',
+]);
+/** 规范化文本：小写 + 中英文标点/空白统一压成单空格。 */
+function normalizeAckText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[\s\p{P}\p{S}]+/gu, ' ')
+        .trim();
+}
+/**
+ * 判定 prompt 是否为琐碎确认/招呼（如"继续"、"好的"、"ok"等）。
+ *
+ * 规则：
+ *   1. 空字符串视为琐碎；
+ *   2. 规范化后命中 TRIVIAL_ACK_WORDS 视为琐碎；
+ *   3. 规范化后字符长度 ≤ 2 视为琐碎（如"好。"、"!!"）。
+ *
+ * 注：斜杠/感叹号开头的命令词（/zhuanspec:、!ls 等）已由 user-input-hook
+ * 在写入 correctionContext 前过滤，无需在此重复处理。
+ */
+export function isTrivialAckPrompt(text) {
+    if (!text)
+        return true;
+    const norm = normalizeAckText(text);
+    if (norm.length === 0)
+        return true;
+    if (TRIVIAL_ACK_WORDS.has(norm))
+        return true;
+    if (norm.length <= 2)
+        return true;
+    return false;
+}
+/**
+ * 判断 correctionContext 是否代表一次有意义的用户纠正（非琐碎确认）。
+ *
+ * 接受的 source：
+ *   - correction-keyword：命中显式纠偏关键词，始终视为用户纠正；
+ *   - post-baseline-prompt：baseline 后任何用户提示，但 promptSnippet
+ *     必须不是琐碎确认词（如"继续"、"好的"）。
+ *
+ * 该函数用于 review 阶段判定 "用户提示词触发的纠正"，使其覆盖范围与 apply 阶段一致。
+ */
+export function isMeaningfulUserCorrection(correctionContext) {
+    if (!correctionContext?.active)
+        return false;
+    const source = correctionContext.source;
+    if (source === 'correction-keyword')
+        return true;
+    if (source === 'post-baseline-prompt') {
+        return !isTrivialAckPrompt(correctionContext.promptSnippet);
+    }
+    return false;
+}
+/**
+ * 判定当前 review 阶段的编辑是否属于 Skill 自动修复（CR/单测），不应计入准确率。
+ *
+ * 判定逻辑：取最近一次 review 阶段的 skill 调用，若 skill name 匹配 REVIEW_AUTOFIX_SKILLS
+ * 且该 skill 调用晚于最近的有意义用户纠偏上下文（correctionContext.resolvedAt），则视为自动修复。
+ *
+ * "有意义的用户纠偏" 定义：
+ *   - source = 'correction-keyword'，或
+ *   - source = 'post-baseline-prompt' 且 promptSnippet 不是琐碎确认词
+ */
+export function isReviewAutoFixActive(skillCalls, correctionContext) {
+    // 取 review 阶段中匹配 autofix skill 的最近一次调用
+    const recentAutofix = [...skillCalls]
+        .reverse()
+        .find(sc => sc.phase === 'review'
+        && REVIEW_AUTOFIX_SKILLS.some(s => sc.skill.includes(s)));
+    if (!recentAutofix)
+        return false;
+    // 如果存在有意义的用户纠偏上下文且 resolvedAt 晚于 skill 触发时间，说明用户已介入
+    if (isMeaningfulUserCorrection(correctionContext)
+        && correctionContext?.resolvedAt
+        && correctionContext.resolvedAt > recentAutofix.triggeredAt) {
+        return false;
+    }
+    return true;
+}
 /**
  * 判定 filePath 在当前 phase 下是否属于白名单，并返回文件分类。
  *
@@ -322,6 +426,32 @@ export async function ensureAccuracySnapshot(changeDir) {
     }
 }
 // ============================================================
+// 纠偏去重计算（同 promptId+filePath+phase 取 max）
+// ============================================================
+/**
+ * 同 (promptId + filePath + phase) 历史 record 中的最大 editLines。
+ *
+ * 背景：用户一次 prompt 可能触发 AI 多次 Edit（重复修正同一区域）。
+ * 直接累加会造成虚高；取 max 反映“最终保留下来的最大一次改动”。
+ *
+ * promptId 为空时返回 0（冷启动，当前是首条，取 0 后累加全量 changeLines）。
+ */
+export function computePromptFileMaxLines(correctionEdits, promptId, filePath, phase) {
+    if (!promptId || !filePath)
+        return 0;
+    let maxLines = 0;
+    for (const e of correctionEdits) {
+        if (e.phase === phase
+            && e.filePath === filePath
+            && e.triggeredBy?.promptId === promptId
+            && typeof e.editLines === 'number'
+            && e.editLines > maxLines) {
+            maxLines = e.editLines;
+        }
+    }
+    return maxLines;
+}
+// ============================================================
 // 用户纠正行数累计
 // ============================================================
 /**

package/dist/core/templates/codex-hooks-template.d.ts

@@ -85,5 +85,32 @@ export interface CodexHookSlot {
  * the same event (matching Codex's array-of-tables semantics).
  */
 export declare function getCodexDefaultHookSlots(): readonly CodexHookSlot[];
+/**
+ * Compute the content-trust SHA-256 hash for a hook handler, replicating
+ * the algorithm from Codex CLI's `codex-rs/hooks/src/engine/discovery.rs`:
+ *
+ * Codex hashes a `NormalizedHookIdentity` struct, which is serialized to
+ * TOML then converted to canonical JSON. The structure is:
+ *
+ *   { event_name, matcher?, hooks: [{ type, command, async, timeout, statusMessage? }] }
+ *
+ * Key normalization details:
+ *   - `timeout` defaults to 600 when absent in source TOML
+ *   - `async` is always false (we don't support async hooks)
+ *   - `command_windows` (None) is omitted in TOML serialization
+ *   - `matcher` is only included when present
+ *   - Keys are recursively sorted (canonical JSON) then SHA-256 hashed
+ *
+ * This allows ZhuanSpec to pre-seed `trusted_hash` entries directly without
+ * relying on cross-project hash grafting, eliminating the "Hooks need review"
+ * prompt on first use or after upgrades.
+ */
+export declare function computeHookContentHash(entry: CodexHookEntry): string;
+/**
+ * Get the computed content-trust hashes for all default hook handlers.
+ * Returns a map from slot suffix (`<event_snake>:<group>:<handler>`) to
+ * the SHA-256 hash string that Codex CLI would compute.
+ */
+export declare function getCodexDefaultHookHashes(): Map<string, string>;
 export {};
 //# sourceMappingURL=codex-hooks-template.d.ts.map

package/dist/core/templates/codex-hooks-template.js

@@ -25,6 +25,7 @@
  * ZhuanSpec markers of `<repo>/.codex/config.toml` so that `zhuanspec update`
  * can regenerate it idempotently without clobbering user-owned config.
  */
+import { createHash } from 'crypto';
 /**
  * ZhuanSpec default hooks, in logical order. Keep this list in sync with the
  * Claude settings.json generator in init.ts so behavior stays consistent
@@ -142,4 +143,84 @@ export function getCodexDefaultHookSlots() {
         return { event: entry.event, eventSnake, groupIndex, handlerIndex: 0 };
     });
 }
+/**
+ * Compute the content-trust SHA-256 hash for a hook handler, replicating
+ * the algorithm from Codex CLI's `codex-rs/hooks/src/engine/discovery.rs`:
+ *
+ * Codex hashes a `NormalizedHookIdentity` struct, which is serialized to
+ * TOML then converted to canonical JSON. The structure is:
+ *
+ *   { event_name, matcher?, hooks: [{ type, command, async, timeout, statusMessage? }] }
+ *
+ * Key normalization details:
+ *   - `timeout` defaults to 600 when absent in source TOML
+ *   - `async` is always false (we don't support async hooks)
+ *   - `command_windows` (None) is omitted in TOML serialization
+ *   - `matcher` is only included when present
+ *   - Keys are recursively sorted (canonical JSON) then SHA-256 hashed
+ *
+ * This allows ZhuanSpec to pre-seed `trusted_hash` entries directly without
+ * relying on cross-project hash grafting, eliminating the "Hooks need review"
+ * prompt on first use or after upgrades.
+ */
+export function computeHookContentHash(entry) {
+    // Build the normalized handler object matching Codex's HookHandlerConfig::Command
+    // after normalization (timeout defaults to 600, async always present).
+    const handlerObj = {
+        type: 'command',
+        command: entry.command,
+        async: false,
+        timeout: 600,
+    };
+    if (entry.statusMessage) {
+        handlerObj.statusMessage = entry.statusMessage;
+    }
+    // Build the NormalizedHookIdentity: event_name + flattened MatcherGroup
+    const identity = {
+        event_name: toEventSnake(entry.event),
+        hooks: [handlerObj],
+    };
+    if (entry.matcher) {
+        identity.matcher = entry.matcher;
+    }
+    const canonical = canonicalJson(identity);
+    const bytes = Buffer.from(JSON.stringify(canonical), 'utf-8');
+    const hex = createHash('sha256').update(bytes).digest('hex');
+    return `sha256:${hex}`;
+}
+/**
+ * Recursively sort object keys alphabetically to produce canonical JSON,
+ * matching Codex CLI's `canonical_json()` in fingerprint.rs.
+ */
+function canonicalJson(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalJson);
+    if (typeof value === 'object') {
+        const obj = value;
+        const sorted = {};
+        for (const key of Object.keys(obj).sort()) {
+            sorted[key] = canonicalJson(obj[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Get the computed content-trust hashes for all default hook handlers.
+ * Returns a map from slot suffix (`<event_snake>:<group>:<handler>`) to
+ * the SHA-256 hash string that Codex CLI would compute.
+ */
+export function getCodexDefaultHookHashes() {
+    const hashes = new Map();
+    const slots = getCodexDefaultHookSlots();
+    for (let i = 0; i < CODEX_DEFAULT_HOOKS.length; i++) {
+        const entry = CODEX_DEFAULT_HOOKS[i];
+        const slot = slots[i];
+        const suffix = `${slot.eventSnake}:${slot.groupIndex}:${slot.handlerIndex}`;
+        hashes.set(suffix, computeHookContentHash(entry));
+    }
+    return hashes;
+}
 //# sourceMappingURL=codex-hooks-template.js.map

package/dist/core/templates/slash-command-templates.js

@@ -432,6 +432,9 @@ const applySteps = `**步骤**
    - 阅读 \`changes/<id>/proposal.md\`、\`design.md\`（如果存在）和 \`tasks.md\` 以确认范围和验收标准。
 2. **Wave 并行执行（默认且唯一执行模式）**
    - **执行模型**：按 Wave 编号串行，Wave 内任务并行启动 subagent。
+   - **⚠️ 每个 Wave 启动前 MUST 重读核心机制（防长任务指令衰减）**：在为新 Wave 启动 subagent 前，编排 Agent **必须**在自己的输出里**逐字复述**以下两句话，作为执行前置自检（缺失即流程故障）：
+     1. "本 Wave 的每个任务 MUST 通过 Agent tool / spawn_agent 启动 subagent，禁止主线程串行手写代码或手写报告。"
+     2. "任务报告必须由 subagent 生成，且必须符合 .claude/agents/tdd-apply-agent.md 或 apply-agent.md 的模板章节。"
    - **并行度限制**：每个 Wave 内最多同时启动 3 个 subagent。超过 3 个任务时，按批次（batch）执行，每批最多 3 个并行 subagent，批次间串行等待。
    - **Subagent 调用 @skill 后的行为**（任务标注 \`@skill:<skill-name>\` 时）：
      1. 执行 @skill 标注的 Skill
@@ -512,6 +515,15 @@ const applySteps = `**步骤**
    - 同 Wave 所有任务（含阻塞任务）全部处理完成后 → 进入集成测试阶段
 
    **B. 集成测试阶段（MANDATORY，同 Wave 所有任务处理完成后）**：
+   B0. **任务报告 schema 校验（MANDATORY GATE，最先执行，不得跳过）**：
+      - 运行 \`zhuanspec validate-reports <change-id> --json\` 校验本 Wave 所有 \`reports/task-*.md\`
+      - 检查内容（基于 \`.claude/agents/tdd-apply-agent.md\` / \`apply-agent.md\` 模板）：
+        * 公共字段：\`## 状态报告\` / Status / Task ID / Report File / \`### Agent 选择决策\` / Agent 类型
+        * tddApplyAgent 报告必须有：TDD Phase / \`### 上下文就绪摘要\` / \`### 验收点映射表\` / \`#### Verify RED\` / \`#### Verify GREEN\` / \`#### Mock Gate\` / \`### 测试运行结果\` / \`### Self-Review 发现\` / \`### Issues/Concerns\`
+        * applyAgent 报告必须有：\`### 实施内容\` / \`### 修改文件\` / \`### Self-Review 发现\` / \`### Issues/Concerns\`
+        * 交叉对账：tasks.md 中带 \`@test-case:TC-XXX\` 的任务，报告必须为 tddApplyAgent，否则必须显式声明 "TDD 适用性: 不适合（降级原因：...）"
+      - 任意报告校验失败 → **该任务强制视为 BLOCKED**，按 B5 流程以 Execution Mode = RETRY 重新 spawn subagent 产出合规报告；禁止跳过本步直接进入 B1
+      - 校验失败的根因通常是：编排 Agent 在主线程手写代码 + 手写偷工报告，没有真的 spawn subagent。修复方式：通过 Agent tool / spawn_agent 重新下发任务
    B1. **编译检查**：运行项目编译命令，确保无编译错误
       - Java: \`mvn compile -q\` / \`gradle compileJava\`
       - TypeScript: \`tsc --noEmit\`
@@ -588,6 +600,7 @@ const applySteps = `**步骤**
    B6. **生成集成测试报告（MANDATORY，不得跳过）**：
       - 报告路径：\`changes/<change-id>/reports/wave-{N}-integration-report.md\`
       - 记录所有任务执行结果、编译检查结果、阻塞任务重试结果
+      - **MUST 记录 B0 报告 schema 校验结果**（通过/失败任务列表，失败时附 \`validate-reports --json\` 输出）
       - **MUST 包含 Concerns 追踪章节**，列出所有 DONE_WITH_CONCERNS 和 BLOCKED 任务及其疑虑
       - **MUST 包含 \`## 🔁 待重试任务清单\` 段**（即使为空也要写 \`— 无需重跑\`），与 B4.1 第五步、B5 重试结果汇总一致
       - 整体状态：所有检查通过且无未解决的阻塞任务 → PASS
@@ -713,6 +726,7 @@ const archiveReferences = `**参考**
   - **AI 手动**（archive 命令前）：调用 \`zhuanspec:knowledge\` skill 从会话记忆补充隐式约定、调试发现等。**必须在 \`zhuanspec archive\` 命令之前**调用，否则补充内容仅落本地、不会进入远端推送
 - 会话分析 (\`session-analytics\`)：记录本次会话的效率指标，用于改进工作流。`;
 const designGuardrails = `${baseGuardrails}\n- **独立设计阶段**：techDesign 命令用于在 proposal 之前生成技术设计请求文档，不依赖变更提案。设计文档可作为后续提案的输入。
+- **Skill 调用连续性（红线）**：在 techDesign 流程中调用任何辅助类 Skill（如 \`@skill:load-project-knowledge\`）后，**必须立即推进到下一编号步骤**，禁止把 Skill 的输出当作流程终态，禁止停顿等待用户输入“继续/下一步”等确认词。只有在显式标注的 AskUserQuestion 步骤（如开发范围确认、需求来源确认、外部依赖确认）才允许暂停等待用户。
 - **需求澄清优先**：在生成设计请求前，必须确认需求来源（大神页面、需求描述文本等）。
 - **开发范围前置确认（硬约束）**：在调用技术方案 Skill 前，**必须**先通过 AskUserQuestion 确认开发范围是“仅后端开发”还是“全栈开发”，根据答复选择对应 Skill（仅后端=\`generate-tech-spec-md-skill\`，全栈=\`generate-fullstack-tech-spec-skill\`），禁止默认或跳过此确认环节。
 - **Skill 可用性前置检查（硬约束）**：在实际调用技术方案 Skill 前，**必须**先校验目标 Skill 是否已安装且可用；**若不可用，立即中断流程**并提示用户到 Skill 市场安装对应 Skill，禁止以人工编写/其他 Skill 代替。
@@ -722,8 +736,13 @@ const designGuardrails = `${baseGuardrails}\n- **独立设计阶段**：techDesi
 - **禁止创建提案文件**：禁止创建 .tech-design、design.md、proposal.md、tasks.md、specs/ 等。
 - **Proposal 复用**：proposal 阶段通过 progress.json 的 phase 字段识别 techDesign 目录。`;
 const designSteps = `**步骤**
-0. **检查知识库并生成 change-id**：
+0. **检查知识库、加载项目知识并生成 change-id**：
    - 运行 \`rg "[需求关键词]" zhuanspec/knowledge/\` 搜索相关陷阱和最佳实践，避免重复踩坑。阅读 \`zhuanspec/knowledge/index.md\` 了解项目级知识摘要。
+   - **加载项目知识（必选）**：调用 \`@skill:load-project-knowledge\` 进行渐进式加载：
+     * 输入：domain（当前项目）、keywords（从需求描述提取的核心关键词）
+     * 获取：matched_services（涉及的服务列表）、search_priority（检索优先路径）、architecture_constraints（架构约束）
+     * 使用：后续技术方案设计需引用 matched_services 作为服务定位，方案设计需检查 architecture_constraints
+     * ⚠️ **连续性约束（红线）**：\`load-project-knowledge\` 完成并输出 matched_services 表后，**必须立即继续执行下面的“生成 change-id”子步骤以及步骤 1（Phase 初始化）**，禁止停顿等待用户输入“继续”。该 Skill 只是辅助加载，不是流程门禁。
    - **生成 change-id**（与 proposal 阶段命名规则一致）：
      * 从用户需求描述中提取核心动词和关键词
      * 格式：动词开头 + kebab-case 关词组合

package/dist/core/templates/tasks-template.js

@@ -191,18 +191,24 @@ Answer: <!-- user answer -->
 
 ### Wave 1（底层：DAO / 外部 Assemble）
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 1: Tasks with no dependencies, 层归属限定 dao/assemble/ddl/config -->
 
 - [ ] 1.1 <!-- Task description --> @layer:dao @skill:none <!-- 纯配置变更或手动操作 -->
 
 ### Wave 2（中间层：Domain / Application）
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 2: Tasks depending on Wave 1, 层归属限定 domain/application -->
 
 - [ ] 2.1 <!-- Task description --> @depends:1.1 @layer:domain @skill:none <!-- 无需特定 skill -->
 
 ### Wave 3（顶层：SCF / MQ / 定时任务 / 前端）
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 3: Tasks depending on Wave 2, 层归属限定 entry-scf/entry-mq-*/entry-job/fe -->
 
 - [ ] 3.1 <!-- Task description --> @depends:2.1 @layer:entry-scf @skill:none <!-- 无需特定 skill -->

package/dist/core/templates/tdd-tasks-template.js

@@ -153,6 +153,8 @@ Answer: <!-- user answer -->
 
 ### Wave 2
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent（优先 tddApplyAgent）执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 2: Red Phase - Write failing tests that define expected behavior -->
 <!-- 先写测试，测试应当初始失败 — 证明测试确实在验证有意义的行为 -->
 <!-- 每个测试任务必须使用类型A/B模板，明确测试文件路径、测试方法签名、断言内容 -->
@@ -162,6 +164,8 @@ Answer: <!-- user answer -->
 
 ### Wave 3
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent（优先 tddApplyAgent）执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 3: Green Phase - Write minimal code to make tests pass -->
 <!-- 编写最少代码使测试通过，每个任务必须使用类型A（新增）或类型B（修改）模板 -->
 
@@ -170,6 +174,8 @@ Answer: <!-- user answer -->
 
 ### Wave 4
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent（优先 tddApplyAgent）执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 4: Refactor Phase - Clean up code while keeping tests green -->
 <!-- 在保持测试通过的前提下重构，每个任务使用类型B模板标明修改位置 -->
 
@@ -178,6 +184,8 @@ Answer: <!-- user answer -->
 
 ### Wave 5
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 5: Documentation - Document the implemented feature -->
 
 - [ ] 5.1 <!-- 更新 API 文档 --> @depends:4.2 @skill:none <!-- justification: documentation task -->

package/dist/core/validation/report-schema.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Apply 阶段任务报告 schema 校验。
+ *
+ * 背景：编排 Agent 在长任务尾部容易"指令衰减"，跳过 Agent tool / spawn_agent
+ * 的 subagent 调用，自己在主线程顺手把任务做掉再补一份偷工的报告。这种偷工
+ * 报告会缺失 tdd-apply-agent.md / apply-agent.md 模板里强制的章节
+ * （TDD Phase / Verify RED / Verify GREEN / Mock Gate / Skill 调用记录 ...）。
+ *
+ * 本模块对 `zhuanspec/changes/<id>/reports/task-*.md` 做轻量结构校验：
+ * - 必备公共字段：`## 状态报告` / Status / Task ID / Report File / Agent 选择决策 / Agent 类型
+ * - 当 Agent 类型 = `tddApplyAgent`：再校验 TDD Phase / 上下文就绪摘要 /
+ *   验收点映射表 / TDD 执行过程（Verify RED + Verify GREEN）/ 测试运行结果 /
+ *   Self-Review 发现 / Issues
+ * - 当 Agent 类型 = `applyAgent`：校验实施内容 / 修改文件 / Self-Review 发现 / Issues
+ *
+ * 与 tasks.md 交叉对账：若任务在 tasks.md 里带 `@test-case:TC-XXX`，则该任务的
+ * 报告原则上必须由 `tddApplyAgent` 产出（除非报告里显式声明降级原因，对应
+ * apply-agent.md 中的"降级使用 applyAgent"路径）。
+ */
+export type ReportAgentType = 'tddApplyAgent' | 'applyAgent' | 'unknown';
+export interface ReportIssue {
+    level: 'ERROR' | 'WARNING';
+    taskId: string;
+    message: string;
+}
+export interface SingleReportResult {
+    /** Task id parsed from filename, e.g. "1.1". */
+    taskId: string;
+    /** Absolute path to the report file. */
+    filePath: string;
+    /** Agent type declared inside report, or 'unknown' when absent. */
+    declaredAgentType: ReportAgentType;
+    /** Agent type expected from tasks.md (`@test-case` ⇒ tddApplyAgent). */
+    expectedAgentType: ReportAgentType;
+    /** Whether the report has a downgrade justification (i.e. claims "降级"/"不适合 TDD"). */
+    hasDowngradeJustification: boolean;
+    /** Section / field names that were required but not found. */
+    missing: string[];
+    /** Issues collected for this report. */
+    issues: ReportIssue[];
+    /** Whether the report passes schema validation. */
+    valid: boolean;
+}
+export interface ReportSchemaSummary {
+    changeId: string;
+    reportsDir: string;
+    /** Total reports inspected. */
+    totalReports: number;
+    /** Reports passing all schema checks. */
+    passedReports: number;
+    /** Reports failing schema checks. */
+    failedReports: number;
+    /** Tasks in tasks.md that have no report file at all. */
+    missingReports: string[];
+    /** Per-report results. */
+    reports: SingleReportResult[];
+    /** Overall validity (no ERROR-level issues + no missing reports). */
+    valid: boolean;
+}
+/**
+ * Inspect a single report file. Pure string-level checks — no side effects.
+ *
+ * @param taskId  The task id (derived from filename).
+ * @param content The raw markdown content of the report file.
+ * @param expected The agent type expected from tasks.md (default 'unknown').
+ */
+export declare function checkReportContent(taskId: string, filePath: string, content: string, expected: ReportAgentType): SingleReportResult;
+/**
+ * Validate all task reports under `<changeDir>/reports/`.
+ * Cross-checks against `<changeDir>/tasks.md` to detect missing reports and
+ * agent-type mismatches.
+ */
+export declare function validateTaskReports(changeDir: string): Promise<ReportSchemaSummary>;
+//# sourceMappingURL=report-schema.d.ts.map