sillyspec 3.28.7 → 3.28.9

package/src/stage-contract.js

@@ -123,7 +123,12 @@ function buildDecisionRecord(id, body) {
   const supersedes = supersedesRaw
     ? supersedesRaw.split(',').map(s => s.trim().toUpperCase().replace(/['"]/g, '')).filter(Boolean)
     : []
-  return { id: id.toUpperCase(), body, status, priority, blocker, priorityMissing, supersedes }
+  // 故障面/退役判据（FR-01/D-001@v1，2026-09-15-tax-governance）：自维护税治理字段，
+  // 软警告素材（warnMissingGovernanceFields）——type 缺省为 ''（非 architecture 不警告）
+  const type = readDecisionField(body, 'type').toLowerCase()
+  const failureMode = readDecisionField(body, '故障面')
+  const retireWhen = readDecisionField(body, '退役判据')
+  return { id: id.toUpperCase(), body, status, priority, blocker, priorityMissing, supersedes, type, failureMode, retireWhen }
 }
 
 function findNextDecisionBoundary(content, startIndex) {
@@ -233,6 +238,22 @@ function warnMissingIds(warnings, ids, targetContent, targetName, sourceName) {
   }
 }
 
+/**
+ * 故障面/退役判据软警告（FR-01/D-001@v1，change: 2026-09-15-tax-governance）：
+ * type=architecture 且 status=accepted 的条目缺任一字段 → warnings.push（不阻断）。
+ * 机制落地时被迫留痕「它引入什么失败模式、什么信号出现就该简化它」；definition/boundary
+ * 等其他类型不要求。扫描无法区分新旧条目（design R-03）——文案标注存量可忽略，
+ * 软警告不升 error（一个观测周期后再评估棘轮升级，D-001 退役判据锚定）。
+ */
+function warnMissingGovernanceFields(warnings, decisionsContent) {
+  if (!decisionsContent) return
+  for (const r of parseDecisionRecords(decisionsContent)) {
+    if (r.type !== 'architecture' || r.status !== 'accepted') continue
+    if (r.failureMode && r.retireWhen) continue
+    warnings.push(`decisions.md ${r.id}（architecture）缺「故障面/退役判据」——新决策建议补齐（存量条目可忽略）`)
+  }
+}
+
 /**
  * scan 完成校验：检查 7 份 scan 文档 + manifest
  */
@@ -356,6 +377,9 @@ function validateBrainstormOutputs(cwd, changeName, context = {}) {
       // tasks（骨架，待 plan 展开）不强求逐条引用每个架构决策，否则批量误报。
       warnMissingIds(warnings, decisionIds, design, 'design.md', 'decisions.md')
     }
+    // 故障面/退役判据软警告（FR-01，2026-09-15-tax-governance）：architecture+accepted 缺字段
+    // → warning 不阻断（经 gates warnings 通道打印，gates.js 零改动）
+    warnMissingGovernanceFields(warnings, decisions)
   }
 
   return { ok: errors.length === 0, errors, warnings }
@@ -397,6 +421,8 @@ function validatePlanOutputs(cwd, changeName, context = {}) {
     }
     const decisionIds = extractCurrentDecisionIds(decisions)
     warnMissingIds(warnings, decisionIds, plan, 'plan.md', 'decisions.md')
+    // 故障面/退役判据软警告（FR-01，2026-09-15-tax-governance）：brainstorm 侧同款（软警告不阻断）
+    warnMissingGovernanceFields(warnings, decisions)
   }
   // ── P0: 生产接线路径检查：design 提到入口但 task 的 allowed_paths 不含入口文件 ──
   // entry-point-wiring(custom):trigger/file 抽取/exemption/failMessage 从 manifest 同源
@@ -689,6 +715,161 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
+// ============ 探针 7 验收×测试覆盖矩阵门禁（2026-09-14-acceptance-test-matrix FR-02） ============
+// 段格式与 src/verify-probes.js renderProbe7Lines 骨架渲染字面同源（禁第二套解析文法）：
+// 段标题「#### 探针 7：验收×测试覆盖矩阵」（全/半角冒号皆认）；每 task 前 **task-NN** 锚行；
+// 五列表 | acceptance 条目 | 归属测试文件 | 关键词命中 | 判定 | 证据 |；判定槽 <待填：四选一>、
+// 证据槽 <TODO>；列表防御行（卡无 acceptance…）与不适用行无槽不计。
+
+/** 判定列四枚举白名单（骨架口径注记字面同源） */
+const MATRIX_VERDICT_WHITELIST = new Set(['covered', 'partial', 'uncovered', 'non-testable'])
+/** 证据列未填占位（骨架字面同源） */
+const MATRIX_EVIDENCE_TODO = '<TODO>'
+
+/**
+ * 切分 markdown 表格行：按未转义管道切列（`\|` 是单元格内字面量，切列须忽略），
+ * 行首管道消费、行尾有管道则末段为收尾空段不产列。非 | 起始行返回 null。
+ * @returns {string[]|null} 单元格数组（未 trim）；null = 非表行
+ */
+function splitMatrixRowCells(line) {
+  const s = String(line).trim()
+  if (!s.startsWith('|')) return null
+  const cells = []
+  let cur = ''
+  for (let i = 1; i < s.length; i++) {
+    const ch = s[i]
+    if (ch === '\\' && s[i + 1] === '|') { cur += '|'; i++; continue }
+    if (ch === '|') { cells.push(cur); cur = ''; continue }
+    cur += ch
+  }
+  if (!s.endsWith('|')) cells.push(cur) // 行尾缺管道的宽容形态：尾段仍是单元格
+  return cells
+}
+
+/**
+ * covered/partial 行证据是否含测试锚点形态之一：`.test.` 文件名 / file:line（x.js:123）/
+ * 反引号包裹的标识符（骨架归属列即反引号路径，agent 引用复制即命中）。
+ */
+function matrixEvidenceHasAnchor(evidence) {
+  const e = String(evidence || '')
+  if (e.includes('.test.')) return true
+  if (/[A-Za-z0-9_\-./\\]+\.[A-Za-z0-9]+:\d+/.test(e)) return true
+  if (/`[^`]+`/.test(e)) return true
+  return false
+}
+
+/**
+ * 行级证据口径：covered/partial 须非 TODO 且含测试锚点；non-testable 须非 TODO 且非空
+ * （一句话理由）；uncovered 无证据要求；判定未填（不在三枚举内）的行只计 unfilled 不重复计证据。
+ */
+function matrixEvidenceMissing(verdict, evidence) {
+  if (verdict !== 'covered' && verdict !== 'partial' && verdict !== 'non-testable') return false
+  const e = String(evidence || '').trim()
+  if (e === '' || e === MATRIX_EVIDENCE_TODO || e.startsWith('<待填')) return true
+  if (verdict === 'non-testable') return false // 非 TODO 且非空即合规（理由一句话）
+  return !matrixEvidenceHasAnchor(e)
+}
+
+/**
+ * 行级提取 verify-result.md「#### 探针 7：验收×测试覆盖矩阵」段的判定/证据槽（纯字符串解析）。
+ * 段定位：探针 7 标题（全/半角冒号）到下个同级（####）或更高级（#~###）标题；##### 属段内。
+ * 只认五列表行（按忽略 \| 转义切列）；表头/分隔行、**task-NN** 锚行、列表防御行与
+ * 「不适用（无 TaskCard）」行不计槽。
+ * @param {string} verifyMd - verify-result.md 全文
+ * @returns {{
+ *   present: boolean,
+ *   rows: Array<{task: string, acceptance: string, verdict: string, evidence: string, unfilled?: boolean, evidenceMissing?: boolean}>,
+ *   unfilled: number,
+ *   missingEvidence: number
+ * }} 无段时 present=false、rows=[]、计数 0/0（调用方区分「无段」与「段在而未填」）
+ */
+export function extractAcceptanceMatrixSlots(verifyMd) {
+  const md = String(verifyMd || '')
+  const out = { present: false, rows: [], unfilled: 0, missingEvidence: 0 }
+  const hm = md.match(/^#### 探针 7[：:]/m)
+  if (!hm) return out
+  out.present = true
+  const rest = md.slice(hm.index + hm[0].length)
+  const endMatch = rest.match(/^#{1,4}(?:[ \t]|$)/m)
+  const sectionText = endMatch ? rest.slice(0, endMatch.index) : rest
+
+  let currentTask = ''
+  for (const rawLine of sectionText.split(/\r?\n/)) {
+    const anchor = rawLine.match(/^\*\*\s*(task-[A-Za-z0-9._-]+)\s*\*\*/)
+    if (anchor) { currentTask = anchor[1]; continue }
+    const cells = splitMatrixRowCells(rawLine)
+    if (!cells || cells.length !== 5) continue // 列表防御行/不适用行/非五列表行不计槽
+    const c = cells.map(x => x.trim())
+    if (c.every(x => /^:?-{3,}:?$/.test(x))) continue // 分隔行 |---|---|…|
+    if (c[3] === '判定' && c[4] === '证据') continue // 表头行
+    const verdict = c[3]
+    const evidence = c[4]
+    const row = { task: currentTask, acceptance: c[0], verdict, evidence }
+    if (!MATRIX_VERDICT_WHITELIST.has(verdict)) { row.unfilled = true; out.unfilled++ }
+    if (matrixEvidenceMissing(verdict, evidence)) { row.evidenceMissing = true; out.missingEvidence++ }
+    out.rows.push(row)
+  }
+  return out
+}
+
+/**
+ * 探针 7 矩阵门禁 validator（注册 contracts.verify.validators，走 runValidators errors
+ * 阻断链——勿进 gates.js fail-soft 回填块，catch 只 warn 会吞阻断）：
+ *   - 无 tasks/ 目录（quick 会话/旧变更，无 TaskCard）→ no-op 零行为变化
+ *   - verify-result.md 未落盘（verify 中间步骤）→ no-op：存在性归引擎 manifest，此处只读已落盘内容
+ *   - 段缺失：严格档（isIrStrictVerifyChange / IR_STRICT_SINCE 同源常量，与结论槽
+ *     「删槽回退已关闭」同口径）ERROR；非严格（存量变更）warning 提示补段不阻断
+ *   - 段在场：unfilled / missingEvidence > 0 → ERROR 列出违规行（task+acceptance 截断 40 字）
+ */
+function validateAcceptanceMatrix(cwd, changeName, context = {}) {
+  const { specRoot } = context
+  const errors = []
+  const warnings = []
+  const changeDir = resolveChangeDir(cwd, changeName, specRoot)
+
+  // 无 TaskCard（tasks/ 不存在）→ 不校验（设计兼容策略：brownfield 零行为变化）
+  if (!existsSync(join(changeDir, 'tasks'))) return { ok: true, errors, warnings }
+  // verify-result.md 中间步骤未落盘 → 不校验（末步引擎存在性规则兜底）
+  const verifyResultPath = join(changeDir, 'verify-result.md')
+  if (!existsSync(verifyResultPath)) return { ok: true, errors, warnings }
+
+  const matrix = extractAcceptanceMatrixSlots(readFileSync(verifyResultPath, 'utf8'))
+  if (!matrix.present) {
+    if (isIrStrictVerifyChange(changeDir)) {
+      errors.push(
+        `探针 7 矩阵段缺失（有 TaskCard 且严格档，created_at ≥ ${IR_STRICT_SINCE}）——` +
+        `verify-result.md 缺「#### 探针 7：验收×测试覆盖矩阵」段。` +
+        `修复：跑 \`sillyspec verify-probes --change ${changeName} --init\` 幂等补段（已有正文不覆盖），再逐行填判定与证据。`
+      )
+    } else {
+      warnings.push(
+        `verify-result.md 缺探针 7 验收×测试覆盖矩阵段（非严格档，存量变更不强制）——` +
+        `可跑 \`sillyspec verify-probes --change ${changeName} --init\` 幂等补段。`
+      )
+    }
+    return { ok: errors.length === 0, errors, warnings }
+  }
+
+  const clip = (s) => { const t = String(s || ''); return t.length > 40 ? t.slice(0, 40) + '…' : t }
+  const rowLabel = (r) => `${r.task || '（未知 task）'}｜${clip(r.acceptance)}`
+  if (matrix.unfilled > 0) {
+    const list = matrix.rows.filter(r => r.unfilled).map(rowLabel).join('；')
+    errors.push(
+      `探针 7 验收×测试覆盖矩阵有 ${matrix.unfilled} 行判定未填（四选一 covered/partial/uncovered/non-testable）：${list}。` +
+      `修复：编辑 verify-result.md 探针 7 段，把 <待填：四选一> 替换为判定值。`
+    )
+  }
+  if (matrix.missingEvidence > 0) {
+    const list = matrix.rows.filter(r => r.evidenceMissing).map(rowLabel).join('；')
+    errors.push(
+      `探针 7 验收×测试覆盖矩阵有 ${matrix.missingEvidence} 行证据缺失` +
+      `（covered/partial 证据须含测试锚点：\`.test.\` 文件名 / file:line / 反引号包裹的测试名；non-testable 证据须写一句理由）：${list}。` +
+      `修复：在证据列补测试锚点（如 \`test/foo.test.mjs\` 或 \`src/x.js:42\`）或 non-testable 理由。`
+    )
+  }
+  return { ok: errors.length === 0, errors, warnings }
+}
+
 /**
  * 计算归档目标目录名：保持原变更名不变，直接移入 archive/。
  */
