@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/testing-strategy/references/e2e-real-flow-testing.md

@@ -0,0 +1,71 @@
+# E2E And Real-Flow Testing
+
+Use this for critical user journeys, cross-service flows, release smoke, browser workflows, and runtime integration that lower-level tests cannot prove.
+
+## When E2E Is Worth It
+
+- Login/onboarding/payment/publish/export/import or other primary user flows.
+- Permission-sensitive or role-sensitive workflows.
+- Cross-service state change where API, UI, worker, and persistence must align.
+- Browser-specific interaction such as routing, forms, uploads, keyboard/safe-area behavior, dialogs, or responsive layout.
+- Release smoke for the highest-risk changed path.
+
+Before adding a new E2E test, create or update the scenario matrix in `scenario-testing.md`. Keep only the cross-boundary proof in E2E; push deterministic permutations down to unit, contract, component, or integration tests.
+
+## Browser E2E Rules
+
+- Use stable selectors or accessible labels; avoid brittle text-only or CSS-position selectors.
+- Prefer accessibility-tree element references or role/name selectors when the browser tool supports them; they survive layout changes better than coordinates or CSS paths.
+- Re-read visible state after every action that should change the page.
+- Wait for explicit conditions: URL transition, visible text, DOM state, event, network idle, persisted state, or backend signal.
+- Avoid fixed sleeps except as a last resort with a clear reason.
+- Use isolated browser/session contexts for different users or roles.
+- Save authenticated state only when the test is not about login.
+- Capture console errors, failed network requests, screenshots/traces/video when useful.
+- Use network interception only to control nondeterminism or assert payloads; do not mock away the contract that the E2E test is meant to prove.
+- **Playwright 1.5x baseline (Microsoft, ongoing 2024-2026)** is the current default-recommendation browser-E2E framework for new web testing. Key features to use deliberately, per `playwright.dev` docs: (a) **Trace Viewer** is the load-bearing debugging surface — every CI failure should produce a `trace.zip` artifact. Set `trace: 'retain-on-failure'` (not `'on-first-retry'`) when CI runs with `retries: 0` for deterministic gating — `'on-first-retry'` produces no trace unless the test actually retries, leaving teams with zero diagnostics on first-failure-then-fix-the-flake debugging cycles. Reviewers open the artifact locally or via `trace.playwright.dev` to step through actions, screenshots, network, and console without re-running the test. (b) **Soft assertions** via `const softExpect = expect.configure({ soft: true })` let one test report multiple failures rather than stopping at the first — useful for state-snapshot assertions where the team wants the whole-page diff in one run, NOT a substitute for the "one test, one behavior" discipline. (c) `toMatchAriaSnapshot()` (Playwright 1.49+) is the structured accessibility-tree assertion — call it on a locator (`expect(page.locator('main')).toMatchAriaSnapshot(...)` or `await page.locator(...).ariaSnapshot()`), preferred over DOM-string snapshots for resilience to non-semantic markup changes. (d) **Component testing** (`@playwright/experimental-ct-{react,vue,svelte}`) is still labeled experimental — use Vitest browser mode for component-level tests until Playwright component-test API stabilizes. (e) **Projects** in `playwright.config.ts` define run matrices (browser × device emulation × baseURL × config variant) and produce one merged HTML report. Note: Projects ≠ sharding — sharding is a separate `--shard=k/n` mechanism that splits a single project's tests across multiple workers/machines; teams often combine both (projects for the matrix, sharding for parallelism per project). Pin worker count and shard count for CI determinism, do not let auto-detect choose. Routing the per-stack Playwright config implementation goes to `web-react-dev/references/web-quality-release.md`; this skill owns the test-layer policy.
+
+## Runtime QA Sweep
+
+Use this only as bounded runtime acceptance / release-smoke evidence for the scenario-matrix paths whose risk needs runtime proof — it is not exploratory QA and cannot close coverage on its own; push deterministic permutations down to unit/contract/component/integration tests. When smoke-testing a running web surface, sweep these bug categories (not only the one happy path); several are invisible in the rendered UI unless you look:
+
+- **Functional:** dead controls (click does nothing), broken or wrong-destination links, form validation that is missing or bypassable, state not persisting across refresh / back-button, and double-submit or stale-data races.
+- **Console / network:** check the console *and* the network panel after interactions, not only on load. Watch uncaught JS exceptions, failed 4xx/5xx user-path requests, and the often UI-silent classes — CORS failures, mixed content (an HTTP resource on an HTTPS page), CSP violations, and deprecation warnings (these surface in the console and frequently as blocked/failed network entries). **Classify before calling any of them a defect** (per the skill's verification-warning rule): product-owned exceptions, failed supported-user-path requests, enforced CSP breaks, blocked mixed content, and unexpected CORS on a supported environment are defects; CSP report-only entries, expected negative/preflight denials, dev-only proxy noise, and third-party deprecations outside the team's control are observations unless they block a supported user path or the current slice caused them — record owner + residual risk rather than failing the sweep blindly.
+- **Performance:** cumulative unexpected layout shift across the page lifecycle (CLS — e.g. content jumping after a late-loading image or ad, not only after first paint), and request-pattern smells (unexpected growth versus baseline, duplicate requests, N+1 fan-out, unbounded polling, or unbatched fetches). A high request count alone is not a smell — dashboards, feeds, maps, and streaming surfaces legitimately make many requests with documented pagination or parallel panels.
+- **Auth boundary:** what the surface does when logged out and across the relevant user roles, not only the authenticated happy path. **Run these only against staging, synthetic tenants, or read-only / dry-run paths.** Verify privileged or destructive actions by their guardrails — visibility, disabled state, confirmation copy, permission denial, and audit metadata — or via a dry-run / mocked request; do NOT execute the privileged/destructive action itself (irreversible writes, account/session changes, money/quota mutations, deletes, admin repairs) against real data as part of a sweep. A genuine end-to-end test of such an action is a separately-authorized E2E case against synthetic data, never a sweep step.
+
+Capture evidence per the `Browser E2E Rules` above (console/network/screenshot/trace). Preserve every runtime failure or ambiguous red signal as evidence and route it through `defect-diagnosis` (label "confirmed defect" only after triage — never drop or greenwash an unconfirmed failure). Proven categories belong in the `scenario-testing.md` matrix and lower-layer tests, not re-verified by hand every release.
+
+A sweep is **report-and-route, not fix-in-place**: document each finding (severity, category, expected-vs-actual, repro evidence) and route it through `defect-diagnosis` for triage — only confirmed defects proceed to cause + fix + regression evidence; observations (CSP report-only, expected denials, third-party deprecations, ambiguous reds) stay recorded with owner, residual risk, and follow-up path, not treated as defects before triage. During the sweep, treat product/runtime code as read-only (external-state mutation stays governed by the auth-boundary rule above — controlled synthetic/dry-run submits for the functional checks are fine; unrequested or real-data destructive mutation is not): you may write evidence artifacts and scoped QA/test files when they are part of the requested deliverable, but do not make a finding green by patching product code, so a read-only QA / acceptance pass cannot silently become unrequested code changes. If the current-turn request explicitly asks for QA *and* fixing, close the sweep evidence first, then start a separate `defect-diagnosis` phase before any product-code edit.
+
+## Backend/API Real Flows
+
+- Assert response envelope, canonical error code, trace/log id, persisted state, emitted event, and dependency outcome.
+- Include setup and teardown or use isolated test tenants/namespaces.
+- Make idempotency, retry, and compensation behavior visible.
+- Treat live-data scripts, production-like IDs, replay tools, and tests that only log or panic on error as diagnostic until they are isolated, repeatable, and assertion-based.
+
+## Verify The World, Not The Self-Report
+
+When the subject under test is an agent's or automation's own output — a file it says it wrote, a command it says it ran, a state it reports — the assertion re-observes the world independently through **read-only inspection of durable effects**: re-read the file from disk, query the authoritative persisted state, and assert that files the run should not have touched are byte-identical. An audit/log record counts only when it is emitted by an authoritative subsystem **outside the subject's own write/control boundary** and is correlated to the operation and the resulting state — a success record the subject wrote itself is a durable self-report, not evidence; when no independent durable-state observation is safely available, classify the check as incomplete rather than pass it on the record. Re-run a reported command only when it is known read-only or idempotent and confined to a test-owned resource — re-running a deployment, migration, payment, or retry mutates state a second time and still cannot show the original run happened. A keyword probe over the agent's own transcript or summary is not evidence — it lets a cheating or mistaken agent pass. Such tests own their resources: create the harness inside the test and dispose it in a teardown hook that runs on cooperative failure, retry, and in-process timeout — and, because a hard-killed runner never reaches teardown, back durable or external resources with an out-of-process cleanup: tag them with the run id and a TTL and run a bounded janitor/finalizer keyed to that run, so repeated CI runs cannot leak state or retain sensitive test data. Put shared fixtures in a plain helper module rather than importing another spec (re-registering its cases duplicates real runs). The delegation-side rule (do not accept a sub-agent's report as proof) is owned by `multi-agent-delegation`.
+
+## Published Entry Path
+
+When the deliverable ships as a built or installed artifact — a package `bin`, a bundled worker or non-index runtime entry, a plugin loaded by a real loader, a container image — at least one smoke must enter through that published path: the built artifact under the plain runtime, the real loader boot, the installed command. Dev/source-path runners, hot loaders, and hand-mounted test compositions mask module-resolution failures, settle races, and swallowed load errors that only the shipped path exposes; this is the "green unit tests, broken product on start" class. Mock only external services or nondeterministic inputs in that smoke and assert model-visible request/log, durable state, or user-visible output; a genuinely missing config must exit non-zero.
+
+## E2E Scope Control
+
+- Do not reproduce every unit branch through E2E.
+- Keep E2E flows few, stable, and tied to user/business risk.
+- Prefer one happy path plus high-risk negative paths over many shallow click-throughs.
+- A click-through without assertions is not E2E evidence.
+- If a scenario can be proven with a stable API/contract/integration test and only needs one browser smoke for confidence, do not duplicate all permutations in the browser.
+
+## Failure Handling
+
+If E2E fails:
+
+- Treat it as a real signal until proven invalid.
+- Preserve trace, screenshot, console/network errors, payload, and environment.
+- Route through `defect-diagnosis`.
+- Do not replace the scenario with a thinner mock-only test unless the E2E scenario was invalid or redundant.

package/dist/assets/marketplace/plugins/ccl-skills/skills/testing-strategy/references/fitness-functions.md

@@ -0,0 +1,240 @@
+# Architecture Fitness Functions
+
+把架构 invariants 写成**自动化测试**，每次 build / CI 跑 — 架构不再靠口头约定 + 文档守护。
+
+不替代普通单测 / e2e；这是**结构性约束**的测试（无循环依赖 / 分层不越界 / latency budget / etc）。
+
+## 外部来源
+
+- **Neal Ford / Rebecca Parsons / Patrick Kua**, *Building Evolutionary Architectures* (O'Reilly, 1st ed 2017) + **+ Pramod Sadalage** (2nd ed Dec 2022) — fitness function 定义 + 分类
+- **ThoughtWorks Tech Radar** — "Architecture Fitness Functions"（Trial → Adopt）
+- **ArchUnit / NetArchTest / Dependency-Cruiser** — 工具示例
+
+---
+
+## §1 定义
+
+**Fitness function**：可执行的测试 / 检查，判断**架构是否仍符合某个所声明的不变量**。失败 = 架构 drift / 违反预设。
+
+与普通测试区别：
+- **单测 / e2e**：测**业务正确性**（"用户能否完成 X 流程"）
+- **fitness function**：测**结构正确性**（"X 模块是否仍是无依赖 leaf；p99 是否仍 < 100ms；DAL 是否仍唯一 DB 访问出口"）
+
+---
+
+## §2 分类（精选自 Ford et al. taxonomy）
+
+Ford 等原书有更多维度（Temporal / Intentional vs Emergent / Domain-specific / Coverage / Proactivity 等；2nd ed 2022 reframe 为 Scope/Cadence/Result/Invocation/Proactivity/Coverage）。本 ref 只取最高 ROI 的 4 个常用维度：
+
+| 维度 | 选项 | 含义 |
+|---|---|---|
+| **Atomic vs Holistic** | atomic | 测单个 attribute（如纯 latency）|
+|  | holistic | 多 attribute 组合下的行为（latency 在 50% CPU 时仍 < 100ms）|
+| **Triggered vs Continuous** | triggered | CI / commit / merge 触发 |
+|  | continuous | 生产持续监控（与 §5 集成）|
+| **Static vs Dynamic** | static | 无需运行代码（grep / AST / dep graph）|
+|  | dynamic | 需运行（load test / chaos）|
+| **Automated vs Manual** | automated | CI 卡点 |
+|  | manual | code review checklist / 季度审计 |
+
+本 ref 重点：**triggered + static / dynamic + automated**（最高 ROI），manual 类只在 automated 不可行时用。
+
+---
+
+## §3 典型 fitness function 例
+
+### 3.1 模块依赖 / 分层（static + automated）
+- 无循环依赖：`go vet` / `dep-cruiser` / ArchUnit `slicesShouldBeFreeOfCycles()`
+- 分层不越界：`domain` 不依赖 `infrastructure`；`infrastructure` 不能 import `web` handler
+- 实现：ArchUnit (Java) / dep-cruiser (JS/TS) / go-arch-lint (Go) / pytest-arch (Python)
+
+### 3.2 数据访问出口（static + automated）
+- **Invariant**：DB 操作只能经特定模块（如 `repository/` 包）；HTTP 出口只能经特定 client 包
+- **Go 例**：linter 检查其它包不能 `import "database/sql"` / ORM 包；业务代码不能 `import "net/http"`
+- **其它栈类比**：Python — 检查非 DAL 模块不 `import sqlalchemy`；JS/TS — eslint rule 阻 `import 'pg'` 在 service 层外
+
+### 3.3 性能 budget（dynamic + automated）
+- p99 latency < 100ms：CI 跑 benchmark / load test 卡 budget
+- bundle size < N kB：webpack-bundle-analyzer / size-limit CI 卡
+- cold start < N ms：benchmark + 阈值（适用 serverless / CLI / mobile startup / container scale-to-zero / plugin host；常驻 backend 服务不必）
+
+### 3.4 复杂度上限（static + automated）
+- 单 function 圈复杂度 ≤ 10：gocyclo / radon / eslint complexity rule
+- 单文件行数 ≤ 500：linter rule
+- API 总数 ≤ N：API gateway config 检查
+
+### 3.5 安全 invariants（static + automated）
+- 无硬编码 secret：gitleaks / trufflehog / 自写 grep
+- HTTPS only：lint config
+- SQL 不拼接：linter（sqlc / 检查 ORM 使用）
+
+### 3.6 接口稳定性（dynamic + automated）
+- OpenAPI breaking-change 检测：oasdiff / openapi-diff
+- proto breaking-change：buf breaking
+- DB migration 向后兼容：linter（pt-online-schema-change 兼容性）
+
+---
+
+## §4 实现路径
+
+### 4.1 起手 — 3 个原则
+
+1. **每个 fitness function 必有 owning decision record**（ADR 或同等 reason 记录）：function 测的是哪个决定的 invariant？没记录 = function 易被随便删。新发现的 guardrail 可先以 reason comment 起步，**当它编码 material 架构 invariant 时 promote 到 ADR**
+2. **Fail loud, fail early**：CI 红，不只是 warning；本地 pre-commit 也跑
+3. **每个 function 必有名字 + reason**：commit message / config 写明"why this function exists"，避免后人删时不知 trade-off
+
+### 4.1.1 规范到健康度检查
+
+团队研发规范要能落成项目健康度检查，而不是只靠人工 review。把每条规范先分类：
+
+| 类型 | 适合检查的内容 | 执行器 |
+|---|---|---|
+| Deterministic | 文件/目录、IDL、生成产物、配置、依赖锁、CI、覆盖率、命令、日志字段、trace 字段 | 脚本、lint、测试、CI |
+| Agent review | 分层是否绕过、领域边界、组件职责、测试有效性、Spec 对齐、异常/降级语义 | bounded agent prompt + evidence packet |
+| Manual | 需要真实账号、真机、外部审批、生产窗口或人工判断的项 | 手工证据 + owner + 到期时间 |
+| Not automatable yet | 当前没有稳定输入或工具的项 | 缺口记录 + 自动化计划 |
+
+健康度报告至少包含：规则 id、规范来源、severity、检查类型、执行命令或 agent prompt、证据、结果、owner、CI 行为。结果只能是 `pass`、`fail`、`blocked`、`inconclusive` 或 `not_applicable`。CI 只卡 `blocker` 或团队已声明卡关的规则；warning/info 进入报告并要求责任人，不伪装成通过。
+
+脚本负责事实，agent 负责判断。不要让 agent 去猜文件是否存在、覆盖率是多少、CI 是否配置；也不要让脚本用 grep 代替架构判断。任何检查类型缺少具体证据时都不得写成 `pass`。`agent_review` 没有具体证据、超时、范围不足或只返回泛泛结论时，结果必须是 `inconclusive`。`manual` 在人工证据到位前必须是 `blocked` 或 `inconclusive`；`not_automatable_yet` 必须是 `blocked` 或 `not_applicable`，并记录缺口和自动化计划。
+
+字段存在不等于链路正确。grep/lint 只能证明日志字段、trace 字段、请求头或配置项存在；跨 HTTP/RPC/MQ/worker/client 的传播必须由集成测试、E2E/host smoke、运行时观测证据，或明确的 `agent_review` 判断补足后才能写成 `pass`。
+
+**grep 不够时优先 AST；标准库 AST 是常见零依赖路径——但别当反射、也别因没装第三方工具就退回 grep smell 或 defer 成 `not_automatable_yet`。** 代码形态类确定性检查（"边界是否返回 ad-hoc error dict"、"导出函数是否传 ctx"等）用 grep 既会被注释/字符串内同形文本误匹配、又易被改写绕过，只能算 `smell-grep / advisory`（命中=待查、干净≠合规）。要做成 `deterministic`：**先看现有工具/lint 选项 + owner 决定**；没有合适第三方工具时，**Python `ast`、Go `go/ast` 是 stdlib 零依赖路径**（JS/TS 的 TypeScript compiler API / ESLint / Babel parser **不是 stdlib**，仅在仓里已装时用，否则记一个 tooling 决定、别号称零依赖）。自写检查器**有真实成本**（正确性、parser 边界、维护——看似简单的检查可能要多轮才稳），只对**窄的、高价值的枚举不变量**这么做，并配 test harness（正例命中、反例不误报、坏 scope 报 `inconclusive` 不报 clean）；需要完整类型/数据流分析才能判的形态，**保持 `blocked`/`inconclusive` + 自动化计划**，别硬 ship 一个半成品 linter。AST 只对**枚举形态**确定，把覆盖边界（抓哪些、哪些是 accepted residual）写进文档与 result-schema，干净跑只代表"未发现枚举形态"。
+
+### 4.1.2 语言基本规范 conformance — 示例 fitness functions
+
+承载 `service-language-basics` 规范的可机判子集。本轮 ship **确定性 AST 检查**（stdlib，不依赖 semgrep/ast-grep）：解析 AST → 不误匹配注释/字符串里的同形文本、能抓 grep 抓不到的形态。**确定性边界（诚实）**：只对下列**枚举形态**确定；"是否真伪造错误 / 是否真传 ctx"语义上不可判定，干净跑 = "未发现枚举形态"，**非完全合规**。ccl-skills 只 ship 可采纳件；**机械 firing 发生在消费仓**（接 pre-commit / CI），ccl-skills 对外部仓无强制力 → opt-in，未采纳前对应规范仍是 salience + 人 review 兜底。
+
+**LB-1 — Python 在边界用返回值伪造错误**（check_type：`deterministic`，限枚举形态）
+
+- owner：`python-service-dev`；severity：warning → blocker（消费仓采纳后定）。
+- 脚本：`python3 skills/testing-strategy/scripts/lang-basics-ast-check.py <transport_paths>`（stdlib `ast`，零三方依赖）。配套 test harness `lang-basics-ast-check.test.sh`。
+- scope：只传 transport / handler / view / router 路径；**pure / domain 层豁免**（那里允许 `Result` / `Either`）。
+- 抓的形态（含旧 grep 抓不到的）：`{"success"/"ok": False}`（任意引号）、`{SUCCESS: False}`（常量键）、`dict(success=False)`、`return (data, err/error/exc/e)`、`return (None, <msg>)`。**注释 / 字符串内同形文本不误报**（AST 不看），故无需 `# lb-allow` 抑制机制。
+- 残留未覆盖（诚实）：ad-hoc `{"code":...,"message":...}`（与合法 envelope 无类型/流分析难分，不抓，避免误伤）、经变量别名传递的 error 对象；比 return root / 一层构造器 / `(body, status)` tuple 更深的嵌套或动态构造的 fake dict 不抓——这是枚举形态边界，不是 bug。
+- 退出码：`1`=命中（fail）；`2`=scope 无效 / 语法错（inconclusive，绝不报 clean）；`0`=未发现枚举形态（**≠完全合规**）。
+- result-schema：`{"rule_id":"py.error.boundary_return_fake","severity":"warning","check_type":"deterministic","status":"pass|fail|inconclusive","evidence":["file:line"],"owner":"python-service-dev"}`。
+
+**LB-2 — Go ctx 传播**（check_type：`deterministic` proxy）
+
+- owner：`go-microservice-dev`；severity：warning → blocker（按层）。
+- 脚本：`go run skills/testing-strategy/scripts/lang-basics-go-check.go <dir>`（go/ast；**目录用 `go run`，单文件先 `go build`** —— `go run` 会把尾随 `.go` 当成源文件）。配套 test harness `lang-basics-go-check.test.sh`。
+- 抓的形态：非 `main`/`init` 函数里调 `context.Background()` / `context.TODO()` —— 常见的"丢了 caller 的 ctx、自造 root ctx"信号（丢 cancel/deadline/trace 传播）。解析 per-file import 名，**alias（`import ctx "context"`）与 dot-import 都能抓**。`_test.go` 跳过（目录遍历与显式文件参数都跳）；`vendor`/`.git`/`testdata`/`node_modules` 跳过。
+- **proxy 边界 + 已接受残留（诚实）**：低误报代理，非完整"导出 IO 函数缺 ctx 形参"检查（需 `go/types`）。**接受的残留**（修了反而误伤合法用法）：① `main`/`init` 内的闭包/goroutine 调 Background 不报（常是合法 background worker）；② 局部变量 shadow 了 context alias / dot-import 的 `Background` 名可能误报。干净跑 ≠ 每个函数都正确传 ctx。
+- 退出码同 LB-1。
+
+### 4.1.3 客户端 language-basics conformance — 示例 fitness functions
+
+承载 `client-language-basics`（spec 006）规范的可机判子集，覆盖 `web-react-dev` / `app-cross-platform-dev` / `miniapp-product-dev` / `terminal-cli-dev` 四个客户端 surface 栈。把 Go/Python 的 language-basics（分层=依赖方向、错误契约、ctx/取消传播）映射到客户端 analog。
+
+**关键诚实（与 005 不同的客户端现实）**：
+
+- **生态 linter 是默认执行器，非组织自写脚本**。不像 Go/Python（`go/ast`/`ast` stdlib 零依赖、且 LB-1/LB-2 抓的是 `go vet`/`ruff` 漏掉的窄不变量），客户端 language-basics **多数已被成熟生态 linter 覆盖**：JS/TS 的 `eslint-plugin-react-hooks` + `@typescript-eslint` + `dependency-cruiser`、Dart 的 `dart analyze`+`flutter_lints`、Kotlin 的 detekt+Android Lint、Swift 的 SwiftLint。**故客户端 conformance 的 deterministic 那半 = enforce 这些生态规则的 config**，不重写成自写检查器（重复劳动 + monotonic）。
+- **JS/TS / Dart / Kotlin / Swift 的 AST 都不是 stdlib**：自写检查器要么依赖消费仓 toolchain（TS compiler / custom_lint / detekt custom rule / SwiftLint custom rule）→ **记 tooling 决定，不号称零依赖**；要么退化 source-text 扫读（advisory-leaning，命中=待查）。**不 ship 半成品自写 parser**（见 §4.1.1）。
+- 每栈 analyzer 默认规则集**很薄**（RN 默认仅 2 条 hooks 规则；SwiftLint 安全规则多 opt-in；Dart lints 默认 `info` 严重度不卡 CI，需 `analyzer>errors:` 升级；detekt 多条 inactive）→ **"开/升级 baseline" 本身是每栈 setup 义务**，写进消费仓 conformance config。
+
+**A. 全栈 STD 覆盖（开/升级生态规则即可，禁自写）** — 错误处理（空/泛 catch、typed throw）+ 空安全（强解包禁令）两族全栈 STD：
+
+| 栈 | deterministic 执行器（生态规则，需 enable/config） |
+|---|---|
+| web/RN(JS/TS) | `react-hooks/rules-of-hooks`·`exhaustive-deps`·`set-state-in-effect`·`error-boundaries`(v6+)；`@typescript-eslint/no-explicit-any`·`no-floating-promises`·`no-misused-promises`·`only-throw-error`(typed，需 `parserOptions.project`)；`no-empty`；tsconfig `strict`(+`noUncheckedIndexedAccess`)；dep-cruiser `forbidden`/`no-circular`、ESLint `no-restricted-imports`/`no-restricted-globals` |
+| Flutter/Dart | `flutter_lints` baseline + `empty_catches`·`avoid_catches_without_on_clauses`·`only_throw_errors`·`use_rethrow_when_possible`·`unawaited_futures`·`discarded_futures`·`cancel_subscriptions`·`close_sinks`·`use_build_context_synchronously`·`avoid_dynamic_calls`；**`analyzer>errors:` 升级严重度**（关键 gotcha） |
+| Android/Kotlin | detekt `exceptions/*`(SwallowedException·TooGenericExceptionCaught/Thrown·PrintStackTrace)·`empty-blocks/EmptyCatchBlock`·`coroutines/*`(GlobalCoroutineUsage·InjectDispatcher·SleepInsteadOfDelay·SuspendFunSwallowedCancellation)·`potential-bugs/UnsafeCallOnNullableType`(`!!`)·`LateinitUsage`；开 inactive 规则；Kotlin explicit-API 编译 flag |
+| iOS/Swift | SwiftLint `force_try`·`force_cast`(默认) + 启用 opt-in `force_unwrapping`·`no_empty_block`·`untyped_error_in_catch`·`weak_delegate`·`private_outlet`·`implicitly_unwrapped_optional` |
+
+权威源：react.dev / typescriptlang.org / typescript-eslint.io / dependency-cruiser；dart.dev linter-rules+effective-dart；developer.android.com architecture + detekt.dev；swift.org API guidelines + realm.github.io/SwiftLint。
+
+**B. 本轮 ship 的 runnable 检查器**（生态无标准规则 + 高价值 + 低依赖低误报，对标 LB-1/LB-2）：
+
+**CB-1 — terminal `no-hardcoded-ANSI`**（check_type：`deterministic`，语言无关，Python stdlib 零依赖）
+
+- owner：`terminal-cli-dev`；权威源 clig.dev Output（capability-aware lib + `TERM=dumb`）；severity：warning → blocker（消费仓采纳后定）。
+- 脚本：`python3 skills/testing-strategy/scripts/client-terminal-ansi-check.py <src-path...> [--allow=<substr>]...`。配套 test harness `client-terminal-ansi-check.test.sh`（green）。
+- 抓的形态：源码字面 ESC 编码（`\x1b` / `\x1B` / `\033` / `\e` / `` / `\u{1b}` / 裸 ESC 0x1b）后跟 **CSI `[` 或 OSC `]`** 引导符——OSC 覆盖 hyperlink/OSC-52 clipboard（terminal §6 视其为安全边界）。仅扫源码扩展名（不误伤 golden/fixture）。`--allow=` 豁免渲染/ANSI 模块路径。
+- 诚实边界：抓"硬编 CSI/OSC 转义字面存在"，**不**判语义（是否走 capability lib / NO_COLOR / isatty 守卫=agent-review）；只覆盖 CSI/OSC 引导符（charset `\x1b(`、DCS `\x1bP`、经变量传递的 ESC 不抓）；**不跟随 symlink 目录**（os.walk 默认）。干净跑 = 已遍历非 symlink 源树未发现硬编转义，≠完全合规。
+- 退出码：`1`=命中；`2`=scope 无效/不可读（inconclusive，绝不报 clean）；`0`=未发现。
+- result-schema：`{"rule_id":"terminal.ansi.hardcoded_escape","severity":"warning","check_type":"deterministic","status":"pass|fail|inconclusive","evidence":["file:line"],"owner":"terminal-cli-dev"}`。
+
+> **miniapp `react-dom`/`TARO_ENV` conformance is executed by ESLint config, NOT a repository script** (see C). A regex/source-text Python checker for these was prototyped and **rejected**: across adversarial-challenge rounds it spawned the SAME class of new defect each round (`/*` inside a string literal flipping comment state, whitespace around `process.env . TARO_ENV`, multiline forms…) — i.e. it was re-implementing a JS lexer in regex, the half-baked-parser anti-pattern (005 §4.1.2). JS/TS already has an AST linter; the correct executor is ESLint, which gets string/comment/whitespace state right for free. (CB-1 stays a script because terminal/CLI has NO ecosystem ANSI-aware linter and a byte-scan needs no JS parser.)
+
+**C. executor config 模板（生态 linter = 默认执行器，非仓库自写脚本）**
+
+miniapp `react-dom` ban + DOM/BOM ban + `TARO_ENV`-confinement — repo-authored ESLint config (runs on the real AST, so string/comment/whitespace edge-cases are handled correctly; owner `miniapp-product-dev`, sources developers.weixin.qq.com js-support + docs.taro.zone envs):
+
+```jsonc
+// .eslintrc — mini-program build target (exempt H5 via an overrides block on *.h5.* / h5/**)
+"rules": {
+  // CB-2a: no react-dom (logic layer has no DOM); also bans react-dom/* and type-only imports
+  "no-restricted-imports": ["error", { "patterns": ["react-dom", "react-dom/*"] }],
+  // no DOM/BOM globals in mini-program runtime
+  "no-restricted-globals": ["error", "window", "document", "navigator", "localStorage"],
+  // CB-2b: TARO_ENV branching only in the adapter/platform layer — confine via an overrides block
+  // that ENABLES this rule for src/**, then DISABLES it for src/adapters/** and *.{weapp,alipay,tt,...}.*
+  "no-restricted-syntax": ["error", {
+    "selector": "MemberExpression[property.name='TARO_ENV'][object.property.name='env'][object.object.name='process']",
+    "message": "process.env.TARO_ENV branching belongs in the adapter/platform layer, not scattered"
+  }]
+}
+```
+
+Layering/dependency-direction (**全栈 custom 旗舰，无 out-of-box 规则**) likewise落各栈 import-ban config——JS/TS dep-cruiser `forbidden`、Kotlin Konsist/ArchUnit 或 custom detekt、Dart custom_lint、Swift custom；点禁用 `no-restricted-imports`。这些都是**消费仓 config**，由对应 client `*-dev` owner 提供/维护，不在 ccl-skills 落 runnable 脚本。
+
+**D. backlog（named owner + 触发条件，不半 ship）**：每栈 dispose 生命周期 / 取消协作（Swift Task `isCancelled`、RN useEffect abort）/ 语义吞异常 / JS-TS finite-value 集中 / 分层自定义规则——需 AST/类型分析或各栈 toolchain，触发=该栈消费仓启用 dep-conformance CI 时拾取。
+
+### 4.2 起步 sequencing
+新项目从最便宜的开始上：
+1. **Linter rules**（语法 / 命名 / 简单依赖）— 零启动成本，本地 IDE 即时反馈
+2. **Static dep graph 检查**（无循环 / 分层）— 几分钟接入 dep-cruiser / go-arch-lint
+3. **Pre-existing tools 的 invariant 模式**（gitleaks / breaking-change linter）— 1 小时接入
+4. **Performance budget**（最贵 — 需要稳定 load test 环境）— 项目稳定后再上
+
+### 4.3 与 ADR 配合
+每个 ADR 的 Consequences 段如果声明了"承诺保持 X"，对应应有 fitness function 验。
+
+例：ADR-0007 "DAL is only DB access point" → fitness function `no_db_import_outside_repository_pkg`。
+
+没 fitness function = consequences 仅口头承诺，迟早违反。
+
+---
+
+## §5 与现有 skill 的映射
+
+| Fitness function 类型 | 集成进哪 |
+|---|---|
+| Linter / static dep | 各 stack-dev skill（`go-microservice-dev` / `python-service-dev` / `web-react-dev` / `app-cross-platform-dev` / `miniapp-product-dev`）的 CI gate |
+| Performance budget | 见 `testing-strategy/references/test-code-authoring-patterns.md` §3 (slow test heuristic) + `platform-observability` 运行时验证 |
+| Breaking change detection | `test-artifact-management/references/source-to-case-workflows.md` §D (schemathesis / Pact / Dredd) — 契约层 fitness function |
+| Security invariants | code review + `code-review` skill（CI 集成）|
+| R&D standards conformance | `product-rd-workflow` owns the standards family and conformance map; this reference owns the executable invariant model; stack skills own concrete commands |
+| Repo-local agent contracts | `agents-file-coverage-gate` for AGENTS.md coverage; `product-rd-workflow` decides when contract changes are required |
+
+- Security-invariant reviews must route through `code-review`; the selected CLI keeps its local provider and model configuration.
+
+### 5.1 健康度检查输出
+
+Prefer a stable machine-readable result so CI, dashboards, and agents can reuse it:
+
+```json
+{
+  "rule_id": "go.contract.idl_first",
+  "severity": "blocker",
+  "check_type": "deterministic",
+  "status": "pass",
+  "evidence": ["idl repo found", "generated package imported by service"],
+  "owner": "service owner",
+  "ci_gate": true
+}
+```
+
+For `agent_review` checks, include the prompt or review packet path and quote only the concrete finding summary, not the whole source. If the review cannot make a concrete judgment from the evidence packet, emit `inconclusive` with the missing evidence; never convert it to `pass`. A health score is optional; blockers, failed gates, and evidence quality matter more than a single number.
+
+---
+
+## §6 故意不借鉴
+
+| 概念 | 原因 |
+|---|---|
+| Ford 等 *Building Evolutionary Architectures* 整书的 evolutionary architecture 哲学 | 完整哲学体系太重；本 ref 只取 fitness function 这个 actionable 部分 |
+| Mutation testing 作架构 fitness function | mutation 测的是 test suite quality，已在 `test-artifact-management/references/source-to-case-workflows.md` §C.1；不重复 |
+| Chaos engineering 全套（Netflix Chaos Monkey 等）| 是 reliability fitness function 的具体方法，归 `platform-release-engineering` 实现层 |