@xulthekl/team-flow 0.57.0 → 0.59.0

package/docs/release-checklist.md

@@ -46,7 +46,7 @@ For each example in `docs/examples/`:
 - `node scripts/team-flow.mjs version <version> --dry-run` — reports all files in sync
 - `node scripts/check-version-consistency.mjs` — exits 0
 - `node scripts/team-flow.mjs --help` — all subcommands listed
-- `node scripts/team-flow.mjs install-workbuddy --dry-run` — finds all 9 skills and target paths
+- `node scripts/team-flow.mjs install-workbuddy --dry-run` — finds all 28 skills and target paths
 - `npm run test:raw-mode` — packs the current source and runs a canonical runtime in an empty directory with no plugin-root variables or global `tf`.
 - Run a representative local-installer smoke test.
 - `team-flow.config.json` absence still works (backward compatible defaults)

package/docs/usage-guide.md

@@ -1,6 +1,6 @@
 # team-flow 使用说明（研发团队版）
 
-> 版本锚点：v0.50.0（26 skills + 17 agents）· 更新日期：2026-09-09
+> 版本锚点：v0.59.0（28 skills + 17 agents）· 更新日期：2026-09-12
 > 读者：使用 team-flow 做日常研发的工程师。不需要你懂插件内部实现，只需要照着路径走。
 > 配套文档：安装细节见 [INSTALL.md](../INSTALL.md)；状态机细节见 [state-machine.md](state-machine.md)；决策点细节见 [decision-points.md](decision-points.md)；平台差异见 [platform-matrix.md](platform-matrix.md)。
 
@@ -36,7 +36,7 @@
 | 大需求拆成一团乱麻，改 A 坏 B | 产品级编排拆分 change + 依赖 DAG + 跨 change 冲突检测 |
 | 会话中断后上下文全丢 | 状态持久化在 `.team-flow.yaml`，新会话可无损恢复 |
 
-**规模感知**：24 个 skills（工作流能力）+ 15 个 agents（子代理角色）+ 1 个 `tf` CLI（状态机与门禁运行时）。你日常真正需要记住的入口只有 **3 个**（见第 3 节）。
+**规模感知**：28 个 skills（工作流能力）+ 17 个 agents（子代理角色）+ 1 个 `tf` CLI（状态机与门禁运行时）。你日常真正需要记住的入口只有 **3 个**（见第 3 节）。
 
 ### 双层编排架构
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact). 26 skills, one install.",
-  "version": "0.57.0",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact). 28 skills, one install.",
+  "version": "0.59.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.57.0: auto-sync CLI version with plugin version
+# v0.59.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.57.0"
+PLUGIN_VERSION="0.59.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.57.0.
+Current version: v0.59.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.57.0",
-  "description": "Unified plugin (26 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
+  "version": "0.59.0",
+  "description": "Unified plugin (28 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.57.0",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding). 26 skills + 17 agents, one install.",
+  "version": "0.59.0",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding). 28 skills + 17 agents, one install.",
   "author": {
     "name": "LT"
   },

package/scripts/check-version-consistency.mjs

