@yottameta/yotta-code-quality 0.3.0

package/install.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# yotta-code-quality 多智能体安装脚本（YottaSkills）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-code-quality"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@yottameta/yotta-code-quality",
+  "version": "0.3.0",
+  "description": "Pair-style code quality reviewer: twelve book-grounded decay risks (R1-R6, T1-T6) plus release-safety and first-paint UX checks; Iron Law findings (Symptom -> Source -> Consequence -> Remedy) and 0-100 Health Score.",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "yotta-code-quality",
+    "code-review",
+    "tech-debt",
+    "test-quality"
+  ],
+  "files": [
+    "SKILL.md",
+    "LICENSE",
+    "README.md",
+    "install.sh",
+    "references",
+    "bin",
+    "assets"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YottaMeta/yotta-code-quality.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "yotta-code-quality": "bin/install.js"
+  }
+}

package/references/AGENTS-template.md

@@ -0,0 +1,44 @@
+# AGENTS.md (drop-in template for any repo)
+
+> Copy the block below into your repo's `AGENTS.md` (or `CLAUDE.md` / `GEMINI.md`) so any
+> Agent-Skills-compatible agent applies the code-quality standard automatically.
+
+---
+
+# Engineering Standards (Code Quality Reviewer)
+
+This project uses the **yotta-code-quality** skill (grounded in twelve classic software-engineering
+books) for all code-quality work.
+
+## Core Purpose
+Diagnose code quality across twelve "decay risk" dimensions — six in production code (Cognitive
+Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder,
+Domain Model Distortion) and six in tests (Test Obscurity, Brittleness, Duplication, Mock Abuse,
+Coverage Illusion, Architecture Mismatch).
+
+## Rules (mandatory)
+- **The Iron Law:** NEVER suggest fixes before completing risk diagnosis. Every finding MUST follow:
+  **Symptom → Source → Consequence → Remedy**.
+- **Auto-trigger:** Proactively use the skill whenever discussing code quality, PR reviews,
+  architecture health, test quality, or technical debt.
+- **Scoring:** Base 100. Deductions: 🔴 Critical (−15), 🟡 Warning (−5), 🟢 Suggestion (−1). Floor 0.
+- **Project Config:** If `.code-quality.yaml` exists in the project root, read and apply it before
+  any review (settings: `disable`, `severity`, `ignore`, `focus`, `strictness`).
+- **Trigger boundaries:** Every review trigger must respect the skill's "Do NOT trigger for:" clause
+  to avoid false triggering (pure from-scratch code questions, syntax questions with no code shown).
+
+## Skill Integration (per agent)
+- **Codex CLI / Claude Code / Cursor / Gemini / generic agents:** the skill loads from the agent's
+  skills folder (`~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`, etc.). Invoke by name
+  or let it auto-trigger on code-quality discussion.
+- **WorkBuddy:** the skill lives in `~/.workbuddy/skills/yotta-code-quality/`; the assistant loads
+  it via the Skill tool when code quality is in scope.
+
+## Report Convention
+Output the standardized report (`Mode / Scope / Health Score / Findings[Critical→Warning→Suggestion]
+/ Summary`). Keep Iron Law field labels and book titles in English; translate the rest to the user's
+language.
+
+---
+
+> Note: prefer instructions in this file when an agent operates in this repository.

package/references/common.md

