@aipper/aiws-spec 0.0.52 → 0.0.55

package/docs/skill-manifest.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "description": "Default skills installed by `aiws skill add`",
+  "sources": [
+    {
+      "source": "https://gitea.aipper.de/github/taste-skill",
+      "description": "67K-star collection: anti-slop frontend design rules (Impeccable Design, Zero Emoji, Phosphor Icons, layout diversification, etc.)"
+    },
+    {
+      "source": "https://gitea.aipper.de/github/skills",
+      "description": "Engineering workflow pipeline: grill-with-docs → to-spec → to-tickets → implement → code-review + tdd, domain-modeling, handoff, research, prototype, grill-me"
+    }
+  ],
+  "notes": [
+    "Add more sources here as curated defaults.",
+    "aiws-built-in skills (grill-me, ws-*, p-aiws-*) are shipped via templates and do not need listing here."
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.52",
+  "version": "0.0.55",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.opencode/README.md

@@ -0,0 +1,49 @@
+# OpenCode Skills — Two-Layer Architecture
+
+This workspace uses a layered skill architecture:
+
+## Layer 1: Engineering Pipeline (mattpocock/skills)
+
+Default entry for daily engineering work. Skills auto-load by intent.
+
+```
+/grill-with-docs  →  Design discussion with domain modeling + ADR
+/to-spec          →  Synthesize conversation into a spec
+/to-tickets       →  Break spec into executable tickets
+/implement        →  Implement from spec/tickets (with TDD)
+/code-review      →  Review against standards + spec
+/handoff          →  Compact session for handoff to another agent
+```
+
+Also available: `/tdd`, `/research`, `/prototype`, `/domain-modeling`, `/grill-me`, `/diagnosing-bugs`, `/resolving-merge-conflicts`, etc.
+
+## Layer 2: aiws Governance (ws-*)
+
+Supplemental skills for process, audit, and compliance. Use when the work needs:
+- Traceable goal/change/contract tracking
+- Completion gates and evidence
+- Spec/quality review process
+
+```
+/ws-goal                     →  Set auditable goal with dependency check
+/ws-plan                     →  Bind change with requirements contract
+/ws-dev / ws-dev-lite        →  Develop under AIWS constraints
+/ws-frontend-design          →  Apply frontend design rules
+/ws-finish                   →  Merge change + archive evidence
+/ws-spec-review              →  Process completeness audit
+/ws-quality-review           →  Implementation quality + test coverage
+/ws-verify-before-complete   →  Pre-finish validation gate
+```
+
+## When to Use Which
+
+| You want to... | Use |
+|---|---|
+| Explore and refine an idea | `/grill-with-docs` |
+| Create a spec from discussion | `/to-spec` |
+| Implement a well-defined feature | `/implement` (or `/ws-dev` if aiws governance needed) |
+| Fix a small bug quickly | `/ws-dev-lite` |
+| Review a branch | `/code-review` |
+| Audit process compliance | `/ws-spec-review` + `/ws-quality-review` |
+| Merge and archive | `/ws-finish` |
+| Design UI | `/ws-frontend-design` |

package/templates/workspace/.opencode/command/ws-frontend-design.md

@@ -0,0 +1,17 @@
+---
+description: 前端设计：视觉优先的 UI/UX 实现，先信息层级与构图，再组件细节
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-frontend-design -->
+# ws frontend design
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下交付可运行、可验证、视觉方向明确的前端界面。先信息层级与构图，再组件细节。品牌页重视觉锚点，产品页重可操作性。
+
+前置：
+1) 运行 `$ws-preflight` 读取真值文件。
+2) 判断任务类型：`landing`（品牌/营销）| `app-ui`（dashboard/工具）| `polish-only`（仅视觉提质）。
+3) medium/complex 任务先用 `$ws-plan` 落盘计划。
+
+详细设计指令见对应的 SKILL.md 文件：`skill(name="ws-frontend-design")`
+<!-- AIWS_MANAGED_END:opencode:ws-frontend-design -->

package/templates/workspace/.opencode/commands/using-aiws.md

@@ -15,13 +15,24 @@ description: 默认 workflow router：先判定阶段，再进入具体 ws-* 入
    - 若未检测到：输出 `OpenCode mode: standard-opencode`
 2) 若缺失任一真值文件：先 `/ws-preflight`，必要时运行 `aiws init .`，不要继续实现。
 3) 若任务意图、归因或验证入口不明确：先提 1-3 个关键澄清问题并停止。
