@xulthekl/team-flow 0.56.1 → 0.58.0

package/skills/build-executor/task-reviewer-prompt.md

@@ -100,6 +100,40 @@ Subagent (general-purpose):
     - DRY without premature abstraction?
     - Edge cases handled?
 
+    **Structural criteria (clean-code) — mechanical thresholds:**
+    - **Magic values** (unnamed numeric/string literals) → **Critical**. Front-end code too.
+    - Function length >20 lines / nesting depth >2 levels / parameters >3 / naming form
+      (constants SCREAMING_SNAKE; booleans `is`/`has`/`can` prefix) → Minor. When counting
+      nesting, exclude try/catch's own level and guard-clause `return`/`continue` levels;
+      framework-fixed signatures are exempt from the parameter rule.
+
+    **Incremental boundary — applies to ALL criteria above and below**: judge only the code
+    units this diff adds or modifies. When a hit sits inside a function that already existed
+    before this change, downgrade it to **Minor** and register it as `存量待整改` in your
+    report — never ask for a rewrite outside the task scope.
+
+    **Structural criteria — mandatory answers** (no threshold: answer AND justify):
+    - **Single responsibility**: can the function name cover ALL steps in the body?
+    - **DRY**: is there a structurally equivalent logic block within this diff OR this
+      repository (ignore comments, whitespace, identifier names)? Answer "yes" only when
+      you cite BOTH `file:line` sides.
+      - Disposition: same shared publish unit (same package / module / directory) →
+        **Critical**, extract a shared layer. Cross-repo duplication is NOT judgeable
+        here (your worktree is single-repo).
+
+    **Judgement cases** — when a structural hit is genuinely not blocking, cite it as
+    `judgement-exception: <id>` **plus the structural similarity** (e.g. "all guard clauses,
+    no nesting"). Match by **structural features, not line count** — the numbers below
+    illustrate the case, they are not thresholds. Available ids:
+    - `P1` — long function (≈37 lines) whose body is all guard clauses, one abstraction level → not blocking
+    - `P2` — cross-repo isomorphic fix, no shared publish unit → not blocking
+    - `N1` — long function (≈54 lines) that is guard clauses + one switch, no nesting → not blocking
+    - `N2` — deep nesting arising from try/catch + guard-clause `continue` → already covered
+      by the nesting rule (cite only if that rule's intent is disputed)
+    - `N4` — ≈35 lines, single abstraction level (error mapping) → advisory only
+    - Magic-value exemptions beyond the criterion's list: no id needed — apply the criterion's
+      own test ("does changing this value change behavior?") and state your reasoning.
+
     **Tests:**
     - Do the new and changed tests verify real behavior, not mocks?
     - Are the task's edge cases covered?
@@ -127,12 +161,12 @@ Subagent (general-purpose):
     Categorize issues by actual severity. Not everything is Critical.
     Important means this task cannot be trusted until it is fixed: incorrect
     or fragile behavior, a missed requirement, or maintainability damage you
-    would block a merge over — verbatim duplication of a logic block,
-    swallowed errors, tests that assert nothing. "Coverage could be broader"
-    and polish suggestions are Minor.
+    would block a merge over — structurally equivalent duplication of a logic
+    block (see Structural criteria), swallowed errors, tests that assert
+    nothing. "Coverage could be broader" and polish suggestions are Minor.
     If the plan or brief explicitly mandates something this rubric calls a
-    defect (a test that asserts nothing, verbatim duplication of a logic
-    block), that IS a finding — report it as Important, labeled
+    defect (a test that asserts nothing, structurally equivalent duplication
+    of a logic block), that IS a finding — report it as Important, labeled
     plan-mandated. The plan's authorship does not grade its own work; the
     human decides.
     Acknowledge what was done well before listing issues — accurate praise
@@ -161,6 +195,18 @@ Subagent (general-purpose):
       diff alone, and what the controller should check — report alongside the
       ✅/❌ verdict for everything you could verify]
 
+    ### Structural Criteria (mandatory answers)
+
+    Answer both; cite `file:line` for each. If you downgrade by citing a judgement
+    case, name it here as `judgement-exception: <id>` plus the structural similarity.
+
+    - **Single responsibility**: [Yes | No — if No, list the steps the function name
+      cannot cover, with file:line]
+    - **DRY**: [Yes | No — if Yes, cite BOTH `file:line` sides + shared-layer disposition]
+
+    **存量待整改** (pre-existing hits downgraded to Minor — one per line, or "none"):
+    - [e.g. `src/foo/Bar.java:120` — function length >20 lines, pre-existing]
+
     ### Strengths
     [What's well done? Be specific.]
 

package/skills/ce-brainstorm/references/grounding.md

@@ -8,8 +8,8 @@ Detailed context scanning logic for Phase 1.1. The main SKILL.md describes the h
 
 **Standard and Deep** — Two passes:
 
-*Constraint Check (inline)* — Use the project's active instructions and conventions already in your context. Read `STRATEGY.md` if it exists for product direction and `CONCEPTS.md` if it exists for canonical vocabulary. Use canonical names in dialogue, approaches, and the Product Contract.
-- **Solutions index (v0.5)**: Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = prd OR phase = cross-phase` and `domain` matches the current topic. Inject top-5 summaries as context constraints. If INDEX.md does not exist or is empty, skip silently.
+*Constraint Check (inline)* — Use the project's active instructions and conventions already in your context. Read `STRATEGY.md` if it exists for product direction and `CONCEPTS.md` if it exists for canonical vocabulary — it lives at **`docs/architecture/CONCEPTS.md`** (the repo-root location was retired in v0.23.0, so a root-only probe misses bootstrapped projects). Use canonical names in dialogue, approaches, and the Product Contract.
+- **Solutions index (v0.5)**: Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = prd OR phase = cross-phase` and `domain` matches the current topic. Inject the **top 5** summaries as context constraints, ordered **severity → phase-match → date** (the CLI's ordering). Widen the window with `tf solutions inject --phase prd --limit <n>` when cross-phase entries saturate it — otherwise this stage's own entries are unreachable. If INDEX.md does not exist or is empty, skip silently — a missing index makes the CLI print one WARN, which is not an error.
 
 ## Topic Scan (Grounding Scout)
 

package/skills/ce-compound/references/promotion-rules.md

@@ -18,28 +18,45 @@ tf solutions promote <change-dir>
 
 满足以下条件的经验从 change 级别晋升到全局 `docs/solutions/`：
 
-- **severity ≥ medium** 且 **type = pitfall 或 pattern** → 晋升到全局 `docs/solutions/`
-- 与全局 INDEX 中已有条目 **domain + type 匹配** → 标记"已确认模式"，severity 升级
+- **severity ≥ medium** 且 **type = pitfall 或 pattern** → 晋升到全局 `docs/solutions/<phase>/`
+- 与既有条目**文件名与正文签名都相同** → 同一条经验：登记来源 change + 升级 severity（见下「同名条目确认」），**不新建文件**
+- 与既有条目**同标题但正文不同** → **另一条**经验：新建条目（文件名加 `-2`/`-3` 后缀）——**正文不合并**
+
+> 判重的键是「**标题分量 + 内容分量**」，不是分类标签：旧实现按 `domain + type` 判重
+> （`domain` 由 LLM 自由命名）⇒ 既不稳定（该合的没合）又太粗（不该合的硬合），
+> 且命中即丢弃正文（实测丢 13 条）。v0.57.0 起每条经验独立成条，正文零丢失。
 
 ### Severity 标准
 
 | Severity | 含义 | 晋升行为 |
 |----------|------|----------|
-| critical | 安全 / 数据 / 合规级高危经验（凭证熵源、越权、数据损坏等） | 满足 type 条件时必然晋升；INDEX 重建后置顶 |
+| critical | 安全 / 数据 / 合规级高危经验（凭证熵源、越权、数据损坏等） | 满足 type 条件时必然晋升；severity 是其 INDEX 排序的首键，故自动靠前（INDEX 是派生物，无需手动重建） |
 | high | 阻塞性问题或关键模式 | 满足 type 条件时必然晋升 |
 | medium | 有显著影响的问题或可复用模式 | 满足 type 条件时晋升 |
 | low | 轻微问题或局部洞察 | 不晋升，保留在 change 级别 |
 
 > **晋升是 severity × type 的合取判定**（`severity ≥ medium` **且** `type ∈ {pitfall, pattern}`）——
 > 任一维度不满足即 skipped，critical 也不例外（如 `critical` + `insight` 不晋升）。
-> 「置顶」需 `tf solutions index-gen` 重建 INDEX 后生效：promote 只 append 或原地改 severity，不重排。
+> **INDEX 是派生物**（v0.57.0 §4.2）：promote 写完条目文件后调用 `refreshIndex()` 重建 INDEX
+> （**入口内建**，不靠调用点枚举——promote 与 capture 各有多个落盘分支，逐处追加必然漏改），
+> 故条目顺序（severity 降序 → date 降序 → file 兜底）与 severity 取值在下一次读写时即已一致，无需额外命令。
+> （v0.57.0 之前 promote 只在 INDEX 行上做 append/原地改 severity，与 index-gen 的全量重建互为回滚——
+> 旧文档"「置顶」需 `tf solutions index-gen` 重建后生效"描述的是那个已废止的行为。）
 > 取值域与「序」由 `scripts/lib/severity.mjs` 唯一定义（v0.23 §91）；新增等级只改该文件，不在消费点各自实现。
 > 取值**区分大小写**，须全小写（`Critical` 会被判为未知值：排最后且不晋升）。
 
-### 已确认模式
+### 同名条目确认
+
+当晋升的经验与既有条目的**文件名与正文签名都相同**时（同一天、同标题、同内容）：
 
-当晋升的经验与全局 INDEX 中已有条目的 domain + type 匹配时：
 1. 不创建新文件
-2. 在已有条目中标记"已确认模式"
-3. severity 升级（low → medium → high → critical）
-4. 更新 INDEX.md 中对应行的 severity 字段
+2. 在**条目文件** frontmatter 的 `confirmations` 追加来源 change
+3. **按其**升级 severity（low → medium → high → critical，`critical` 封顶）
+4. **不写 INDEX** —— INDEX 由 `refreshIndex()` 从条目文件派生
+
+- **幂等**：同一 change 重复 promote 记为 `unchanged`，**不**升档（重跑不是新证据）
+- **升级依据**：每新增一个**来源 change**升一档，且 `critical` 封顶后不再升——故
+  `confirmations` 的长度是**升档次数的上界**，不等于最终档位（如 `[a, b, c]` 长度 3，
+  severity 也可能只是 `critical` 而非"3 档"）
+- 旧文档描述的"在已有条目中标记『已确认模式』"**从未落地**（代码里只有 `confirmed: N` 计数）；
+  v0.57.0 起该字段改名为 `confirmations: [...]`，语义也从"计数"改为**来源 change 集合**

package/skills/ce-compound/references/schema.yaml

@@ -5,8 +5,10 @@
 # v0.49.0 §83.3.5（来源：workflow-feedback 20260909）：docs/solutions/ 有两条产出通道，
 # frontmatter 契约不同 ——
 #   ① ce-compound 手工条目：使用本文件的 schema（module / problem_type / component / ...）
-#   ② tf solutions promote 自动晋升条目：phase / domain / type / severity / date / source
-#      （见 scripts/lib/solutions-promote.mjs，字段源自 change 根 learnings.md）
+#   ② tf solutions promote 自动晋升条目：phase / domain / type / severity / date /
+#      source / title / confirmations（见 scripts/lib/solutions-promote.mjs，字段源自 change 根
+#      learnings.md。`title` 是检索字段与 INDEX 摘要来源；`confirmations` 是确认过该条经验的
+#      来源 change 集合——每新增一个来源升一档 severity，同 change 重跑不升）
 # 共同消费面 = docs/solutions/INDEX.md（tf solutions inject 只读该文件，不读条目 frontmatter）。
 # 下方 schema 仅适用于通道 ①。
 #

package/skills/ce-compound/references/three-tier-index.md

@@ -4,7 +4,7 @@
 
 ```
 docs/solutions/
-├── INDEX.md                  # L1：轻量索引（≤150行，每条一行摘要+标签）
+├── INDEX.md                  # L1：轻量索引（≤150 条，每条一行摘要+标签）
 ├── prd/                      # 按阶段分目录（枚举权威：scripts/lib/solutions-phases.mjs）
 ├── plan/
 ├── architecture/
@@ -22,9 +22,9 @@ docs/solutions/
 
 ```markdown
 # Solutions Index
-<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
-| date | phase | domain | type | severity | summary | file |
-|------|-------|--------|------|----------|---------|------|
+<!-- 每条一行，排序 severity 降序 → date 降序 → file 兜底，≤150 条上限 -->
+| date | phase | domain | type | severity | summary | file | source |
+|------|-------|--------|------|----------|---------|------|--------|
 ```
 
 ## 经验文件格式
@@ -35,10 +35,13 @@ docs/solutions/
 ---
 phase: prd          # 阶段标签：prd | plan | architecture | prototype | spec | build | review | cross-phase
 domain: auth        # 领域标签（与 PRD/change 的领域对应）
-type: pitfall       # pitfall | pattern | decision | insight
+type: pitfall       # pitfall | pattern | insight（仅 pitfall/pattern 参与晋升；其余保留在 change 级）
 severity: high      # critical | high | medium | low（序定义于 scripts/lib/severity.mjs）
 date: 2026-07-15
-source: change-id   # 来源 change（晋升时保留）
+source: change-id   # 首次晋升的来源 change
+title: 一句话标题     # 检索字段（learnings-researcher 按 title/tags/module/problem_type grep）
+confirmations: [change-a, change-b]   # 确认过这条经验的**全部**来源 change（晋升时追加）
+                                      # —— 每新增一个来源升一档 severity；同 change 重跑不升
 ---
 
 ## 问题描述
@@ -54,6 +57,6 @@ source: change-id   # 来源 change（晋升时保留）
 ## 按需加载策略
 
 三层索引设计使最坏情况 token 消耗约 ~6.5k：
-1. **L1 INDEX.md**：始终加载（≤150 行，每条约 40 token）
+1. **L1 INDEX.md**：始终加载（**≤150 条**，每条约 40 token）
 2. **L2 阶段目录**：按 phase 过滤后加载匹配文件列表
 3. **L3 经验文件**：仅加载与当前任务相关的具体文件

package/skills/ce-compound/references/write-flow.md

@@ -3,17 +3,29 @@
 ## 记录一条经验的步骤
 
 1. 确定 phase/domain/type/severity 标签
-2. 在对应阶段目录下创建经验文件（如 `docs/solutions/prd/2026-07-15-需求歧义.md`）
-3. 在 INDEX.md 中追加一行摘要
-4. 如果 INDEX.md 超过 150 行，执行淘汰规则
+2. 在对应阶段目录下创建经验文件（如 `docs/solutions/prd/2026-07-15-需求歧义.md`），frontmatter **须含 `title:`** —— 它是 `learnings-researcher` 的检索字段（该 agent 按 `title:`/`tags:`/`module:`/`problem_type:` grep）；存量条目可用 `tf solutions backfill` 补齐
+3. **不要手工编辑 `INDEX.md`** —— 见下节
 
-## 淘汰规则（Eviction）
+## INDEX 的维护（v0.57.0 §4.2 变更）
 
-当 INDEX.md 超过 150 行硬上限时：
-- 按 severity 降序排列（critical > high > medium > low；序定义于 `scripts/lib/severity.mjs`）
-- 保留前 150 条
-- 淘汰 low severity 且 date 最早的条目
-- 被淘汰的经验文件保留在阶段目录中（可从文件系统找回），仅从 INDEX.md 移除
+INDEX 是**投影**，唯一写入者是 `scripts/lib/solutions-index-gen.mjs` 的 `refreshIndex()`：
+
+- `tf solutions capture` / `tf solutions promote` 在写完条目文件后调用它（**入口内建**，不靠调用点枚举——两者各有多个落盘分支，逐处追加必然漏改）
+- `tf solutions index-gen` 是它的 CLI 入口
+- **手工改写 INDEX 会在下一次捕获/晋升时被覆盖**——v0.57.0 之前 capture/promote 会直接 append INDEX 行，
+  与 index-gen 的全量重建互为回滚；收敛为单一 writer 后该风险消除
+
+`severity` 与 `confirmations` 的真相源是**条目文件的 frontmatter**（唯一不被重建抹掉的持久层）；
+INDEX 行中的值是它们的投影。可用 `tf doctor` 的 `Solutions` 维度检查两者是否一致。
+
+## 容量与淘汰（v0.57.0）
+
+上限为 **150 条**（`MAX_INDEX_ENTRIES`；**不是 150 行**——INDEX 文件另含 4 行头部）：
+
+- 按 **severity 降序**（critical > high > medium > low；序定义于 `scripts/lib/severity.mjs`）→ **同级按 date 降序** → **同名同级按 file 兜底**（末键保证去留在跨机器上可复现）
+- 保留前 150 条；**被淘汰的经验文件保留在阶段目录中**（仅从 INDEX 移除）
+- **淘汰会显式 WARN 并逐条列出**被丢弃的文件（v0.57.0 前为静默）
+- 条目数逼近上限时 `tf doctor` 的 `Solutions` 维度会预警
 
 ## CLI 写入命令
 
@@ -32,5 +44,5 @@ tf solutions index-gen    # 重建复利索引
 ## 阶段感知注入
 
 ```bash
-tf solutions inject --phase <p> --domain <d>   # 阶段感知注入（top-5）
+tf solutions inject --phase <p> --domain <d> --limit <n>   # 阶段感知注入（默认 top-5，须显式传 --limit）
 ```

package/skills/ce-ideate/references/agents/learnings-researcher.md

@@ -17,9 +17,16 @@ For ideation invocations, search the full learning corpus described below, then
 
 ## Step 0: Ground in CONCEPTS.md (if present)
 
-Before searching `docs/solutions/`, check whether `CONCEPTS.md` exists at the repo root. If it does, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+Before searching `docs/solutions/`, probe for `CONCEPTS.md` in **either** of two locations and read the first one found:
 
-If `CONCEPTS.md` does not exist, skip this step entirely and proceed to Step 1.
+1. `CONCEPTS.md` at the repo root
+2. `docs/architecture/CONCEPTS.md`
+
+If found, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+
+> 两处探测的原因：`workflow-bootstrap` B3 把词汇表产出在 `docs/architecture/CONCEPTS.md`，而本步骤原只查仓库根 ⇒ grounding 静默落空（实测 emp-auth 的 `CONCEPTS.md` 位于 `docs/architecture/`）。与 Step 2「动态探测目录、不假设固定列表」同一原则。
+
+If neither location has `CONCEPTS.md`, skip this step entirely and proceed to Step 1.
 
 ## Search Strategy (Grep-First Filtering)
 

package/skills/ce-ideate/references/grounding.md

@@ -35,7 +35,7 @@ Run grounding agents in parallel in the **foreground** (do not background — re
 
    > **Grounding scope:** use the supplied project context and go directly to current patterns bearing on the focus, pain points, leverage points, applicable workflow constraints, and in surprise-me mode representative files plus recent activity. If the focus cannot be scoped, use one targeted root or workspace probe.
    >
-   > Start with the files and areas named by the focus or caller context. Read `STRATEGY.md` when product alignment matters, and `CONCEPTS.md` when canonical vocabulary matters.
+   > Start with the files and areas named by the focus or caller context. Read `STRATEGY.md` when product alignment matters, and `CONCEPTS.md` when canonical vocabulary matters — the latter lives at **`docs/architecture/CONCEPTS.md`** (repo-root location retired in v0.23.0).
    >
    > If the focus names a root-level `*.md` file, read it and include under `User-named references`. When listed on the research-artifacts line, include only a one-line gist here.
    >

package/skills/ce-plan/references/agents/learnings-researcher.md

@@ -17,9 +17,16 @@ For planning invocations, search the full learning corpus described below, then
 
 ## Step 0: Ground in CONCEPTS.md (if present)
 
-Before searching `docs/solutions/`, check whether `CONCEPTS.md` exists at the repo root. If it does, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+Before searching `docs/solutions/`, probe for `CONCEPTS.md` in **either** of two locations and read the first one found:
 
-If `CONCEPTS.md` does not exist, skip this step entirely and proceed to Step 1.
+1. `CONCEPTS.md` at the repo root
+2. `docs/architecture/CONCEPTS.md`
+
+If found, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+
+> 两处探测的原因：`workflow-bootstrap` B3 把词汇表产出在 `docs/architecture/CONCEPTS.md`，而本步骤原只查仓库根 ⇒ grounding 静默落空（实测 emp-auth 的 `CONCEPTS.md` 位于 `docs/architecture/`）。与 Step 2「动态探测目录、不假设固定列表」同一原则。
+
+If neither location has `CONCEPTS.md`, skip this step entirely and proceed to Step 1.
 
 ## Search Strategy (Grep-First Filtering)
 

package/skills/ce-plan/references/research-workflow.md

@@ -12,7 +12,7 @@ Prepare a concise planning context summary (a paragraph or two) to pass as input
 - If an origin document exists, summarize the problem frame, requirements, and key decisions from that document
 - Otherwise use the feature description directly
 - If `STRATEGY.md` exists, read it and include the relevant pieces (target problem, approach, active tracks) in the summary so downstream research and planning decisions are anchored to product strategy
-- If `CONCEPTS.md` exists at repo root, read it — its definitions are the canonical names for domain entities, named processes, and status concepts. Plan with those terms rather than synonyms.
+- If `CONCEPTS.md` exists — check **repo root first, then `docs/architecture/CONCEPTS.md`** (`workflow-bootstrap` B3 writes it to the latter, so a root-only probe misses bootstrapped projects) — read it: its definitions are the canonical names for domain entities, named processes, and status concepts. Plan with those terms rather than synonyms.
 - Include session-settled decisions with their rejected alternatives, plus the standing line "If you find evidence a settled decision cannot work, report it — do not suppress it." Do not pass the decision's advocacy or rationale, and keep any adversarial or validation lens blind to settlement markers.
 
 Pass the project's active instructions and the planning context summary to `repo-research-analyst`, and send it directly to the requested current scopes. If the feature cannot be scoped from that context, allow one targeted root or workspace probe. Read an exact dependency or runtime version when the plan or an external-doc query materially depends on it.
@@ -45,7 +45,7 @@ Collect:
 - **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
 - **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
 
-**Solutions index (v0.5)**: Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = plan OR phase = cross-phase` and `domain` matches the current topic. Inject top-5 summaries as planning constraints. If INDEX.md does not exist or is empty, skip silently.
+**Solutions index (v0.5)**: Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = plan OR phase = cross-phase` and `domain` matches the current topic. Inject the **top 5** summaries as planning constraints, ordered **severity → phase-match → date** (the CLI's ordering); widen with `tf solutions inject --phase plan --limit <n>` when cross-phase entries saturate the window. If INDEX.md does not exist or is empty, skip silently — a missing index makes the CLI print one WARN, which is not an error.
 
 ## 1.1b Detect Execution Direction Signals
 

package/skills/clean-code/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: clean-code
+description: 代码结构质量判据 skill——可机械判定项阈值与计数口径、审查必答项、增量归因边界与共享层判定。
+user-invocable: false
+---
+
+# Clean Code
+
+代码结构质量的判据集。判据三分：能机械判定的给阈值；需要判断力的设为「必答项」（不给阈值，但必须回答并给理由）；既有的不动。
+
+判例集与判例引用约定见 `references/judgement-cases.md`；共享层判定的完整规则见 `references/shared-layer-rules.md`。
+
+> **执行处说明**：本文件是判据**真相源**。实际执行由**派发模板**承载——`skills/build-executor/implementer-prompt.md`（实施自检）、`skills/build-executor/task-reviewer-prompt.md`、`skills/code-reviewer/code-reviewer-prompt.md`（审查）各自内联判据，因为由模板派发的 `general-purpose` 子代理读不到本文件。两侧须保持一致。
+
+## 1. 判据三分
+
+| 类型 | 判据 | 处置 |
+|---|---|---|
+| 可机械判定项 | 魔法值、函数长度、嵌套深度、参数个数、命名形式 | 查表 §2 |
+| 审查必答项 | 单一职责、DRY | 必答 §3（不给阈值）|
+| 沿用既有清单项 | 错误处理、边界条件、YAGNI/过度设计 | 本 skill 不涉及，由原清单负责 |
+
+为何不给「单一职责」设阈值：它需要判断力，阈值化会制造查表错觉。实测反证——37 行的 `validateFrontSystemSecret`（通体卫语句、单层抽象）可读性良好；54 行的 `handleDelivery`（三个卫语句 + switch + catch）同样良好。任何「抽象层级计数」规则都无法在这一对同类样本上复现判定，故该规则已废。
+
+## 2. 可机械判定项
+
+| 判据 | 阈值 | 分级 | 例外 |
+|---|---|---|---|
+| 魔法值（后端）| 见下方口径 | **Critical** | 见下方豁免 |
+| 魔法值（前端）| 同上 | **Critical** | 同上 |
+| 函数长度 | >20 行 | Minor | 存量代码（§4）|
+| 嵌套深度 | >2 层 | Minor | 见下方计数口径 |
+| 参数个数 | >3 个 | Minor | 框架接口固定签名不适用 |
+| 命名（形式）| 常量非 SCREAMING_SNAKE；布尔非 `is` · `has` · `can` 前缀 | Minor | 仅判形式；命名是否揭示意图属审查者判断，在报告中说明即可 |
+
+### 2.1 魔法值判据口径（真相源）
+
+- **定义**：直接出现在逻辑中的数值 / 字符串字面量，**其值变化会改变行为**。典型：业务码、TTL / 超时、阈值、错误消息、键名、URL、正则。
+- **豁免**：结构性索引（`arr[0]`、`list.get(0)`）、算术恒等元（`i + 1`、`x * 1`）、空串 / 空集合判断、CSS 取值、注解参数、日志格式串、测试夹具中自明数据、生成代码。
+- **适用范围**：`src/main` 与前端**运行时**代码。**不适用**于测试代码、构建脚本、SQL 迁移。
+- **交付形态**：命名为常量或枚举（枚举用于有语义集合，纯常量入常量类）。
+
+> 项目 conventions 若给出更严或更宽的豁免，以 conventions 为准（§7）。
+
+### 2.2 计数口径
+
+- **函数长度**：按**有效行**计——不含空行与纯注释行；**签名行计入**。
+- **嵌套深度**：函数体为第 1 层，每进入一个块（`if` / `for` / `while` / `switch` / `try`）加 1。**排除** `try/catch` 自身一层与卫语句（`return` / `continue`）所在层；`try/catch` 仅排除自身，其体内语句仍计入。
+
+函数长度恒为提示级，不设升级线：曾拟「>50 行升 Important」，但该阈值系从样本反推（过拟合），且会与存量长函数冲突。长度异常的价值由 §3 的必答项综合判断承载。
+
+## 3. 审查必答项（不给阈值，须给理由）
+
+| 判据 | 判定要件 | 必答格式 |
+|---|---|---|
+| 单一职责 | 函数名能否概括函数体的全部步骤？ | 必须回答「是 / 否」；答「否」须列出无法概括的步骤 + 分级理由。**不单独升级为 Critical** |
+| DRY | 本 diff 内或本仓内是否存在结构等价的逻辑块（忽略注释、空白、标识符命名）？ | 必须回答；答「是」须给两侧 `文件:行号` + 结构对比 + 按 §5 判定处置。**同共享发布单元内的重复 = Critical**（见 §5）|
+
+效力边界（诚实声明）：必答格式使发现过程可被第三方核对，提升的是发现一致性，不是判定一致性——分级仍由审查者判断，「须给理由」也可能被套用现成话术。故单一职责不单独升 Critical，避免用一条无客观约束的判据制造阻断。
+
+判例引用出口：审查者可在报告中标注 `judgement-exception: <判例编号>`（编号与含义见 `references/judgement-cases.md`，模板侧同步内联）以引用客观例外，须同时写明与该判例的相似点。该机制用于防止用现成话术无边界降级；**机械判定项同样可引用**（判例 `P1` / `N2` / `N4` 即针对长度与嵌套）。
+
+## 4. 增量归因边界
+
+判据只判本次 diff 新增或修改的行所属的代码单元。
+
+| 情形 | 处置 |
+|---|---|
+| 新增函数命中 | 按 §2 / §3 正常判定 |
+| 存量函数命中（本次改动前已存在）| 一律降 Minor，并在审查报告中登记「存量待整改」（函数名 + `文件:行号` + 命中判据）|
+
+为何不设「改动占比」阈值：函数总行数不在 diff hunk 内、而审查者被限制读文件，无取证通道；且按次求值可被「两次各改 40%」规避。存量恒为 Minor ⇒ 无豁免判定、无计算需求、无规避动机。台账经审查报告累积。
+
+## 5. 共享层判定（结论）
+
+| 步 | 判据 | 判定 |
+|---|---|---|
+| 1 | 复制体是否在同一共享发布单元内（同 npm 包 / 同 Maven 模块 / 同仓同目录）？ | **是 → 应抽共享层**（Critical）|
+| 2 | 缺陷是否属同名耦合类（编译期无保护）？若是，横展须逐字节同构并留对端标注 | 附加条件 |
+
+**跨仓不可判**：审查者 worktree 为单仓；跨仓 DRY 归横展完整性检查承接。完整规则、判定依据与 v1 实测校验见 `references/shared-layer-rules.md`。
+
+## 6. 取证边界
+
+DRY 的取证范围是「本 diff 内或本仓内」，两条派发路径的依据不同：
+
+- task 级审查（`skills/build-executor/task-reviewer-prompt.md`）：显式授权——「Inspect code outside the diff only to evaluate a concrete risk you can name — one focused check per named risk」
+- wave 级审查（`skills/code-reviewer/code-reviewer-prompt.md`）：无禁止性条款（约束仅有 read-only 与 scope 限制）
+
+「须给两侧 `文件:行号`」这一格式要求本身即构成上述条款所要求的「命名的具体风险」。
+
+## 7. 与 conventions 的关系
+
+- conventions 优先：项目 conventions 与本 skill 冲突时以项目为准（项目级契约 > 通用缺省）。
+- 追加通道：项目可沉淀「本项目特有的结构约定」，格式参照项目级 `backend-patterns.md` 的 `MUST + 来源 + 证据段` 范式。
+- 引用约定：conventions 引用插件侧 references 时 MUST 写全路径 `skills/<skill>/references/<file>.md`，不得写裸 `references/...`。
+- 参数口径：`test-strategy` 的 `param_count>6` 判测试复杂度，本 skill 的「参数 >3」判可读性——管辖不同，非矛盾。
+
+## 8. 自检口诀
+
+新增函数交付前逐条自查：常量命名了吗？超 20 行了吗？嵌套超 2 层了吗？只做一件事吗？与其他地方重复吗？
+
+## 9. 术语中英对照
+
+本 skill 以中文面向读者；三个派发模板以英文内联执行（受众为 `general-purpose` 子代理）。两侧判据**语义相同**，P4 一致性检查按下表比对：
+
+| 中文（本 skill）| English（模板内联）|
+|---|---|
+| 魔法值 | Magic values |
+| 单一职责 | Single responsibility |
+| 结构等价 | structurally equivalent |
+| 共享发布单元 | shared publish unit |
+| 存量待整改 | pre-existing / register as 存量待整改 |
+| 判例引用出口 | judgement-exception |
+| 必答项 | mandatory answers |
+| 增量归因边界 | incremental boundary |

package/skills/clean-code/references/judgement-cases.md

@@ -0,0 +1,83 @@
+# 判例集（Judgement Cases）
+
+> **用途**：为「审查必答项」（单一职责 / DRY）提供**客观锚点**，防止判据退化成新的直觉。
+> **全部判例均取自 emp-auth v1 的真实代码**，非虚构。
+
+## 判例引用约定
+
+审查者在报告中对某项判定可标注：
+
+```
+judgement-exception: <P1|P2|N1|N2|N4>
+```
+
+含义：**该降级属客观例外**（非主观放行）。使用要求：
+
+1. 必须同时写明「本处与所引判例的相似点」（至少一条结构性事实，如"通体卫语句、无嵌套"）；
+2. 引用判例**不改变**判据本身的阈值适用——它只解释为何某项判定不阻断；
+3. 若某处与判例只有表面相似（如"也超 20 行"但结构不同），引用无效，按正常分级处理。
+
+**为何需要这个出口**：`task-reviewer-prompt.md` 既有条款 "a stated rationale never downgrades a finding's severity" 约束的是**实施者的自述**；本出口约束的是**审查者的判定**，两者主体不同。判例编号把「判定」从「话术」中分离出来——引用必须有结构性事实支撑。
+
+## 一、判为「Critical（阻断）」的锚点
+
+### N3 — 同一共享单元内的结构等价复制
+
+| 项 | 内容 |
+|---|---|
+| **位置** | emp-auth v1-C2 `ui-emp-frame/src/views/iam/relay.vue:19-52`（常量 + `hasControlChar` + `isValidFrontSystem`，其中 `isValidFrontSystem` 在 `:44`）→ v1-C3 同仓 `logout.vue:12-44`（在 `:35`）|
+| **判定** | **Critical**（DRY）|
+| **依据** | §5 步 1「同一共享发布单元内」成立：同一 npm 包、同仓同目录 |
+| **取证** | 两侧同在本仓 → 可达（`code-reviewer-prompt.md` 无禁止性条款；task 级有显式授权）|
+| **要点** | 结构等价判定**忽略注释差异**——两处注释分别为「SP-1 裁定 / design.md D-01」与「与登录入口 relay.vue 同口径」，不作为"非重复"的依据 |
+
+## 二、判为「不阻断」的锚点（防止过度阻断）
+
+### P1 — 长函数但结构清晰
+
+| 项 | 内容 |
+|---|---|
+| **位置** | emp-auth v1-C1 `infra-emp-auth` `SysFrontSystemService.java:382-418`（`validateFrontSystemSecret`，37 行）|
+| **判定** | 不阻断（长度属提示级）|
+| **理由** | 通体卫语句早返回、无嵌套、每步有意图注释 |
+| **反面对照价值** | 该函数内含 repository 调用、枚举判断、摘要算法与结果装配 —— **故「抽象层级计数」不可作为判据**（同一规则会把它与 N1 混为一谈，得出相反判定）|
+
+### P2 — 跨单元的必要横展
+
+| 项 | 内容 |
+|---|---|
+| **位置** | emp-auth v1-C5 `AuthService.java:47`（两个 BFF 仓各删 1 行 `@Cacheable`）|
+| **判定** | 不阻断 |
+| **依据** | 跨仓、无共享发布单元、无可用共享通道 → 必要横展（见 `shared-layer-rules.md`）|
+| **注意** | 本判例**不在** `clean-code` 的 DRY 判据范围内（跨仓不可判），归 `cross-change-consistency-checker` 的 Dim 5 承接。列此仅为说明「跨单元 ≠ 应抽层」的边界 |
+
+### N1 — 多职责外观但实为单一层次
+
+| 项 | 内容 |
+|---|---|
+| **位置** | emp-auth v1-C3 `bff-emp-usersidentification` `AcceptInvalidTokenConsumer.java:57-115`（`handleDelivery`）|
+| **判定** | 不阻断 |
+| **理由** | 三个卫语句早返回 + 一个 switch + catch 兜底，**通体无嵌套** |
+| **历史** | 曾被判「阻断」，理由为「混合域判断/事件解析/规范化/分支/日志」——该描述**不可复现**。其签名 4 个参数亦不适用参数判据（`MessageListener` 框架固定签名）|
+
+### N2 — 深嵌套但来自 try/catch 与卫语句
+
+| 项 | 内容 |
+|---|---|
+| **位置** | emp-auth v1-C3 `InvalidTokenInitializer.java:81`（bff）/ `:85-137`（adapter）|
+| **判定** | 提示（嵌套例外已排除）|
+| **理由** | 嵌套层级来自 try/catch 自身一层与卫语句 `continue` 所在层——按 §2 例外规则**不计入深度**|
+
+### N4 — 长度超阈值但单一抽象层级
+
+| 项 | 内容 |
+|---|---|
+| **位置** | emp-auth v1-C2 `demo/bff/.../RelayTokenClient.java:51-85`（`redeem`，35 行含 4 个 catch 分支）|
+| **判定** | 提示 |
+| **理由** | 单一抽象层级（错误映射与信封解包）；长度超阈值但无职责混杂 |
+
+## 三、判例集维护约定
+
+1. **增补来源**：仅接纳**真实代码**中的判定分歧案例（同一判据在不同审查者间给出不同结论）；
+2. **增补须附**：位置（`文件:行号`）、判定、结构性理由、与该判例易混之处；
+3. **判例可能被推翻**：若新证据表明某判例的判定有误（如 P1 被证明实为职责混杂），**更新判例本身**并在设计文档版本记录中注明——不得保留错误判例供后续引用。

package/skills/clean-code/references/shared-layer-rules.md

@@ -0,0 +1,50 @@
+# 共享层判定与跨仓边界
+
+> 用途：区分「必要横展」与「应抽共享层」——**两种处置的正确性相反，判错即方向性错误**。
+
+## 一、二判据（顺序判定）
+
+| 步 | 判据 | 判定 |
+|---|---|---|
+| 1 | 复制体是否在**同一共享发布单元**内（同 npm 包 / 同 Maven 模块 / 同仓同目录）？ | **是 → 应抽共享层**（同单元内复制必然漂移，且抽取成本最低）|
+| 2 | 缺陷是否属**同名耦合类**（编译期无保护，如缓存名、常量名）？若是，横展须**逐字节同构**并留对端标注 | 附加条件，不单独改变步 1 判定 |
+
+### 为何是二判据，而非三判据
+
+早期版本曾有第三条「跨单元时是否存在可用的共享通道（父 POM / 可发公共包 / 已有跨仓契约）」。**该判据已删除**，两个原因：
+
+1. **共线**：跨仓必然无共享单元，第 1 条已隐含"跨单元"的判定，第 3 条只在跨单元时才触发 —— 两条实际只有一条在起作用；
+2. **不可判定**：审查者被锁定单仓 worktree，无法知道别的仓有无父 POM 依赖或公共包 —— 该判据**无取证通道**（与「跨仓 DRY 不可判」同源）。
+
+删除后本判据**完全在单仓内可判**。
+
+## 二、跨仓边界（重要）
+
+**本判据只管单仓内**。下列情形**不在** `clean-code` 的判据范围：
+
+| 情形 | 归属 |
+|---|---|
+| 跨仓的同构缺陷（如 v1-C5 修了 2 个 BFF 仓、漏了 2 个 adapter 仓）| `cross-change-consistency-checker` 的 **Dim 5（同构横展完整性）** |
+| 跨仓的重复代码 | 同上（模式驱动扫描全部仓，见 Dim 5）|
+
+理由：审查者的 worktree 为**单仓**（实证：`changes/<name>/.superpowers/sdd/reviews/w*.md` 的 metadata 含 `Target repository: service/<repo>`），跨仓在物理与约定层面均不可达。
+
+## 三、v1 实测校验
+
+| 案例 | 步 1 | 判定 | 与实测一致性 |
+|---|---|---|---|
+| C2 `relay.vue` → C3 `logout.vue`（同仓同目录同一 npm 包）| 是 | **应抽共享层** | ✅ 与实测判断一致 |
+| C5 后端两仓（`bff-emp-usersidentification` / `bff-emp-clientsidentification`，跨仓、无共享 jar、hunk md5 相同、同名缓存值类型耦合）| 跨仓 | **不在本判据范围** → Dim 5 承接 | ✅（当时判为必要横展，结论正确但依据不同）|
+| C5 前端三仓（各自独立 npm 包、各修本仓存储封装）| 跨仓 | **不在本判据范围** | 同上 |
+
+## 四、判定为「应抽共享层」后的处置
+
+1. **不要求本次 change 立即重构**（避免范围蔓延）——除非该抽取本身在本次 write_set 内；
+2. 在审查报告中标注为 **Critical**（DRY 唯一的分级），并给出共享层建议落点（如 `src/utils/`）；
+3. 若项目 conventions 已有对应的共享层约定，以 conventions 为准。
+
+## 五、判定为「必要横展」的处置（由 Dim 5 承接时）
+
+1. 横展须**逐字节同构**（含注释口径），并保留对端来源标注（参照项目级 `backend-patterns.md` 的 §8.1 范式）；
+2. 横展范围须覆盖**全部**同构位置——遗漏即 Dim 5 的 Important 发现（可达时）；
+3. 不可达位置（零调用方）记 Minor，属「预防性一致处置」。

package/skills/code-reviewer/SKILL.md

@@ -93,6 +93,13 @@ Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI
 
 The code-reviewer agent follows this 6-step process:
 
+### Step 0: Solutions Injection (v0.57.0 §4.1)
+
+Run `tf solutions inject --phase review --limit 15` (never blocks on failure) — it surfaces historical learnings from the `review` and `cross-phase` buckets so this review avoids known pitfalls. Treat the output as **advisory hints, not constraints**; report conflicts with the contract/spec rather than following either silently. On a failed/empty read the CLI prints one WARN and returns empty — continue.
+
+> **Keep `--limit`**: the default top-5 saturates once 5 cross-phase entries exist, making this stage's own (lower-severity) entries unreachable. The flag widens the window only — ordering is unchanged (severity → phase-match → date).
+> **Two dispatch paths, both must inject**: this step covers the `team-flow:code-reviewer` agent path (which preloads this file); `code-reviewer-prompt.md` carries its own copy for the `general-purpose` + template path. Removing either drops injection on that path — gated by `tests/lib/doc-consistency.test.mjs`.
+
 ### Step 1: Gather Context
 
 1. Read `change-brief.md` to understand scope and constraints
@@ -126,6 +133,12 @@ Check for:
 - **Performance**: No obvious N+1 queries, no unnecessary loops, appropriate caching
 - **Security**: Input validation, SQL injection prevention, XSS prevention, auth checks
 
+**Structural criteria (clean-code, v0.58.0)**：本节另有一套可判定判据——机械阈值（魔法值 Critical；长度/嵌套/参数/命名 Minor）+ 两项必答（单一职责、DRY）。
+
+**执行处是派发模板** `skills/code-reviewer/code-reviewer-prompt.md`（其 Code quality 段已内联完整判据），**不是本文件**。原因：由该模板派发的 `general-purpose` 子代理**读不到**本 SKILL.md 或 `clean-code` skill——子代理不继承父 Agent 的 Skills（CLAUDE.md 明文）。注：该模板经**直接路径读取**（本文件 `Procedure` 步骤 2 指明），**不**经 `tf runtime asset read` 的 `ASSETS` 白名单——后者仅含 `skills/build-executor/implementer-prompt.md` 与 `task-reviewer-prompt.md` 两个模板，写此文时曾误述为「白名单放行本模板」。
+
+本 SKILL.md 与 `clean-code` skill 是判据的**真相源**，供 agent 路径预加载与维护参考；两侧核心判据 MUST 保持一致（由 P4 一致性检查守护）。
+
 ### Step 4: Architecture Review
 
 Check for:
@@ -187,12 +200,16 @@ Check for:
 
 ## Verdict Criteria
 
+本表用于**报告内**的结论表述；写入 receipt 时只有 `pass | fail` 两值，映射规则见末行。
+
 | Verdict | Condition |
 |---------|-----------|
 | **PASS** | No Critical or Important findings |
 | **PASS_WITH_WARNINGS** | No Critical, but Important findings exist |
 | **FAIL** | Any Critical finding (including Test Matrix Compliance gaps — v0.12 §44.3) |
 
+**receipt 映射（v0.58.0 统一，消除此前四处口径分歧）**：`tf execution review --verdict` 只接受 `pass | fail`。**PASS → `pass`**；**PASS_WITH_WARNINGS 与 FAIL 均 → `fail`** —— 即 **Important 亦须阻断**，与 `code-reviewer-prompt.md`、`task-reviewer-prompt.md`、`build-executor/SKILL.md` 三处的「Critical/Important findings require a `fail` receipt」保持一致。此前本表的「FAIL 仅 Critical」是四处口径中唯一的异类，且 `PASS_WITH_WARNINGS` 在二值 receipt 中**无法表达**，已按此统一。
+
 Test Matrix Compliance Critical findings carry the same weight as Spec Compliance violations — matrix gaps are always Critical, never Important.
 
 ## Calibration Rules