@@ -881,7 +1062,9 @@ const contracts = {
     description: '验证与测试',
     allowedFrom: ['execute'],
     allowedTo: ['archive'],
-    validators: [validateVerifyOutputs],
+    // validateAcceptanceMatrix：探针 7 矩阵槽 fail-closed（2026-09-14-acceptance-test-matrix FR-02），
+    // 注册进 validator 链即覆盖 gates / machine-interface 等全部 runValidators 调用方（gates.js 零改动）。
+    validators: [validateVerifyOutputs, validateAcceptanceMatrix],
   },
   archive: {
     stage: 'archive',

package/src/stage-review.js

@@ -13,7 +13,8 @@
  *   （平台模式落 <runtimeRoot>/stage-reviews/...，与 execute-runs 同构）
  */
 
-import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs'
+import { writeAtomicSync } from './fs-atomic.js'
 import { join } from 'path'
 import { createHash } from 'crypto'
 import jsYaml from 'js-yaml'
@@ -199,10 +200,17 @@ export function computeDocHash(filePath) {
  *   - 新增 reviewType（design/plan/proposal/code/acceptance）+ checklist
  *   - 复用 VALID_VERDICTS 三态 + cannot_verify 联动规则（task-review.js:65-69）
  *
+ * ql-20260915-001 修复③（坑 stage-review-type-error-no-expected，2026-09-14 用户实证：写错
+ * reviewType 时报错只列全部合法值不说本 stage 期望什么，试错才发现）：可选 stage 入参——
+ * 提供时 reviewType / reviewedFiles 缺失类错误同时给出本 stage 的期望值（期望 reviewType 取
+ * STAGE_REVIEW_TYPE[stage]、期望主文档取 STAGE_MAIN_DOC[stage]），消错一次到位。不提供时
+ * 报错文案与旧版一致（向后兼容，含 test 直接调用）。
+ *
  * @param {object} review - 解析后的 JSON 对象
+ * @param {string} [stage] - brainstorm|plan|execute（错误文案给期望值用；不影响判定逻辑）
  * @returns {{ ok: boolean, errors: string[] }}
  */
-export function validateStageReviewSchema(review) {
+export function validateStageReviewSchema(review, stage = null) {
   const errors = []
   if (!review || typeof review !== 'object') {
     return { ok: false, errors: ['stage review.json 不是有效 JSON 对象'] }
@@ -213,7 +221,11 @@ export function validateStageReviewSchema(review) {
   }
 
   if (!STAGE_REVIEW_TYPES.includes(review.reviewType)) {
-    errors.push(`reviewType 无效：${review.reviewType}（应为 ${STAGE_REVIEW_TYPES.join('/')}）`)
+    // ql-20260915-001 修复③：合法值之外同时给本 stage 期望——agent 不用从 5 个合法值里试错
+    const expectedType = stage && STAGE_REVIEW_TYPE[stage]
+    errors.push(expectedType
+      ? `reviewType 无效：${review.reviewType}（本 stage=${stage} 期望 "${expectedType}"；合法值 ${STAGE_REVIEW_TYPES.join('/')}）`
+      : `reviewType 无效：${review.reviewType}（应为 ${STAGE_REVIEW_TYPES.join('/')}）`)
   }
 
   if (!VALID_VERDICTS.includes(review.specVerdict)) {
@@ -232,7 +244,11 @@ export function validateStageReviewSchema(review) {
 
   // reviewedFiles 必须是非空数组
   if (!Array.isArray(review.reviewedFiles) || review.reviewedFiles.length === 0) {
-    errors.push('缺少 reviewedFiles 字段（应为被审查文档路径数组，[0] 为主审查对象，docHash 对应它）')
+    // ql-20260915-001 修复③顺手补：同款缺期望值问题——给本 stage 的主审查文档示例
+    const expectedDoc = stage && STAGE_MAIN_DOC[stage]
+    errors.push(expectedDoc
+      ? `缺少 reviewedFiles 字段（应为被审查文档路径数组，[0] 为主审查对象——本 stage=${stage} 期望主文档 ${expectedDoc}（如 changes/<变更名>/${expectedDoc}），docHash 对应它）`
+      : '缺少 reviewedFiles 字段（应为被审查文档路径数组，[0] 为主审查对象，docHash 对应它）')
   }
 
   // docHash 非空
@@ -479,7 +495,8 @@ export function validateStageReview(opts) {
     return { ok: false, errors: [`${stage} review.json 解析失败: ${e.message}`], warnings, review: null }
   }
 
-  const schemaResult = validateStageReviewSchema(parsed)
+  // ql-20260915-001 修复③：透传 stage——schema 错误文案给本 stage 期望值
+  const schemaResult = validateStageReviewSchema(parsed, stage)
   if (!schemaResult.ok) {
     return { ok: false, errors: [`${stage} review.json schema 校验失败 — ${schemaResult.errors.join('; ')}`], warnings, review: parsed }
   }
@@ -561,7 +578,7 @@ export function validateStageReviewWithAutoRefresh(opts) {
     reviewerNotes: `${result.review.reviewerNotes || ''}\ndocHash auto-refreshed at ${refreshedAt}（gate 检测主文档改版，机械重算；verdict 保留，结论是否仍适用需人工确认）`.trim(),
   }
   try {
-    writeFileSync(reviewPath, JSON.stringify(refreshed, null, 2) + '\n')
+    writeAtomicSync(reviewPath, JSON.stringify(refreshed, null, 2) + '\n')
   } catch {
     return { result, autoRefreshed: false } // 写失败回落原失败结果，不静默放行
   }
@@ -698,8 +715,8 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
       reviewedFiles,
       reviewerNotes: `${existing.reviewerNotes || ''}\ndocHash refreshed at ${refreshedAt}（主文档改版后机械重算；verdict 结论是否仍适用需人工确认）`.trim(),
     }
-    writeFileSync(existingPath, JSON.stringify(review, null, 2) + '\n')
-    const schemaRecheck = validateStageReviewSchema(review)
+    writeAtomicSync(existingPath, JSON.stringify(review, null, 2) + '\n')
+    const schemaRecheck = validateStageReviewSchema(review, stage)
     if (!schemaRecheck.ok) {
       throw new Error(`register-stage-review: refresh 后 schema 自检失败 — ${schemaRecheck.errors.join('; ')}（原 review 字段异常，先修原文件）`)
     }
@@ -724,7 +741,7 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
     } catch (e) {
       throw new Error(`register-stage-review: --from 文件 JSON 解析失败 ${fromAbs}: ${e.message}`)
     }
-    const schemaResult = validateStageReviewSchema(parsed)
+    const schemaResult = validateStageReviewSchema(parsed, stage)
     if (!schemaResult.ok) {
       throw new Error(`register-stage-review: --from 文件 schema 校验失败 — ${schemaResult.errors.join('; ')}`)
     }
@@ -750,7 +767,7 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
   const reviewDir = join(runtimeRoot, 'stage-reviews', `${stage}-${reviewRunId}`)
   const reviewPath = join(reviewDir, 'review.json')
   mkdirSync(reviewDir, { recursive: true })
-  writeFileSync(reviewPath, JSON.stringify(review, null, 2) + '\n')
+  writeAtomicSync(reviewPath, JSON.stringify(review, null, 2) + '\n')
   // stage-reviews 回收不在此处（ql-20260908-005 已定分野）：变更归属类证据走归档时精确
   // 回收（pruneArchivedChangeRuntime 按 reviewedFiles 归属）；写入侧滚动是启发式，
   // 活跃变更的 review 可能因他端高频写而跌出 keep 窗，不进证据类目录。
@@ -760,11 +777,11 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
     console.warn(`⚠️ register-stage-review: marker 已存在 ${markerPath}，将被覆盖为 ${reviewRunId}`)
   }
   mkdirSync(runtimeRoot, { recursive: true })
-  writeFileSync(markerPath, reviewRunId + '\n')
+  writeAtomicSync(markerPath, reviewRunId + '\n')
 
   // self-check（fail-closed）：刚写的 review 必过 schema + docHash 真实性。只验 mechanics，
   // 不判 verdict（verdict 是 agent/子代理的审查结论，even fail 也如实落盘，由 Stage Review Gate 裁决）。
-  const schemaRecheck = validateStageReviewSchema(review)
+  const schemaRecheck = validateStageReviewSchema(review, stage)
   if (!schemaRecheck.ok) {
     throw new Error(`register-stage-review: 写入后 schema 自检失败（不应发生）— ${schemaRecheck.errors.join('; ')}`)
   }

package/src/stages/brainstorm.js

@@ -173,6 +173,8 @@ export const definition = {
 - normalized_requirement: <可测试的约束>
 - impacts: [FR-?, task-?, verify-?]
 - evidence: <文件路径/代码位置/用户回答轮次>
+- 故障面: <本决策引入的新失败模式>（可选，type=architecture 时建议填写）
+- 退役判据: <出现什么信号时简化/删除本机制>（可选，type=architecture 时建议填写）
 \`\`\`
 
 - 幂等：写入前按 D-xxx@vN 查重，已存在的不重复追加；后续修正走新版本 D-001@v2 + supersedes（见 Design Grill 版本规则）
@@ -293,7 +295,7 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
    - 仅改内部实现、无对外字段变动时，说明列照常写「新增 xx 方法」即可，无需数据流。
 
    **跨仓变更写法**（本次变更涉及 local.yaml repos: 注册的其他仓时必读；纯主仓变更跳过）：
-   - 清单**按仓分段**：每个仓一个小节，标题格式固定 \`## <repo-key> 仓变更\`（如 \`## sub-grid-security 仓变更\`）。plan-postcheck 文件覆盖对账按此段头解析仓归属，写成「前端仓 / backend」等其他标题 → 对账不上
+   - 清单**按仓分段**：每个仓一个小节，标题格式固定 \`## <repo-key> 仓变更\`（如 \`## sub-grid-security 仓变更\`；可加编号前缀或（跨仓，X1-X4）这类括号备注后缀，其余后缀/写法解析不了）。plan-postcheck 文件覆盖对账按此段头解析仓归属，写成「前端仓 / backend」等其他标题 → 对账不上且会点名段头格式错误
    - 段内路径相对**该仓根**写（\`src/routes/x.js\`）；❌ 禁止带仓库名前缀（\`sub-grid-security/src/routes/x.js\`）、❌ 禁止绝对路径/盘符路径（\`C:/repo/src/...\`）——后续 TaskCard 的 allowed_paths 与 review 对账（\`git -C <仓根> diff\` 产仓根相对路径）都用同一口径，前缀/绝对路径永不命中
    - 主仓文件放在第一个段头之前（无段头区域 = main），或单独写 \`## main 仓变更\` 段
    - repo-key 必须是 local.yaml repos: 段已注册的键（未注册先跑 \`sillyspec local register-repo <key> <仓根路径>\`，main 隐式不用注册）
@@ -434,6 +436,8 @@ ${REVIEW_CHECKLISTS.brainstorm.slice(3).map((item) => '- ' + item).join('\n')}
 - normalized_requirement: TTL 过期且上游仍异常时返回 stale 标记，不刷新缓存。
 - impacts: [FR-02, task-03, verify-02]
 - evidence: design.md §3/§7, src/cache/...
+- 故障面: <本决策引入的新失败模式>（可选，type=architecture 时建议填写）
+- 退役判据: <出现什么信号时简化/删除本机制>（可选，type=architecture 时建议填写）
 \`\`\`
 
 ### 输出格式
@@ -590,6 +594,8 @@ created_at: <now-datetime>
 - evidence: 用户回答轮次或代码/文档路径
 \`\`\`
 
+> 可选字段（按需另加，旧格式决策缺这些字段不受影响）：**锚点**（决策落点主文件，\`<src 路径>:<行号或符号>\`；status=confirmed 时必填）；**模块域**（决策涉及的模块 ID，可多个逗号分隔——合法 id 只取**当前变更所属项目**的 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`，多项目仓勿读其他子项目的 map（核验不认，报错会点名归属）；规划中的新模块用 \`NEW:<名>\` 前缀声明，冒号后不加空格：\`NEW:foo\` 合法、\`NEW: foo\` 属书写错误。本步 --done 的模块域核验对不认识的 id 直接阻断）；**否决理由**（status=rejected 时必填）；**复潮条件**（status=rejected 时必填）；**故障面**（本决策引入的新失败模式——新机制落地时留痕它引入什么失败模式；type=architecture 时建议填写，可选）；**退役判据**（出现什么信号时简化或删除本机制——信号出现就该简化它；type=architecture 时建议填写，可选）。
+
 ### 后续变更包处理
 如果 MASTER.md 中规划了后续变更包（拆分后的子阶段），**必须同时为每个后续包创建独立变更目录**：
 1. 读取 MASTER.md 中的变更包列表（包名 + 边界描述）

package/src/stages/execute.js

@@ -15,6 +15,84 @@ import { resolveChangeModuleCards } from '../module-resolve.js'
 // 决策锚点触碰事实（2026-08-24-decision-touch-cli-drift task-01，W-A 主渲染点 D-003）：
 // changedFiles 口径与 {DOCS_DEBT} 现算同源（collectExecuteChangedFiles 唯一实现，勿双写）
 import { collectExecuteChangedFiles, computeDecisionTouches, renderDecisionTouchFacts } from '../docs-debt.js'
+// Wave 粒度机械知识注入（2026-09-14-knowledge-loop-close task-04，FR-04）：两模块均为 fs/path
+// 叶子，无环。为什么不 import run/prompt.js 的 buildKnowledgeInjection：prompt.js → stages/index.js
+// → 本文件的既有依赖方向（run 编排 stages），本文件反向静态 import 会在「本文件作模块图入口」
+// （test 直 import 本文件皆此形态）触发 stages/index.js 顶层 stageRegistry 对本文件 definition
+// const 的 TDZ 求值（ESM 环实证 2026-09-14）。此处为同格式本地孪生，漂移由
+// test/knowledge-inject.test.mjs 格式等价断言锁定——改 prompt.js 版必同步改此处。
+import { matchKnowledge } from '../knowledge-match.js'
+import { appendKnowledgeHit } from '../knowledge-hits.js'
+
+// 机械知识注入限额（与 run/prompt.js KNOWLEDGE_INJECT_MAX_FILES/MAX_LINES 同值孪生，R-02 膨胀控制）
+const KNOWLEDGE_INJECT_MAX_FILES = 3
+const KNOWLEDGE_INJECT_MAX_LINES = 40
+
+/**
+ * Wave 粒度机械知识注入段（task-04，FR-04 / D-002@v1 总体方案 D）：用本 Wave 各 task 标题拼接
+ * 串跑 matchKnowledge，命中文件正文以纯文本段注入 buildWavePrompt 输出（**禁止 {{include:}} 形式**
+ * ——execute-testcase-design-include.test.mjs:74 include 计数恰为 1 的断言约束）。未命中返回 ''
+ * （零字节零变化）。命中同时 appendKnowledgeHit 落 hits.jsonl 一条 type:inject 记录。
+ * best-effort：任何异常返回 ''，不阻断 Wave prompt 组装（INDEX/knowledge 缺失时 matchKnowledge
+ * 本就返回 matched:false，brownfield no-op）。
+ */
+function buildWaveKnowledgeSection(changeDir, wave) {
+  if (!changeDir) return ''
+  try {
+    const specBase = path.dirname(path.dirname(changeDir))
+    const knowledgeDir = path.join(specBase, 'knowledge')
+    // Wave 任务名串：本 Wave 各 task 标题拼接（buildWavePrompt 唯一稳定的 Wave 级任务语料）
+    const query = (Array.isArray(wave && wave.tasks) ? wave.tasks : [])
+      .map(t => String((t && t.name) || '')).filter(Boolean).join(' ')
+    if (!query.trim()) return ''
+    const result = matchKnowledge(knowledgeDir, query)
+    if (!result.matched) return ''
+    // ── 以下与 run/prompt.js renderKnowledgeInjectSection 同格式孪生（含段头文案/截断标记）──
+    const ref = e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)
+    const lines = []
+    lines.push(`### 📚 命中知识（CLI 按 Wave 任务名机械匹配，top-${KNOWLEDGE_INJECT_MAX_FILES}——勿自行重跑 INDEX 匹配）`)
+    lines.push(`Status: matched | Entries: ${result.entries.length} | Sources:`)
+    for (const e of result.entries) lines.push(` - ${ref(e)}`)
+    lines.push(`（命中清单如上；正文按 INDEX 行序注入前 ${KNOWLEDGE_INJECT_MAX_FILES} 个不同文件，单文件首 ${KNOWLEDGE_INJECT_MAX_LINES} 行截断——未注入条目需要时按 Sources 路径自行读取）`)
+    const seen = new Set()
+    const picked = []
+    for (const e of result.entries) {
+      if (seen.has(e.file)) continue
+      seen.add(e.file)
+      picked.push(e)
+      if (picked.length >= KNOWLEDGE_INJECT_MAX_FILES) break
+    }
+    for (const e of picked) {
+      lines.push('')
+      lines.push(`── ${ref(e)}${e.display ? `（${e.display}）` : ''} ──`)
+      let body = ''
+      try {
+        body = readFileSync(path.join(knowledgeDir, e.file), 'utf8').replace(/\r\n?/g, '\n')
+      } catch (err) {
+        lines.push(`（文件不可读：${err && err.message ? err.message : err}）`)
+        continue
+      }
+      const bodyLines = body.split('\n')
+      if (bodyLines.length > KNOWLEDGE_INJECT_MAX_LINES) {
+        lines.push(bodyLines.slice(0, KNOWLEDGE_INJECT_MAX_LINES).join('\n'))
+        lines.push('…（截断）')
+      } else {
+        lines.push(body.replace(/\n+$/, ''))
+      }
+    }
+    try {
+      appendKnowledgeHit(path.join(specBase, '.runtime'), {
+        type: 'inject',
+        change: path.basename(changeDir),
+        query,
+        matchedFiles: result.entries.map(ref),
+      })
+    } catch { /* 遥测 fail-soft（R-04） */ }
+    return lines.join('\n') + '\n'
+  } catch {
+    return ''
+  }
+}
 
 /**
  * 任务注册表解析（2026-08-20-task-truth-unify D-001@v1：tasks.md 唯一任务真相）。
@@ -311,12 +389,12 @@ worktree 路径 + 分支名 + 模式
 1. 从 plan 中解析 Wave 分组和任务列表
 2. 模型档位：若 tasks.md 中某 task 标注了 [model:xxx]，启动该 task 子代理时按标签选模型（档位由 plan 阶段或用户在 tasks.md 显式标注，execute 不在此自动建议——关键词→档位无统一映射，自动建议反而易误导）
 3. 确认频率：默认每个 Wave 完成后展示结果（wave 模式）；用户口头指定按 Task 展示或全自动时遵从
-4. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
+4. 知识库：CLI 已按任务上下文机械匹配（changeName + tasks.md 任务行）——命中时下方「知识命中报告」段直接含命中文件正文（top-3 截断），勿自行重跑 INDEX 匹配；无命中且确有需要时才读 \`.sillyspec/knowledge/INDEX.md\`
 
 ### 知识命中报告
 {KNOWLEDGE_HIT_REPORT}
 
-如上所示的知识条目与本次任务相关。请阅读这些条目以获取项目约定和已知模式。
+命中条目正文已由 CLI 机械注入如上（INDEX 行序 top-3 不同文件、单文件截断）——直接阅读获取项目约定与已知模式；Sources 清单中未注入正文的其他命中条目，需要时按路径自行读取。
 如无命中条目（Status: no matches），跳过本节。
 
 ### 模块文档欠账（CLI 算事实）
@@ -956,6 +1034,10 @@ ${indexLines}
     }
   } catch { /* 触碰事实 best-effort：失败不注入不阻断 */ }
 
+  // ── Wave 粒度机械知识注入（task-04，FR-04）：Wave 任务名串匹配 → 命中正文纯文本段（未命中 ''，
+  // Wave prompt 与无知识库时字节一致）。pure text 注入，禁 {{include:}}（include 计数测试约束）。──
+  const waveKnowledgeSection = buildWaveKnowledgeSection(changeDir, wave)
+
   // 子代理要点 4 / Wave 开始前第 1 条：模块表 / 热区存在时换成「按注入内容执行」版文案，
   // 否则保留原文（零回归——无 map / 无 design 的项目 prompt 不变）
   const moduleDocPoint = moduleSection
@@ -1074,6 +1156,10 @@ ${crossLines}${crossWorktreeSection}${crossLegacySection}
       `  - task-${i.taskNum} (repo: ${i.repo}) → workdir: "${i.workdir}"`
     ).join('\n')
     worktreeSection = `
+### task 进行中标记（中断续跑的半成品归属，2026-09-12 起）
+
+每个 task **开工/完工各跑一条命令**（低摩擦，主代理或子代理均可）：开工「sillyspec task start --change {CHANGE_NAME} --task task-NN --note 一句话在做什么」；完工「sillyspec task finish --change {CHANGE_NAME} --task task-NN」。中断续跑时主代理用「sillyspec task list --change {CHANGE_NAME}」点名接管（>2h 标红为中断遗留），不再靠翻 git 工作区猜哪个半成品是谁的。
+
 ### 工作目录（per-task）
 
 调用 Task 工具启动子代理时，**workdir 参数是强制必传的**，且本 Wave 内不同 task 的 workdir 不同（主仓 task vs 跨仓 task）。
@@ -1184,7 +1270,7 @@ ${taskSummary}
 
 {{include: testcase-design}}
 
-${designHotzone}${decisionTouchSection}
+${designHotzone}${decisionTouchSection}${waveKnowledgeSection}
 ### Wave 开始前
 ${waveStartItem1}
 2. 读取 plan.md 了解全局任务划分和依赖关系
@@ -1213,7 +1299,8 @@ ${taskList}
    - 最后一个 Wave 完成后做一次全量编译验证
    - 用户明确要求编译时
 4. 每个任务完成后：
-   - **在 worktree 内 git add -A && git commit -m "<task-NN 摘要>"**（坑 subagent-uncommitted-newfile-apply3way，2026-08-22 实证：纯新增文件不 commit 时 apply 的 git apply --3way 报 "does not exist in index" 直接炸——未 commit 的新文件不在 base commit 也不在 index，patch 生成取不到。commit 后 base..HEAD diff 完整、apply 顺畅，review.json 的 head 也有真实锚点）
+   - **使用 \`sillyspec wt-commit --change <change-name> -- <task-files>\` 串行提交**（坑 wt-parallel-commit-race：同一 Wave 多子代理共享 worktree，裸 \`git add -A\` 互卷 WIP / 撞 index.lock；\`git add -A\` 还会把并行子代理未提交的半成品一并暂存——**禁 \`git add -A\`**；sillyspec wt-commit 自动处理分支切换与序列化，无需手动 git 操作；未 commit 的新文件不在 base commit 也不在 index，apply --3way 报 "does not exist in index"）
+   - commit 后 base..HEAD diff 完整、apply 顺畅，review.json 的 head 也有真实锚点
    - **写 review.json 即可**（checkbox 由 CLI 自动勾选，见下方 Task Review Gate）
    - **任务边界上报（每任务一次，主仓根目录）**：review write 落盘（CLI 已自动勾选）后跑一次 \`sillyspec platform sync --change <change-name>\`——以任务粒度把「最后信号」（last_pushed_at）与 tasks.md 勾选状态推上平台（变更中心「进行中」可见性）；未连接平台时该命令静默跳过，无需先检查连接状态
    - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）

package/src/stages/knowledge.js

@@ -12,6 +12,8 @@
  *   validate — 校验知识库完整性
  *   refresh  — 从 scan 文档刷新自动知识（仅写 generated/）
  *   propose  — 提议新知识（写入 proposed/）
+ *   classify — 归类 uncategorized 条目到目标知识文件（动态 import src/knowledge-classify.js，task-02 交付）
+ *   stats    — 命中矩阵聚合与死重对照（动态 import src/knowledge-stats.js，task-05 交付）
  */
 
 import { existsSync, readFileSync, readdirSync, mkdirSync, statSync } from 'fs'
@@ -223,8 +225,8 @@ export async function cmdValidate(dir, args, opts = {}) {
 
   for (const mdFile of allMdFiles) {
     if (mdFile === 'INDEX.md') continue
-    // generated/ 和 proposed/ 区不强制要求 INDEX 注册
-    if (mdFile.startsWith('generated/') || mdFile.startsWith('proposed/')) continue
+    // generated/ 和 proposed/ 区不强制要求 INDEX 注册；uncategorized.md 是暂存区（条目归类即迁出，语义上永不注册 INDEX）
+    if (mdFile.startsWith('generated/') || mdFile.startsWith('proposed/') || mdFile === 'uncategorized.md') continue
     if (!indexedFiles.has(mdFile)) {
       warnings.push({
         code: 'unregistered_file',
@@ -498,6 +500,29 @@ function extractSections(content) {
 
 // ── 入口路由 ──
 
+/**
+ * 动态加载 classify / stats 子命令实现（2026-09-14-knowledge-loop-close）。
+ *
+ * 实现文件由 Wave 2/3 的 task-02（src/knowledge-classify.js）/ task-05（src/knowledge-stats.js）交付，
+ * 落地前可能缺席——静态 import 会断链整个 knowledge 命令，故循 index.js case 'knowledge'
+ * 先例用动态 import；模块缺席时返回 null 由调用方输出友好错误，其余异常照抛。
+ * 实现侧须导出 CLI 入口 cmdKnowledgeClassify / cmdKnowledgeStats(dir, args, opts)，
+ * 形态对齐本文件 cmdSearch 等既有子命令。
+ *
+ * 遥测底座：两命令的归类/命中审计统一经 src/knowledge-hits.js 的
+ * appendKnowledgeHit / readKnowledgeHits（KnowledgeHitsAPI 契约，task-02/04/05 消费）。
+ */
+async function tryImportSubcommandImpl(importPath, moduleName) {
+  try {
+    return await import(importPath)
+  } catch (err) {
+    if (err && err.code === 'ERR_MODULE_NOT_FOUND' && String(err.message || '').includes(moduleName)) {
+      return null
+    }
+    throw err
+  }
+}
+
 /**
  * @param {string[]} args - filteredArgs.slice(1)（去掉 'knowledge'）
  * @param {string} dir - 项目根目录
@@ -517,11 +542,35 @@ export async function cmdKnowledge(args, dir, opts = {}) {
       return cmdRefresh(dir, args.slice(1), opts)
     case 'propose':
       return cmdPropose(dir, args.slice(1), opts)
+    case 'classify': {
+      const mod = await tryImportSubcommandImpl('../knowledge-classify.js', 'knowledge-classify.js')
+      if (!mod || typeof mod.cmdKnowledgeClassify !== 'function') {
+        output(false, {}, {
+          code: 'not_implemented',
+          subcommand: 'classify',
+          message: '实现未落地（task-02 交付 src/knowledge-classify.js）',
+        })
+        return
+      }
+      return mod.cmdKnowledgeClassify(dir, args.slice(1), opts)
+    }
+    case 'stats': {
+      const mod = await tryImportSubcommandImpl('../knowledge-stats.js', 'knowledge-stats.js')
+      if (!mod || typeof mod.cmdKnowledgeStats !== 'function') {
+        output(false, {}, {
+          code: 'not_implemented',
+          subcommand: 'stats',
+          message: '实现未落地（task-05 交付 src/knowledge-stats.js）',
+        })
+        return
+      }
+      return mod.cmdKnowledgeStats(dir, args.slice(1), opts)
+    }
     default:
       output(false, {}, {
         code: 'unknown_subcommand',
         subcommand: subCommand,
-        available: ['search', 'inspect', 'validate', 'refresh', 'propose'],
+        available: ['search', 'inspect', 'validate', 'refresh', 'propose', 'classify', 'stats'],
       })
   }
 }