@@ -71,6 +71,9 @@ const TEXT_CHECKS = [
   { file: 'llms.txt',               extract: /Current version: v(\d+\.\d+\.\d+)\./ },
   { file: '.claude/always/phase-guard.md', extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
   { file: 'GEMINI.md',              extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
+  // v0.59.0：新增 usage-guide 版本锚点（此前不在扫描面内，0.58.0 与 0.59.0 两次发版均靠人工改；
+  // P3-15 ② 半项闭合——**检出**已覆盖，本段仍无 --fix 分支，自动修复待做）
+  { file: 'docs/usage-guide.md',    extract: /版本锚点：v(\d+\.\d+\.\d+)/ },
 ];
 
 for (const check of TEXT_CHECKS) {
@@ -103,9 +106,19 @@ const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
 const ACTUAL_SKILL_COUNT = skillDirs.length;
 
 // JSON manifests: extract the "N skills" number from the description field.
+// v0.59.0：扫描面扩展至全部含计数的宿主 manifest——此前仅覆盖 2 个 JSON + 2 个 md，
+// 其余 10+ 处靠人工，是「计数漂移反复发生」的根因（0.58.0 漏 13+ 处、0.59.0 又漏
+// INSTALL.md / platform-matrix.md / usage-guide.md 共 3 文件）。path 支持嵌套与数组下标。
 const SKILL_COUNT_JSON_CHECKS = [
   { file: 'plugin.json', path: ['description'], extract: /(\d+) skills/ },
   { file: '.claude-plugin/plugin.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: '.claude-plugin/marketplace.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: '.claude-plugin/marketplace.json', path: ['plugins', '0', 'description'], extract: /(\d+) skills/ },
+  { file: '.cursor-plugin/plugin.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: '.cursor-plugin/marketplace.json', path: ['plugins', '0', 'description'], extract: /(\d+) skills/ },
+  { file: '.codex-plugin/plugin.json', path: ['interface', 'longDescription'], extract: /(\d+) skills/ },
+  { file: 'gemini-extension.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: 'package.json', path: ['description'], extract: /(\d+) skills/ },
 ];
 
 for (const check of SKILL_COUNT_JSON_CHECKS) {
@@ -123,11 +136,20 @@ for (const check of SKILL_COUNT_JSON_CHECKS) {
       errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: 'PATTERN_NOT_MATCHED', expected: ACTUAL_SKILL_COUNT });
     } else if (Number(match[1]) !== ACTUAL_SKILL_COUNT) {
       if (AUTO_FIX) {
-        // Auto-fix: update skill count in JSON
+        // Auto-fix: update skill count in JSON.
+        // v0.59.0 修复：原实现只写顶层键（把 path[0] 直接赋成新值），对嵌套路径
+        // （plugins[0].description、interface.longDescription）会把父级整体覆盖成字符串 → 毁文件。
+        // 改为按完整路径回溯写回，并在路径不可写时显式报错而非静默跳过。
         const newVal = val.replace(check.extract, `${ACTUAL_SKILL_COUNT} skills`);
-        obj[check.path[0]] = newVal;
-        writeFileSync(fp, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
-        fixes.push(`${check.file}: ${match[1]} → ${ACTUAL_SKILL_COUNT}`);
+        let target = obj;
+        for (let i = 0; i < check.path.length - 1; i += 1) target = target?.[check.path[i]];
+        if (target && typeof target === 'object') {
+          target[check.path[check.path.length - 1]] = newVal;
+          writeFileSync(fp, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+          fixes.push(`${check.file}: ${match[1]} → ${ACTUAL_SKILL_COUNT}`);
+        } else {
+          errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: 'FIX_PATH_UNWRITABLE', expected: ACTUAL_SKILL_COUNT });
+        }
       } else {
         errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: match[1], expected: ACTUAL_SKILL_COUNT });
       }
@@ -138,9 +160,17 @@ for (const check of SKILL_COUNT_JSON_CHECKS) {
 }
 
 // Text files: extract the documented skill count.
+// v0.59.0：新增 usage-guide / platform-matrix / INSTALL.md（后者 3 条精确规则——不能用全局
+// 「N 个 skill」替换，因为 :797 的「其余 27 个」是 count-1，会被误改）。
 const SKILL_COUNT_TEXT_CHECKS = [
   { file: 'README.md', extract: /(\d+) skills/, replace: (content, count) => content.replace(/(\d+) skills/, `${count} skills`) },
   { file: 'AGENTS.md', extract: /Skills 索引（(\d+) 个）/, replace: (content, count) => content.replace(/Skills 索引（(\d+) 个）/, `Skills 索引（${count} 个）`) },
+  { file: 'docs/usage-guide.md', extract: /(\d+) 个 skills/, replace: (content, count) => content.replace(/(\d+) 个 skills/, `${count} 个 skills`) },
+  { file: 'docs/platform-matrix.md', extract: /(\d+) 个 skill 部署/, replace: (content, count) => content.replace(/(\d+) 个 skill 部署/, `${count} 个 skill 部署`) },
+  { file: 'INSTALL.md', extract: /应有 (\d+) 个 skill 目录/, replace: (content, count) => content.replace(/(\d+) 个 skill 目录/g, `${count} 个 skill 目录`) },
+  { file: 'INSTALL.md', extract: /包含 (\d+) 个 skill、/, replace: (content, count) => content.replace(/(\d+) 个 skill、/, `${count} 个 skill、`) },
+  { file: 'INSTALL.md', extract: /← (\d+) 个 skill（/, replace: (content, count) => content.replace(/← (\d+) 个 skill（/, `← ${count} 个 skill（`) },
+  { file: 'docs/release-checklist.md', extract: /all (\d+) skills/, replace: (content, count) => content.replace(/all (\d+) skills/, `all ${count} skills`) },
 ];
 
 for (const check of SKILL_COUNT_TEXT_CHECKS) {

package/scripts/guard/checks/dp3-approved.mjs

@@ -7,7 +7,7 @@ export function checkDp3Approved(changeDir) {
   if (!decision) {
     return {
       pass: false,
-      failures: ['DP-3 (dp_3_result) is not recorded — minimal contract approval is required before hotfix build'],
+      failures: ['DP-3 (dp_3_result) is not recorded — contract approval is required before build'],
     };
   }
 

package/scripts/guard/guard.mjs

@@ -33,7 +33,13 @@ const TRANSITION_CHECKS = {
   //（arch_baseline 缺失 → WARN 不 FAIL，项目级豁免）。
   'exploring:specifying':           ['arch-design', 'arch-readiness'],
   'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
-  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
+  // v0.59.0（decision-surrogate P4 审查发现）：**dp3-approved 新增**——原状 full 该转换只查
+  // dp-gate-passed（仅要求 dp_3_result 非空），而取值严格校验的 dp3-approved 只挂在 hotfix
+  // （见下方 WORKFLOW_TRANSITION_CHECKS）→ **安全档位倒置**：更重要的 full 用弱校验。后果是
+  // 任何能写 dp_3_result 的主体（含夜间替身的 HOLD 落盘）都能让 change 呈现"已批准"假象，
+  // 从而在无真实批准的前提下跨过 DP-3 硬门。本维度要求取值以 "approved" 开头
+  // （判据实现见 checks/dp3-approved.mjs）。
+  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved'],
   // v0.13 §49：test-matrix-ready 门禁前移——full 模式进入 executing 前强制测试准备度
   //（矩阵存在非空 OR 显式 skip 附理由；legacy 豁免）。hotfix/tweak 沿用 §45.3 豁免，不挂。
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready'],

package/scripts/lib/cmd-state.mjs

@@ -18,15 +18,18 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const SETTABLE_FIELDS = [
   'workflow', 'batches_completed', 'spec_merged',
   'dp_0_decisions', 'dp_0_confirmed', 'dp_0_timestamp', 'dp_0_result',
-  'dp_1_result', 'dp_1_timestamp', 'dp_1_decisions', 'dp_1_confirmed',
-  'dp_2_result', 'dp_2_timestamp', 'dp_2_decisions', 'dp_2_confirmed',
-  'dp_3_result', 'dp_3_timestamp', 'dp_3_decisions', 'dp_3_confirmed',
+  // v0.59.0（P4 实测）：dp_{1,2,3,5,6,7}_decisions / _confirmed 共 12 个字段已移除——
+  // 它们虽在旧白名单内，但 writeState 无对应序列化分支，tf state set 会**回显成功却零写入**
+  // （静默假成功；全仓零消费者）。dp_0_decisions / dp_0_confirmed 保留（二者确有序列化分支）。
+  'dp_1_result', 'dp_1_timestamp',
+  'dp_2_result', 'dp_2_timestamp',
+  'dp_3_result', 'dp_3_timestamp',
   // v2.1 §6.6/§6.7：GLAF4 委托决策与状态位（dp_4_result 仍由 tf execution plan --confirm 程序化写入，不在列表）
   'dp_4_glaf4_mode', 'dp_4_write_set_hash',
   'delegation_status', 'delegation_retry_count', 'delegation_partial_writes',
-  'dp_5_result', 'dp_5_timestamp', 'dp_5_decisions', 'dp_5_confirmed',
-  'dp_6_result', 'dp_6_timestamp', 'dp_6_decisions', 'dp_6_confirmed',
-  'dp_7_result', 'dp_7_timestamp', 'dp_7_decisions', 'dp_7_confirmed',
+  'dp_5_result', 'dp_5_timestamp',
+  'dp_6_result', 'dp_6_timestamp',
+  'dp_7_result', 'dp_7_timestamp',
   // Architecture design gate (v0.9 §26, v0.22.5 评审修复 F02)
   'arch_design_decision', 'arch_design_reason',
   'arch_design_timestamp', 'arch_design_artifacts',

package/skills/architecture-design/templates/conventions/frontend-patterns.md

@@ -10,6 +10,13 @@ date: 2026-07-31
 > 本文件由 team-flow 被动式自动沉淀机制维护（v0.11 §33）。
 > 请勿手动编辑模板——此文件作为参考模板，实际项目规范在 `.team-flow/conventions/frontend-patterns.md` 中维护。
 
+## 魔法值（v0.58.0）
+
+- **数值 / 字符串字面量 MUST NOT 散落在模板与脚本中**——收敛到 `src/constants/` 下的常量模块，或组件内具名常量。
+- 判据归属：`clean-code` skill 的「魔法值（前端）」判据，分级 **Critical**（与后端「不允许魔法常量」对齐；此前前端无任何等价约束）。
+- 可豁免：结构性索引（如 `arr[0]`）、CSS 取值、仅出现一次且语义自明的字面量。
+- 背景：v1 实测中前端因无约束，同一 change 内出现 21 处硬编码业务码与状态值，被审查降级为 Minor。
+
 ## 框架选型
 - （项目级规范在此补充，如：Vue 2 Options API）
 

package/skills/build-executor/SKILL.md

@@ -72,6 +72,8 @@ RED (write test, see it fail) → GREEN (write minimal code, see it pass) → RE
 ### Law 3: Review Before Drift
 Block on: logic defects, spec violations, missing required tests, unintended scope expansion.
 
+**Structural criteria（clean-code，v0.58.0）**：魔法值（未命名字面量）= Critical；函数长度 / 嵌套深度 / 参数个数 / 命名形式 = Minor；单一职责与 DRY 为审查必答项（无阈值）。**执行处是三个派发模板**（`implementer-prompt.md` / `task-reviewer-prompt.md` / `code-reviewer-prompt.md`）——它们各自内联了完整判据，因为由模板派发的子代理读不到 skill。本摘要仅供编排参考；判据真相源见 `clean-code` skill。
+
 ### Law 4: Rewind on Contract Break
 Return to `specifying` or `bridging` if: new behavior appears, interfaces change materially, design assumptions fail, artifacts no longer define intended implementation.
 

package/skills/build-executor/implementer-prompt.md

@@ -130,6 +130,25 @@ Subagent (general-purpose):
     - Are names clear and accurate (match what things do, not how they work)?
     - Is the code clean and maintainable?
 
+    **Structural criteria** — apply to every function this change adds or modifies:
+
+    - **Magic values** (unnamed numeric/string literals): name them as constants or enums.
+      This is **Critical** — do not ship unnamed literals. Applies to 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.
+    - **Single responsibility**: can the function name cover ALL steps in the body?
+      If not, split it — or state in your report which steps it cannot cover.
+    - **DRY**: is there a structurally equivalent logic block elsewhere in THIS repository
+      (ignore comments, whitespace, identifier names)? If the duplicate lives in the same
+      shared publish unit (same package / module / directory), extract a shared layer
+      rather than copying — if you judge copying is right, say why in your report.
+    - **Pre-existing code**: these criteria apply only to what this change touches. A hit
+      inside a function that already existed is Minor — register it in your report as
+      `存量待整改` rather than restructuring outside your task scope.
+
     **Discipline:**
     - Did I avoid overbuilding (YAGNI)?
     - Did I only build what was requested?

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/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，属「预防性一致处置」。