-4) 路由规则：
-   - 需求/验收/合同变更：`/ws-req-review`
-   - 中大型实现或需要 change/worktree：`/ws-plan`
-   - 小步明确实现：`/ws-dev`（若是 simple/local 单点修复，可显式进入 `/ws-dev-lite`）
-   - 评审/审计：`/ws-review`
-   - finish / merge / push / cleanup：`/ws-finish`
-   - handoff / archive summary：`/ws-handoff`
+  4) 两层架构：默认走 mattpocock/skills 工程流水线，需要 aiws 治理时叠加 ws-*。
+     - 工程入口（mattpocock）：
+       - 需求澄清/设计探讨：`/grill-with-docs`（→ `/grilling` + `/domain-modeling`）
+       - 输出 spec：`/to-spec`
+       - 拆 tickets：`/to-tickets`
+       - 实现（含 TDD）：`/implement`
+       - 代码审查：`/code-review`
+       - 交接：`/handoff`
+     - 治理叠加（aiws ws-*）：
+       - 设定可审计目标：`/ws-goal`
+       - 绑定 change + contract：`/ws-plan`
+       - 小步实现（simple/local 单点修复）：`/ws-dev-lite`
+       - 完整开发（AIWS 约束下）：`/ws-dev`
+       - 前端设计规则：`/ws-frontend-design`
+       - aiws 规范/质量双审查：`/ws-spec-review` + `/ws-quality-review`
+       - 完成前验证：`/ws-verify-before-complete`
+       - 合并/推送/清理：`/ws-finish`
+       - 需求/验收/合同变更：`/ws-req-review`
 5) 输出 `OpenCode mode:` / `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`。
 6) 若 `Route: ws-dev` 且任务属于 simple/local 单点修复：`Next` 可显式建议 `/ws-dev-lite`。
 7) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。

package/templates/workspace/.opencode/skills/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary
+
+Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

package/templates/workspace/.opencode/skills/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/templates/workspace/.opencode/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session, using the `/domain-modeling` skill.

package/templates/workspace/.opencode/skills/tdd/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

package/templates/workspace/.opencode/skills/using-aiws/SKILL.md

@@ -68,7 +68,7 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 
 只问 1-3 个关键问题（意图、Req_ID/Problem_ID、verify、change），然后停止。
 
-### 4. Continuation Routing（新 session 恢复）
+### 4. Continuation Routing / 续跑决策表（新 session 恢复）
 
 change 相位 + goal 叠加；goal 优先于冷启动 plan/dev 跳过：
 