@@ -0,0 +1,141 @@
+# Code Quality Reviewer — Shared Framework
+
+**Single source of truth** for project config, report template, Health Score math, and opt-in history/triage.  
+Risk symptom tables: `decay-risks.md`, `test-decay-risks.md`, `editorial-extensions.md`.  
+Book grounding: `source-coverage.md` (Architecture / disputes only — not every Quick pass).
+
+## The Iron Law
+
+```
+NEVER suggest fixes before completing risk diagnosis.
+EVERY finding must follow: Symptom → Source → Consequence → Remedy.
+Default: report only — edit code only on explicit fix / --fix.
+```
+
+## Project Config
+
+Before review, try `.code-quality.yaml` at repo root. Missing → defaults (all risks on, `balanced`).
+
+### Settings
+
+- **`disable`** — skip risk codes (R1–R7, T1–T6, UX1).
+- **`severity`** — force `critical` | `warning` | `suggestion` per code.
+- **`ignore`** — glob exclude (e.g. `**/*.generated.*`).
+- **`focus`** — only these codes; cannot combine with non-empty `disable`.
+- **`strictness`** — `strict` | `balanced` (default) | `legacy-friendly`.
+- **`history`** — `true` writes `.code-quality-history.json` trend; default `off` (see History Tracking).
+- **`suppress`** — list of `{ id, reason, expires? }` from opt-in triage (see below).
+
+```yaml
+version: 1
+strictness: balanced
+disable: []
+severity: {}
+ignore:
+  - "**/*.generated.*"
+  - "**/node_modules/**"
+suppress: []
+history: false
+```
+
+### Validation
+
+- Bad risk code / severity → skip that entry, note `Config warning: …`.
+- Both `disable` and `focus` non-empty → ignore both, note error.
+- Bad `strictness` → `balanced`.
+- YAML parse fail → defaults.
+- Expired `suppress` entries → ignore them (treat as active findings again).
+
+If config applied, after **Scope**:  
+`Config: .code-quality.yaml applied (strictness: …, N disabled, M ignored)`
+
+## Auto Scope
+
+- **PR:** `git diff --cached` → `git diff` → `git diff main...HEAD` (or `master`) → ask.
+- **Architecture / debt:** whole project; `--since=<ref>` → modules of changed files only.
+- **Test quality:** test files; prefer co-located with production diff.
+- Always print `Scope: …`. Skip generated/lock/minified; note skips.
+
+## Report Template (canonical)
+
+User’s language for prose. English: Iron Law field labels, book titles, smell names, headers.
+
+```markdown
+# Code Quality Review
+
+**Mode:** [Quick / PR Review / Architecture Audit / Tech Debt / Test Quality / Release Gate]
+**Scope:** […]
+**Health Score:** XX/100 *(per-run deduction index, not an absolute grade)*
+
+[One-sentence verdict]
+
+---
+
+## Findings
+
+### 🔴 Critical
+**[Risk Name] — [Short title]**
+Symptom: […]
+Source: [Book — Principle or Smell | Editorial — R7/UX1]
+Consequence: […]
+Remedy: […]
+
+### 🟡 Warning
+… (same)
+
+### 🟢 Suggestion
+… (same)
+
+---
+
+## Summary
+[2–3 sentences: highest-leverage action + trend if any]
+```
+
+Sort Critical → Warning → Suggestion. Omit empty tiers. If &gt; 5 findings, one-line **Recommended fix order**.
+
+## Health Score
+
+Base 100. Deduct by `strictness`:
+
+| Preset | Critical | Warning | Suggestion |
+|--------|----------|---------|------------|
+| `strict` | −20 | −8 | −2 |
+| `balanced` | −15 | −5 | −1 |
+| `legacy-friendly` | −8 | −3 | −1 |
+
+Floor 0. Still report every finding. Under `legacy-friendly`, Summary leads with three highest-leverage fixes.  
+For aging codebases with no prior quality gate, prefer stating `legacy-friendly` in Scope when the user did not choose `strict`.
+
+## Remedy Mode (opt-in)
+
+Only if user says fix / `--fix`. Implement each Remedy as minimal behavior-preserving edits; re-review those findings; do not widen scope.
+
+## History Tracking (opt-in)
+
+**Default: off.** Enable only if user asks for history/trend, or `.code-quality.yaml` has `history: true`.
+
+When enabled: append to `.code-quality-history.json`:  
+`{ date, mode, score, findings: { critical, warning, suggestion }, scope }`.  
+Prior same-mode run → `**Trend:** A → B (±N)`. First run → `First run — no trend data`.  
+**Write failure:** print `History: skipped (reason)` — never invent a trend.
+
+## Post-Report Triage (opt-in)
+
+**Default: off.** Enable only if user says 「逐条处理」 / `--triage`, and the session is interactive (skip in CI/headless).
+
+For Warning/Suggestion (lowest severity first): `[a]ccept / [d]ismiss / [f]defer / [s]kip`.  
+- dismiss → `suppress: [{ id, reason }]`  
+- defer → same + `expires: YYYY-MM-DD` (default +90 days)  
+Do not block delivering the main report on triage.
+
+## Reference routing
+
+| File | When |
+|------|------|
+| `editorial-extensions.md` | Release gate; UI/splash; anti-over-flag disputes |
+| `decay-risks.md` | Production findings needing severity/source |
+| `test-decay-risks.md` | Test findings / PR Step 7 |
+| `pr-review-guide.md` | Full PR process |
+| `source-coverage.md` | Architecture / book tradeoffs |
+| `examples.md` | Calibrate tone / score |

package/references/decay-risks.md

@@ -0,0 +1,252 @@
+# Decay Risk Reference (Production Code)
+
+Six patterns that cause software to degrade. Apply the Iron Law to each finding.
+
+## Risk 1: Cognitive Overload (R1)
+
+**Diagnostic question:** How much mental effort does a human need to understand this?
+
+Cognitive load beyond working memory causes mistakes, avoidance, and blocks the refactoring that
+would fix it.
+
+### Symptoms
+- Function longer than 20 lines where multiple levels of abstraction are mixed.
+- Nesting depth greater than 3 levels.
+- Parameter list with more than 4 parameters.
+- Magic numbers or unexplained constants.
+- Variable names that require reading the implementation to understand (e.g., `d`, `tmp2`, `flag`).
+- Boolean expressions with 3+ conditions combined.
+- Train-wreck chains: `a.getB().getC().doD()`.
+- Code names that do not match what the business calls the same concept.
+- Flag Arguments: a boolean parameter that makes a function do two fundamentally different things.
+- Primitive Obsession: domain concepts as primitives (`String email`, `int orderId`, `double money`)
+  rather than value types.
+- Shallow module: interface/documentation more complex than the functionality provided.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Long Method | Fowler — Refactoring | Long Method |
+| Long Parameter List | Fowler — Refactoring | Long Parameter List |
+| Message Chains | Fowler — Refactoring | Message Chains |
+| Flag Arguments | Fowler — Refactoring | Flag Arguments |
+| Primitive Obsession | Fowler — Refactoring | Primitive Obsession |
+| Function length and nesting | McConnell — Code Complete | Ch. 7: High-Quality Routines |
+| Variable naming | McConnell — Code Complete | Ch. 11: The Power of Variable Names |
+| Magic numbers | McConnell — Code Complete | Ch. 12: Fundamental Data Types |
+| Domain name mismatch | Evans — Domain-Driven Design | Ubiquitous Language |
+| Shallow Module | Ousterhout — A Philosophy of Software Design | Ch. 4: Modules Should Be Deep |
+
+### Severity Guide
+- 🔴 Critical: function > 50 lines, nesting > 5, or virtually no meaningful names.
+- 🟡 Warning: function 20–50 lines, nesting 4–5, some unclear names.
+- 🟢 Suggestion: minor naming issues, 1–2 magic numbers, isolated train-wreck chains.
+
+### What Not to Flag
+- Linear code with clear names and guard clauses is not automatically high cognitive load.
+- Internal implementation detail hidden behind a deep, simple module boundary is not a shallow-module problem.
+- Domain-specific terminology is fine if it matches how experts actually speak.
+
+---
+
+## Risk 2: Change Propagation (R2)
+
+**Diagnostic question:** How many unrelated things break when you change one thing?
+
+Each change ripples to unrelated modules, slowing velocity and multiplying regression risk.
+
+### Symptoms
+- Modifying one feature requires touching > 3 files in unrelated modules.
+- One class changes for multiple different business reasons.
+- A method uses more data from another class than from its own.
+- Two classes know each other's internal state directly.
+- Changing one module requires recompiling/retesting many unrelated modules.
+- **Hyrum's Law**: with sufficient callers, every observable behavior (implementation details,
+  error message text, coincidental call ordering, undocumented side effects) becomes an implicit
+  contract callers depend on.
+- **Orthogonality violation**: changing one dimension forces edits in unrelated dimensions.
+- **Information Leakage**: a design decision (file format, protocol, data shape) encoded in > 1
+  module, so changing it needs coordinated edits.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Shotgun Surgery | Fowler — Refactoring | Shotgun Surgery |
+| Divergent Change | Fowler — Refactoring | Divergent Change |
+| Feature Envy | Fowler — Refactoring | Feature Envy |
+| Inappropriate Intimacy | Fowler — Refactoring | Inappropriate Intimacy |
+| Orthogonality violation | Hunt & Thomas — The Pragmatic Programmer | Ch. 2: Orthogonality |
+| DIP violation | Martin — Clean Architecture | Dependency Inversion Principle |
+| High change propagation radius | Brooks — The Mythical Man-Month | Brooks's Law (communication overhead) |
+| Hyrum's Law | Winters et al. — Software Engineering at Google | Ch. 1: Hyrum's Law |
+| Information Leakage | Ousterhout — A Philosophy of Software Design | Ch. 5: Information Hiding and Leakage |
+
+### Severity Guide
+- 🔴 Critical: one change touches > 5 files, or structural dependency inversion (domain depends on infrastructure).
+- 🟡 Warning: one change touches 3–5 files, mild coupling between modules.
+- 🟢 Suggestion: minor coupling, easily isolatable.
+
+### What Not to Flag
+- A composition root wiring concrete dependencies is not a DIP violation by itself.
+- A stable public API with intentionally supported behavior is not automatically Hyrum's Law debt.
+- Coordinated edits inside one bounded context may be normal, not shotgun surgery.
+
+---
+
+## Risk 3: Knowledge Duplication (R3)
+
+**Diagnostic question:** Is the same decision expressed in more than one place?
+
+Multiple copies drift apart silently. DRY is about decisions, not code lines.
+
+### Symptoms
+- Same logic copy-pasted across files or functions.
+- Same concept named differently (`user`, `account`, `member`, `customer`).
+- Parallel class hierarchies that must change in sync.
+- Config values repeated as literals in multiple places.
+- Two modules implementing the same algorithm independently.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Code duplication | Fowler — Refactoring | Duplicate Code |
+| Parallel Inheritance | Fowler — Refactoring | Parallel Inheritance Hierarchies |
+| DRY violation | Hunt & Thomas — The Pragmatic Programmer | DRY |
+| Inconsistent naming | Evans — Domain-Driven Design | Ubiquitous Language |
+| Alternative Classes | Fowler — Refactoring | Alternative Classes with Different Interfaces |
+
+### Severity Guide
+- 🔴 Critical: core business logic duplicated across modules, or same domain concept named 3+ ways.
+- 🟡 Warning: utility code duplicated, naming inconsistent within a subsystem.
+- 🟢 Suggestion: minor literal duplication, single naming inconsistency.
+
+### What Not to Flag
+- Repetition across separate bounded contexts is not automatically duplicate knowledge.
+- Temporary duplication during an active extraction/migration is not necessarily debt.
+- Shared protocol constants at explicit boundaries may be acceptable when local ownership is clearer.
+
+---
+
+## Risk 4: Accidental Complexity (R4)
+
+**Diagnostic question:** Is the code more complex than the problem it solves?
+
+Accidental complexity accumulates addition by addition until developers fight scaffolding more than
+solving the problem.
+
+### Symptoms
+- Abstractions built "for future use" with no current consumer.
+- Classes that barely justify existence (wrap a single method call).
+- Classes that only delegate without adding behavior (pure middle-men).
+- Second attempt at a system significantly more elaborate than the first.
+- Switch statements signaling missing polymorphism.
+- Config options never changed from defaults.
+- Framework code larger than the application it powers.
+- Code grown under sustained tactical shortcuts.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Speculative Generality | Fowler — Refactoring | Speculative Generality |
+| Lazy Class | Fowler — Refactoring | Lazy Class |
+| Middle Man | Fowler — Refactoring | Middle Man |
+| Switch Statements | Fowler — Refactoring | Switch Statements |
+| Second System Effect | Brooks — The Mythical Man-Month | Ch. 5: The Second-System Effect |
+| YAGNI violations | McConnell — Code Complete | Ch. 5: Design in Construction |
+| Over-engineering | Hunt & Thomas — The Pragmatic Programmer | Topic 4: Good-Enough Software |
+| Tactical programming debt | Ousterhout — A Philosophy of Software Design | Ch. 3: Strategic vs. Tactical Programming |
+
+### Severity Guide
+- 🔴 Critical: entire subsystem built around a speculative requirement, or framework overhead dominates domain logic.
+- 🟡 Warning: several unnecessary abstractions or wrapper classes, unused config systems.
+- 🟢 Suggestion: one or two lazy classes or middle-men in non-critical paths.
+
+### What Not to Flag
+- A switch over an external protocol, wire format, or closed enum is not automatically missing polymorphism.
+- Thin wrappers that absorb vendor churn or hide instability may be justified.
+- A larger second version is not second-system effect unless added generality exceeds present needs.
+
+---
+
+## Risk 5: Dependency Disorder (R5)
+
+**Diagnostic question:** Do dependencies flow in a consistent, predictable direction?
+
+When business logic depends on infrastructure, infrastructure changes cascade into domain changes.
+Cycles prevent isolation.
+
+### Symptoms
+- Circular dependencies between modules/packages.
+- High-level business logic directly imports low-level infrastructure (domain service imports a DB driver).
+- Stable, widely-used components depend on unstable, frequently-changing ones.
+- Abstract components depending on concrete implementations.
+- Law of Demeter violations: `order.getCustomer().getAddress().getCity()`.
+- Module fan-out > 5.
+- A module implements an interface but uses only a subset (ISP violation: fat interface).
+- "One mind did not design this" — incompatible patterns with no clear rule for which to use where.
+- Direct version-pinned deps on transitive packages (diamond dependency / upgrade blockage).
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Dependency cycles | Martin — Clean Architecture | Acyclic Dependencies Principle (ADP) |
+| DIP violation | Martin — Clean Architecture | Dependency Inversion Principle (DIP) |
+| Instability direction | Martin — Clean Architecture | Stable Dependencies Principle (SDP) |
+| Abstraction mismatch | Martin — Clean Architecture | Stable Abstractions Principle (SAP) |
+| ISP violation | Martin — Clean Architecture | Interface Segregation Principle (ISP) |
+| Conceptual integrity | Brooks — The Mythical Man-Month | Ch. 4: Conceptual Integrity |
+| Law of Demeter | Hunt & Thomas — The Pragmatic Programmer | Ch. 5: Decoupling and the Law of Demeter |
+| SOLID violations | Martin — Clean Architecture | SRP, OCP |
+| Diamond dependency | Winters et al. — Software Engineering at Google | Ch. 21: Dependency Management |
+
+### Severity Guide
+- 🔴 Critical: dependency cycles present, or domain layer directly depends on infrastructure layer.
+- 🟡 Warning: several SDP/DIP violations but no cycles; conceptual inconsistency across modules.
+- 🟢 Suggestion: minor Demeter violations, slightly elevated fan-out in isolated modules.
+
+### What Not to Flag
+- High fan-out in an orchestration layer or composition root is not automatically disorder.
+- Adapter modules may depend on both domain and infrastructure when they explicitly translate across the boundary.
+- A stable facade over many leaf dependencies can be healthy if dependency policy is clear.
+
+---
+
+## Risk 6: Domain Model Distortion (R6)
+
+**Diagnostic question:** Does the code faithfully represent the problem it is solving?
+
+Code that mismatches business language forces mental translation. Over time it models schemas instead
+of the domain, with logic bleeding into service layers.
+
+### Symptoms
+- Business logic scattered across service layers while domain objects have only getters/setters
+  (anemic domain model).
+- Names that do not match what business stakeholders call the concept.
+- A class whose only purpose is to hold data with no behavior (pure data bag).
+- A subclass that ignores/overrides most of its parent's behavior (Refused Bequest).
+- Bounded context boundaries crossed without translation or anti-corruption layer.
+- Methods more interested in another class's data than their own (Feature Envy).
+- A subclass overrides parent methods with incompatible behavior or throws where the parent
+  guarantees success (LSP violation).
+- Value Objects treated as Entities (mutable ID + lifecycle instead of replacement on change).
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Anemic Domain Model | Evans — Domain-Driven Design | Domain Model pattern |
+| Ubiquitous Language drift | Evans — Domain-Driven Design | Ubiquitous Language |
+| Bounded context violation | Evans — Domain-Driven Design | Bounded Context |
+| Data Class | Fowler — Refactoring | Data Class |
+| Refused Bequest | Fowler — Refactoring | Refused Bequest |
+| Feature Envy | Fowler — Refactoring | Feature Envy |
+| LSP violation | Martin — Clean Architecture | Liskov Substitution Principle (LSP) |
+
+### Severity Guide
+- 🔴 Critical: domain logic entirely in service layer, domain objects are pure data bags.
+- 🟡 Warning: partial anemia, some naming inconsistency between code and domain language.
+- 🟢 Suggestion: minor naming drift in non-core areas, isolated cases of Feature Envy.
+
+### What Not to Flag
+- CRUD-heavy workflows may legitimately use transaction scripts instead of rich domain objects.
+- DTOs, persistence records, and API payload models are allowed to be data-only.
+- Shared infrastructure language is not domain drift if the business model itself is simple.