@@ -98,3 +98,4 @@ Root: / Found: / OpenCode mode: / Task intent: / Binding: / Route: / Why: / Next
 - subagent 不可用：单 agent，维护等价工件；不用 L4 程序化 skill invoke（agent 读规则后进入 skill）
 
 > 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`
+> Subagent-first 规范：`packages/spec/docs/opencode-subagent-first.md`

package/templates/workspace/.opencode/skills/ws-dev/SKILL.md

@@ -28,9 +28,30 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 
 ## TDD 约束（强制）
 
-新代码/业务逻辑改动必须 RED-GREEN-REFACTOR：
-1. **RED**：先写测试并确认失败 → 2. **GREEN**：最小实现通过 → 3. **REFACTOR**：保持绿
-禁止先实现后补测 / 跳过测试提交。改后自检：`lint → typecheck → test`（无脚本则跳过）。
+新代码/业务逻辑改动必须走 TDD 循环。以下参考自 `tdd` skill（已作为模板 skill 安装）。
+
+### 好测试的定义
+
+测试通过**公开接口**验证行为，而非实现细节。好的测试读起来像规范——"用户可以带着有效购物车结账"精确描述了功能——并且在重构后依然存活，因为它不关心内部结构。
+
+### Seams — 测试在哪写
+
+**Seam** 是你测试的公开边界：在不深入内部的前提下观察行为的接口。测试只写在 seam 处，绝不针对内部实现。
+
+**只在预先约定的 seam 处测试。** 写任何测试前，先写下测试的 seam 并与用户确认。没有测试写在未确认的 seam 上。事前约定 seams 让测试精力落在关键路径和复杂逻辑上，而不是每个边缘情况。
+
+### 反模式
+
+- **实现耦合** — mock 内部协作者、测试私有方法、或通过侧通道验证（查询数据库而非使用接口）。识别信号：重构时测试断裂但行为不变。
+- **同义反复** — 断言用代码本身的方法重算了预期值（`expect(add(a, b)).toBe(a + b)`），所以测试通过构造必然通过，永远不可能与代码矛盾。预期值必须来自独立真值源——已知正确的字面量、演算示例、spec。
+- **水平切片** — 先写完所有测试，再实现所有代码。批量测试验证的是"想象中"的行为。按**垂直切片**工作——一个测试 → 一段实现 → 重复，每个测试都是一颗响应当前学习成果的**示踪弹**。
+
+### 循环规则
+
+1. **RED**：先写失败测试 → 2. **GREEN**：仅实现足够通过的代码 → 3. **REFACTOR**：保持绿
+- 一次一个切片。一个 seam、一个测试、一次最小实现。
+- **重构不是循环的一部分。** 重构属于 review 阶段（见 `code-review` skill），不属于 RED→GREEN 实现循环。
+- 禁止先实现后补测 / 跳过测试提交。改后自检：`lint → typecheck → test`（无脚本则跳过）。
 
 ## 完成判定
 

package/templates/workspace/.opencode/skills/ws-plan/SKILL.md

@@ -74,7 +74,21 @@ OpenCode + oMo 优先策略：
 7) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
 8) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
    - 通过后：标记 `[workflow-state:plan:DONE]` 或 `[workflow-state:gate:plan_passed]`，表示 plan 阶段已收敛。
-8a) **Task Granularity Gate（T3）**：在 plan→dev 交接前，逐条验证计划中每步 ≤3 个原子操作（read/edit/write/run）：
+8a) **Optional Spec Phase**：若用户需要正式 spec 文档（PRD），在 plan 文件生成后追加一份 `docs/spec/<feature>.md`，模板如下（来自 to-spec skill）：
+    ```markdown
+    ## Problem Statement
+    用户视角的问题描述。
+    ## User Stories
+    As an <actor>, I want a <feature>, so that <benefit>（编号列表，全面覆盖）
+    ## Implementation Decisions
+    模块/接口/架构/API 合同（不含具体文件路径，避免过期）
+    ## Testing Decisions
+    好测试的定义（仅测试外部行为，非实现细节）+ 需要测试的模块 + 代码库中同类测试的先例
+    ## Out of Scope
+    明确不做的范围
+    ```
+    可选流程：sketch seams（代码库中已有的 seam 优先于新 seam）→ 与用户确认 seam 匹配 → 写 spec → 落盘。
+8b) **Task Granularity Gate（T3）**：在 plan→dev 交接前，逐条验证计划中每步 ≤3 个原子操作（read/edit/write/run）：
     - 若 any 步超限：拆细后再重新通过 ws-plan-verify，**不** 允许带着粗粒度任务进入 ws-dev
     - 仅当全部通过后才可标记 plan 完成并进入 ws-dev
     - 此门禁同样适用于 goal pipeline 的 Granularity Gate（c-i）—— ws-plan 的产出必须能通过下游检查

package/templates/workspace/.opencode/skills/ws-review/SKILL.md

@@ -62,6 +62,28 @@ OpenCode + oMo 优先策略：
       Quality review scope: <what to check> (if required)
       ```
     - Findings 格式要求：每个 finding 必须有 [Critical/Warning/Info] 级别标签 + 归因到 SPEC/QUALITY/REGRESSION 类别
+3a) **Two-Axis Review Methodology**（可选深化）。对于需要深入审查的变更，拆为两个正交维度并行审查（参考自 `code-review` skill）：
+    - **Standards** — 代码是否符合代码库的编码标准？携带下面的 smell baseline 作为默认基准。
+    - **Spec** — 代码是否忠实地实现了源需求/spec？
+    - 两轴并行运行，避免一个轴掩盖另一个。"符合所有标准但实现了错误需求" → Standards pass, Spec fail；"需求实现了但破坏了项目规范" → Spec pass, Standards fail。
+
+3b) **Code Smell Baseline**。Standards 轴在项目自有标准之外，始终携带以下 Fowler 代码坏味作为默认基准（项目标准高于基线）。每个坏味是启发式标签，不是硬性违规——跳过已由工具强制的内容。
+
+    | Smell | 识别信号 | 修复方向 |
+    |---|---|---|
+    | Mysterious Name | 名称不揭示作用 | 重命名；若找不到诚实名称，设计有问题 |
+    | Duplicated Code | 相同逻辑形状出现在多处 | 提取共享形状 |
+    | Feature Envy | 方法存取其他对象数据多于自身 | 把方法移到它嫉妒的数据上 |
+    | Data Clumps | 相同字段/参数反复出现 | 打包为一个类型 |
+    | Primitive Obsession | 原始类型代替领域概念 | 给概念自己的类型 |
+    | Repeated Switches | 对同类型的 switch/if 级联重复 | 多态或共享 map |
+    | Shotgun Surgery | 一个逻辑变更导致多处分散修改 | 聚合到一个模块 |
+    | Divergent Change | 一个文件因多个不相关原因被改 | 拆分，每个模块只为一个原因变 |
+    | Speculative Generality | 加了 spec 不需要的抽象 | 删除，直到真有需求 |
+    | Message Chains | 长链式导航 | 隐藏在第一个对象的方法后 |
+    | Middle Man | 类/函数主要只是委托转发 | 直接调用真正的目标 |
+    | Refused Bequest | 子类忽略大部分继承内容 | 组合替代继承 |
+
 4) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据