package/references/editorial-extensions.md

@@ -0,0 +1,63 @@
+# Editorial Extensions (R7 · UX1 · Anti-over-flag)
+
+These are **maintainer additions** on top of the twelve book-grounded risks. Use the same Iron Law.  
+For Source line prefer `Editorial — Release Safety` / `Editorial — First-paint UX` unless a classic book truly fits.
+
+## R7 — Release / Supply-chain Safety
+
+**Diagnostic:** Could this change let a user or attacker run untrusted code, leak credentials, or ship an insecure update path *today*?
+
+### Symptoms (non-exhaustive)
+
+- Secrets in repo or scripts: cloud AK/SK, private signing keys, tokens in plaintext.
+- Updater / installer: signature verification skipped, missing pubkey, artifacts unsigned while “auto-update” is on.
+- Production DevTools / debug features left enabled in release builds.
+- CSP `null` / wildly open `connect-src` / `unsafe-eval` in production without documented need.
+- `curl | sh` or equivalent in docs/scripts aimed at end users.
+- Dependency or plugin allowlists that effectively disable sandboxing for convenience.
+
+### Severity guide
+
+- **Critical** — plaintext cloud/signing secrets; updater skip-verify in shipped config; release build with interactive DevTools.
+- **Warning** — CSP missing or far too open; unsigned release channel “temporarily”; debug flags gated poorly.
+- **Suggestion** — docs still showing insecure sample commands; dual unused pubkeys causing foot-guns.
+
+### What not to flag
+
+- Local `tauri:dev` / debug feature flags clearly scoped to development.
+- Test fixtures with fake keys labeled as such.
+- Security work tracked but intentionally deferred with a visible ticket — note tradeoff, don’t Critical-spam.
+
+---
+
+## UX1 — First-paint / Status Clarity
+
+**Diagnostic:** In the first seconds after open (or primary state change), does the user see a coherent status — or empty chrome / lying copy?
+
+### Symptoms
+
+- Splash or loading UI stuck to a corner / zero-height flex parent; solid brand-color empty window for seconds.
+- “Loading / 校验中” state that can never appear (dead field always false).
+- Status label disagrees with enforcement (UI says licensed; gates treat as free — or the reverse).
+- Blocking modal that appears before any readable context.
+
+### Severity guide
+
+- **Critical** — rare; only if users cannot proceed at all with no feedback (hard stuck blank).
+- **Warning** — empty first paint lasting seconds; loading/status lies systematically.
+- **Suggestion** — minor mis-centering; copy polish.
+
+### What not to flag
+
+- Intentionally minimal splash with centered content that works.
+- Skeleton loaders that are clearly loading.
+
+---
+
+## Anti-over-flag (apply before raising R1 especially)
+
+1. Line-count / nesting thresholds are **hints** — require mixed abstraction levels or branch density for Warning+.
+2. **UI markup** (large JSX/SwiftUI view bodies that are mostly layout): default Suggestion or skip unless business rules are embedded.
+3. **Generated / obfuscated / vendor** paths: skip (note in Scope).
+4. One-off scripts and installers: prefer R7 over R1 style nits.
+5. If unsure between Warning and Suggestion, choose Suggestion and state the uncertainty once.