@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/phases/understand/rules.md

@@ -0,0 +1,49 @@
+# Understand Rules (UND-*)
+
+## UND-001: Intent Documentation
+**Severity:** MUST
+**Description:** Before any specification or implementation, the business intent MUST be documented. Intent includes: what is being built, why, and how success is measured.
+**Valid:** Intent captured in `aidlc/requirements.md` with `affects: [...]` before spec delta.
+**Invalid:** Starting spec delta or feature files without documented intent or without an `affects` declaration.
+
+## UND-002: EARS Format
+**Severity:** MUST
+**Description:** All functional requirements MUST use EARS syntax (Ubiquitous, Event-Driven, State-Driven, Unwanted, or Optional).
+**Valid:** `When a user submits valid credentials, the system SHALL return a JWT token.`
+**Invalid:** `The login should work well and be fast.`
+
+## UND-003: BDD Scenario Coverage
+**Severity:** MUST
+**Description:** Each functional requirement MUST have at least 3 BDD scenarios covering positive, negative, and edge cases. Scenarios MUST be tagged with the FR namespace prefix (`@NATIVE-`, `@DESKTOP-`, `@WEB-`, `@BE-`, `@WXA-`, `@MYA-`, `@TTA-`, or `@INT-`).
+**Valid:** `@WEB-FR-001 @positive` with three scenarios per FR.
+**Invalid:** One scenario per FR, or missing namespace prefix.
+
+## UND-004: Affects Declaration
+**Severity:** MUST
+**Description:** Every spec delta MUST declare `affects: [native, desktop, web, backend, wxa, mya, tta, contracts]`.
+**Valid:** `## Change: CHG-001 — User Login\nAffects: [web, backend, contracts]`
+**Invalid:** Spec delta without an `affects` declaration.
+
+## UND-005: Cross-Component Feature Decomposition
+**Severity:** MUST
+**Description:** A feature that affects ≥2 components MUST be split into: one FR per component, one or more `INT-*` FRs, and a `aidlc/features/cross-stack/*.feature` file.
+**Valid:** `affects: [web, backend]` → `WEB-FR-001`, `BE-FR-001`, `INT-FR-001`, plus cross-stack feature file.
+**Invalid:** A single feature file claiming to test both web and backend behavior.
+
+## UND-006: Contract-First for Cross-Component
+**Severity:** MUST
+**Description:** When a feature introduces or changes a public API or event consumed by another component, a contract file MUST be added or updated in `aidlc/contracts/` before any per-component implementation.
+**Valid:** `aidlc/contracts/api/auth.yaml` defines `POST /auth/login` before any code.
+**Invalid:** Per-component code that depends on a contract not in `aidlc/contracts/`.
+
+## Gate Automation
+
+以下 CDH 命令可用于自动化部分 gate 检查：
+
+| Gate | CDH Command | Checks |
+|------|-------------|--------|
+| UND-002 | `cdh aidlc validate --ears` | EARS 语法格式 |
+| UND-003 | `cdh aidlc validate --bdd` | BDD scenario 覆盖率 |
+| FR Namespace | `cdh aidlc validate --fr` | FR prefix 一致性 |
+
+**注意**：这些是辅助工具，最终 gate 仍需人工审查。

package/ai-dlc-skill/phases/verify/config/base_url.md

@@ -0,0 +1,65 @@
+---
+name: verify-config-base-url
+description: Base URL configuration for local Web verification
+triggers:
+  - base url
+  - local url
+  - localhost
+allowed_tools:
+  - Read
+phases:
+  - verify
+---
+
+# Base URL Configuration
+
+## Default Ports by Component Type
+
+| Component | Default Port | Start Command |
+|-----------|--------------|---------------|
+| Web (React/Vue) | 3000 | `npm run dev` |
+| Web (Next.js) | 3000 | `npm run dev` |
+| Web (Vite) | 5173 | `npm run dev` |
+| Backend API | 8080 | `npm run start` |
+| Storybook | 6006 | `npm run storybook` |
+
+## How to Determine Port
+
+AI Agent should:
+
+1. Read `apps/web/package.json`
+2. Extract port from `scripts.dev` or `scripts.start`
+3. Parse common patterns:
+   - `--port {N}` or `--port={N}`
+   - `PORT={N}`
+   - `-p {N}` or `-p{N}`
+
+Example parsing:
+
+```bash
+# Extract port from package.json
+cat apps/web/package.json | jq -r '.scripts.dev' | grep -oE '[0-9]+'
+```
+
+## Stack Preview URL
+
+If application is deployed via `cdh stack preview`:
+- Stack URL is set in environment variable `STACK_URL`
+- AI Agent should prioritize `STACK_URL` over localhost
+
+## Configuration Precedence
+
+1. `STACK_URL` environment variable (if set)
+2. `BASE_URL` environment variable (if set)
+3. `http://localhost:{PORT}` from package.json parsing
+4. Default: `http://localhost:8080`
+
+## Verification
+
+Before running E2E tests, verify base URL is reachable:
+
+```bash
+curl -f -m 5 http://localhost:3000
+# HTTP 200 = reachable
+# Connection refused = not running
+```

package/ai-dlc-skill/phases/verify/entry.md

@@ -0,0 +1,59 @@
+---
+name: ai-dlc-verify
+description: "Verify Phase: TDD Red-Green-Refactor → Contract Test → Quality Gates"
+entry_point: phases/verify/entry.md
+triggers:
+  - verify
+  - TDD
+  - test
+  - quality-gate
+---
+
+# Verify Phase (验证)
+
+Execute TDD per BDD scenario, verify contracts, enforce quality gates.
+
+## Lifecycle
+
+See `lifecycle.md` for the full phase flow.
+See `rules.md` for enforceable rules (VRF-001 to VRF-006 + INT-001 to INT-006).
+See `prompt.md` for the sub-agent delegation prompt template.
+
+## 当被委派时
+
+0. 先调用 `TodoClear` 清除上阶段遗留的 todos，确保从空白计划开始
+1. 按 DAG 顺序对每个 unit 执行 TDD Red→Green→Refactor（见 `aidlc/CONFIG.md` 测试目录）
+2. 运行合约测试 + 检查 backward-compat
+3. 运行 cross-stack e2e
+4. 执行质量门禁（cov≥80%, 0 vulns, no TODO）
+
+## Browser E2E Gate
+
+当触发 Web E2E 验证时，执行 Local Browser E2E 测试：
+
+1. **扫描测试文件**
+   - 扫描 `apps/web/tests/e2e/*.spec.ts`
+   - 如无测试文件，返回 `skipped`
+
+2. **确定目标应用**
+   - 读取 `apps/web/package.json` 中的端口配置
+   - 默认使用 `http://localhost:8080`
+
+3. **执行测试**
+   ```bash
+   cd apps/web
+   npx playwright test --project=chromium
+   ```
+
+4. **返回结果**
+   - 解析 Playwright JSON 报告
+   - 提取 passed/failed/skipped counts
+
+参见：[gates/browser_e2e.md](gates/browser_e2e.md)
+
+## 产出
+
+- 各组件的单元/集成/e2e 测试
+- `aidlc/tests/contract/` 合约测试
+- `aidlc/tests/cross-stack/` 跨栈测试
+- `aidlc/packages/shared/` 生成的共享类型

package/ai-dlc-skill/phases/verify/gates/browser_e2e.md

@@ -0,0 +1,96 @@
+---
+name: browser-e2e-gate
+description: Local Web E2E verification using Playwright
+triggers:
+  - web e2e
+  - browser test
+  - playwright
+  - e2e verification
+  - browser e2e gate
+allowed_tools:
+  - Bash
+  - Read
+  - Glob
+phases:
+  - verify
+---
+
+# Browser E2E Gate
+
+## Overview
+
+Execute local Web application end-to-end tests using Playwright framework.
+
+## Workflow
+
+1. **Identify Target Application**
+   - AI Agent determines the Web component under test
+   - Determine local service port (default 8080)
+   - Read `apps/web/package.json` to extract port from `scripts.dev`
+
+2. **Check Test Files**
+   - Scan `apps/web/tests/e2e/*.spec.ts`
+   - If no test files exist, return `status: "skipped", message: "No e2e tests found"`
+
+3. **Verify Base URL Reachability**
+   ```bash
+   curl -f http://localhost:{PORT}
+   # Must return HTTP 200
+   ```
+
+4. **Execute Tests**
+   ```bash
+   cd apps/web
+   npx playwright test --project=chromium --reporter=json
+   ```
+
+5. **Parse Results**
+   - Parse Playwright JSON report
+   - Extract: passed/failed/skipped counts
+   - If failures exist, extract error messages
+
+## Output Format
+
+```json
+{
+  "gate": "browser_e2e",
+  "status": "passed|failed|skipped",
+  "total": 10,
+  "passed": 9,
+  "failed": 1,
+  "duration_ms": 15000,
+  "failures": [
+    {
+      "test": "login.spec.ts › should login successfully",
+      "error": "Timeout waiting for element #dashboard"
+    }
+  ]
+}
+```
+
+## Quality Gate Criteria
+
+| Criterion | Threshold | Rule |
+|-----------|-----------|------|
+| Test Pass Rate | 100% | WEB-E2E-002 |
+| Base URL | Reachable | WEB-E2E-003 |
+| Test Files | Must exist | WEB-E2E-001 |
+
+## Error Handling
+
+| Error | Handling |
+|-------|----------|
+| Port unreachable | Return `status: "error", message: "Cannot connect to localhost:{PORT}"` |
+| No test files | Return `status: "skipped", message: "No e2e tests found"` |
+| Test failure | Return `status: "failed"` + failure details |
+| Playwright not installed | Return `status: "error", message: "Playwright not installed"` |
+
+## Integration with Verify Phase
+
+This gate is invoked during Verify phase when:
+- WEB component exists
+- BDD scenarios at e2e layer need verification
+
+See also:
+- [runners/playwright_local.md](../runners/playwright_local.md)
+- [config/base_url.md](../config/base_url.md)

package/ai-dlc-skill/phases/verify/lifecycle.md

@@ -0,0 +1,217 @@
+# AI-DLC Phase 3: Verify (验证)
+
+Execute TDD red-green-refactor per BDD scenario at the right test layer, verify all scenarios, and run cross-component contract and cross-stack gates.
+
+## Goal
+
+Ensure every BDD scenario is correctly implemented at the right layer, every contract is backward-compatible, and the full stack e2e flow works — before delivery.
+
+## Flow
+
+```
+Plan + Tasks approved
+  │
+  ▼
+For each unit in DAG order (within each affected component):
+  For each BDD scenario in unit:
+    │
+    RED:   Write test at the right layer → confirm failure
+    GREEN: Write minimum implementation → confirm pass
+    REFACTOR: Clean up → confirm all tests still pass
+    │
+  ─────────────────────────────────
+  Next unit...
+  │
+  ▼
+After per-component units: regenerate shared types + contract tests
+  aidlc/tools/generate_shared.py
+  pytest aidlc/tests/contract/
+  aidlc/tools/contract_diff.py
+  │
+  ▼
+After contracts: cross-stack e2e against unified preview
+  pytest aidlc/tests/cross-stack/
+  │
+  ▼
+Gate: All layers green + contracts compatible + cross-stack pass
+```
+
+## Test Layers
+
+| Layer | When | Test Location | Run Against |
+|-------|------|---------------|-------------|
+| `unit` | Per function / module | `apps/{comp}/tests/unit/` | Local |
+| `integration` | Component + its DB / internal API | `apps/{comp}/tests/integration/` | Local container |
+| `e2e` | Whole component against preview | `apps/{comp}/tests/e2e/` | Component preview URL |
+| `cross-stack` | Full multi-client ↔ backend flow | `aidlc/tests/cross-stack/` | Unified stack preview URL |
+| `contract` | Contract shape + backward compat | `aidlc/tests/contract/` | Generated `aidlc/packages/shared/` |
+
+## TDD — Red
+
+Write one pytest test per assertion in the BDD scenario, at the layer the test plan specified.
+
+```python
+# apps/backend/tests/unit/test_auth.py
+def test_login_valid_credentials():
+    result = authenticate("user@example.com", "correct123")
+    assert result.token is not None
+    assert result.expires_in == 3600
+```
+
+```bash
+pytest apps/backend/tests/unit/test_auth.py -v
+# FAILED — authenticate() not defined  (RED ✓)
+```
+
+**Rule VRF-001:** Test must fail on first run.
+
+## TDD — Green
+
+Write the minimum code to make the test pass. No premature abstraction.
+
+```python
+# apps/backend/src/auth/login.py
+def authenticate(email, password):
+    if email == "user@example.com" and password == "correct123":
+        return AuthResult(token="jwt_token", expires_in=3600)
+    raise AuthError("Invalid credentials")
+```
+
+**Rule VRF-002:** Minimum code to pass.
+
+## TDD — Refactor
+
+```bash
+pytest --cov --cov-fail-under=80
+# All tests passed, coverage ≥80%  (REFACTOR ✓)
+```
+
+**Rule VRF-003:** Behavior must not change. All existing tests must pass before and after.
+
+## Contract Verification (INT-001, INT-002, INT-003)
+
+After per-component units pass and before cross-stack e2e:
+
+```bash
+# 1. Regenerate shared types from contracts
+aidlc/tools/generate_shared.py
+# → aidlc/packages/shared/{api,events} updated
+
+# 2. Run contract tests
+pytest aidlc/tests/contract/ --verbose
+# → All contract scenarios pass (uses packages/shared)
+
+# 3. Run contract compat check
+aidlc/tools/contract_diff.py --base main --head HEAD
+# → exit 0 = backward-compatible
+# → exit 1 = breaking change detected, BLOCKED unless human-approved
+```
+
+**Rule INT-001:** Contract tests must be 100% pass.
+
+**Rule INT-002:** Any breaking contract change (field removed, type changed, status code changed, required field added) is BLOCKED until a human approves the major version bump and a migration note is added to `aidlc/contracts/CHANGELOG.md`.
+
+**Rule INT-003:** Shared types must be generated, not hand-written. CI runs `generate_shared` and fails the build if `aidlc/packages/shared/` is out of date.
+
+## Cross-Stack E2E (STK-001)
+
+```bash
+export STACK_URL=$(deploy_stack --preview --output url)
+pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL --verbose
+# All cross-stack scenarios pass
+```
+
+**Rule STK-001:** All `cross-stack` scenarios must pass. A single failure blocks delivery.
+
+## BDD Scenario Verification (per layer)
+
+```bash
+# Per component
+pytest-bdd apps/backend/features/ --verbose
+pytest-bdd apps/web/features/ --verbose       # e.g. via cucumber-js
+pytest-bdd apps/native/features/ --verbose    # or via detox/cavy
+pytest-bdd apps/desktop/features/ --verbose    # or via spectron
+pytest-bdd apps/wxa/features/ --verbose
+pytest-bdd apps/mya/features/ --verbose
+pytest-bdd apps/tta/features/ --verbose
+
+# Cross-stack
+pytest-bdd aidlc/features/cross-stack/ --verbose
+```
+
+## Quality Gates (Backpressure)
+
+All gates enforced on every attempt to mark a unit / change complete:
+
+```bash
+# Per component
+pytest apps/{component}/ --cov --cov-fail-under=80 && \
+  pytest-bdd apps/{component}/features/ --verbose && \
+  bandit -r apps/{component}/src/ -q && \
+  ! grep -rn "TODO\|FIXME\|HACK\|XXX" apps/{component}/src/
+
+# Cross-component
+pytest aidlc/tests/contract/ && \
+  aidlc/tools/contract_diff.py --base main --head HEAD
+
+# Stack
+pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL
+```
+
+| Gate | Threshold | Rule | Scope |
+|------|-----------|------|-------|
+| Unit/integration coverage | ≥80% | VRF-005 | Per component |
+| BDD scenarios | 100% pass | VRF-004 | Per component |
+| Security | 0 vulns | VRF-005 | Per component |
+| No TODOs | 0 in src/ | VRF-005 | Per component |
+| Contract tests | 100% pass | INT-001 | Cross-component |
+| Contract compat | backward-compat | INT-002 | Cross-component |
+| Shared types | generated, in sync | INT-003 | Cross-component |
+| Cross-stack e2e | 100% pass | STK-001 | Stack |
+
+## Artifacts
+
+| Artifact | Location |
+|----------|----------|
+| TDD tests (unit/integration) | `apps/{comp}/tests/{unit,integration}/test_{feature}.py` |
+| TDD tests (e2e) | `apps/{comp}/tests/e2e/test_{feature}.py` |
+| BDD step defs (component) | `apps/{comp}/features/steps/test_{feature}_steps.py` |
+| BDD step defs (cross-stack) | `aidlc/features/cross-stack/steps/test_{feature}_steps.py` |
+| Implementation | `apps/{comp}/src/{module}/{feature}.py` |
+| Contract tests | `aidlc/tests/contract/test_{contract}.py` |
+| Cross-stack e2e | `aidlc/tests/cross-stack/test_{flow}.py` |
+| Contract diff | `aidlc/openspec/changes/{id}/contract-diff.md` (filled) |
+
+## Gate
+
+**Before advancing to Deliver phase:**
+- [ ] Per-component: All BDD scenarios pass (100%), coverage ≥80%, 0 vulns, no TODO
+- [ ] **Web E2E**: `apps/web/tests/e2e/*.spec.ts` 100% pass via Playwright
+- [ ] Contracts: `aidlc/tools/contract_diff.py` exits 0; `aidlc/tests/contract/` 100% pass; `aidlc/packages/shared/` regenerated and in sync
+- [ ] Cross-stack: `aidlc/tests/cross-stack/` 100% pass against stack preview
+- [ ] `aidlc/openspec/changes/{id}/contract-diff.md` is filled and reviewed
+- [ ] All existing tests still pass
+
+## Web E2E (Browser E2E Gate)
+
+For WEB component, execute Playwright E2E tests:
+
+```bash
+# 1. Determine port from package.json
+cat apps/web/package.json | grep -A5 '"dev"'
+
+# 2. Check test files exist
+ls apps/web/tests/e2e/*.spec.ts
+
+# 3. Execute Playwright tests
+cd apps/web
+npx playwright test --project=chromium --reporter=json
+
+# 4. Parse results
+# Exit code 0 = all passed
+# Exit code 1 = some failed
+```
+
+**Rule WEB-E2E-001:** E2E test files must exist.
+**Rule WEB-E2E-002:** All E2E tests must pass.
+**Rule WEB-E2E-003:** Base URL must be reachable.

package/ai-dlc-skill/phases/verify/prompt.md

@@ -0,0 +1,73 @@
+# Verify Phase Agent Prompt
+
+你是一个 AI-DLC Verify Phase Agent。
+由 Master Agent 委派处理测试验证。
+
+## 输入
+- `{spec_dir}/design.md` 和 `{spec_dir}/task-list.md`
+- BDD feature 文件
+
+## 路径约定
+
+所有产物路径遵循 `aidlc/CONFIG.md` 中的变量定义。关键路径：
+- 单元测试: `apps/{component}/tests/unit/test_{feature}.py`
+- 集成测试: `apps/{component}/tests/integration/test_{feature}.py`
+- E2E 测试: `apps/{component}/tests/e2e/test_{feature}.py`
+- 合约测试: `{$contract_tests_dir}/test_{contract}.py`
+- 跨栈测试: `{$crossstack_tests_dir}/test_{flow}.py`
+- Contract Diff: `{spec_dir}/contract-diff.md`
+
+## 任务
+
+1. **TDD Red-Green-Refactor**（按 DAG 顺序）
+   - 对每个 unit 的每个 BDD scenario：
+     - RED: 写 test → 确认失败
+     - GREEN: 写最小实现 → 确认通过
+     - REFACTOR: 重构清理 → 全部通过
+   - 测试按 layer 分类：unit / integration / e2e
+
+2. **Browser E2E Verification**（Web组件）
+   - 确定目标应用端口：读取 `apps/web/package.json` 的 `scripts.dev`
+   - 检查测试文件：`apps/web/tests/e2e/*.spec.ts`
+   - 执行测试：`cd apps/web && npx playwright test --project=chromium`
+   - 解析结果并报告
+
+3. **Contract Verification**
+   - 重新生成 `{shared_types_dir}/` 类型
+   - 运行 `pytest {contract_test_dir}/`
+   - 运行 `aidlc/tools/contract_diff.py`
+
+4. **Cross-Stack e2e**
+   - 对 unified preview 运行 `{cross_test_dir}/`
+
+5. **Quality Gates**
+   - coverage ≥ 80%
+   - BDD scenarios 100% pass
+   - 0 vulns, no TODO
+   - Web E2E 100% pass
+
+## 输出产物
+- `apps/{component}/tests/unit/test_{feature}.py`
+- `apps/{component}/tests/integration/test_{feature}.py`
+- `apps/{component}/tests/e2e/test_{feature}.py`
+- `apps/web/tests/e2e/*.spec.ts`（Web E2E 测试）
+- `apps/{component}/features/steps/test_{feature}_steps.py`
+- `apps/{component}/src/{module}/{feature}.py`
+- `{$contract_tests_dir}/test_{contract}.py`
+- `{$crossstack_tests_dir}/test_{flow}.py`
+- `{spec_dir}/contract-diff.md`（填充）
+
+## 约束
+- 开始前先调用 `TodoClear` 清除可能遗留的 todos，确保从空白计划开始
+- 遵守 `rules.md` 中的 VRF-001 到 VRF-006
+- 遵守 INT-001 到 INT-006
+- 遵守 STK-001 到 STK-006
+
+## 完成报告
+
+完成后返回以下信息给 Master Agent（用于写入 Registry）：
+- `phase: "verify"`
+- `status: "completed"`
+- `artifacts: [测试文件和实现文件路径列表]`
+- `gatePassed: true/false`
+- `coverage: 覆盖率百分数`

package/ai-dlc-skill/phases/verify/rules.md

@@ -0,0 +1,91 @@
+# Verify Rules (VRF-*) + Integration Rules (INT-*)
+
+## VRF-001: TDD Red Phase
+**Severity:** MUST
+**Description:** Before writing implementation, write a test that asserts expected behavior. The test MUST fail on first run.
+**Valid:** `pytest apps/backend/tests/unit/test_auth.py -k test_login` → FAILED.
+**Invalid:** Test passes on first run.
+
+## VRF-002: TDD Green Phase
+**Severity:** MUST
+**Description:** Write the minimum code needed to make the test pass. No premature abstraction.
+**Valid:** Only the code path required by the test is implemented.
+**Invalid:** Adding database, caching, or logging before the test requires it.
+
+## VRF-003: TDD Refactor Phase
+**Severity:** MUST
+**Description:** After tests pass, refactor to improve code quality while keeping ALL tests green.
+**Valid:** `pytest --cov --cov-fail-under=80` → all pass.
+**Invalid:** Behavior change during refactoring.
+
+## VRF-004: BDD Scenario Pass Gate
+**Severity:** MUST
+**Description:** ALL BDD scenarios MUST pass at every required layer before marking complete.
+**Valid:** `pytest-bdd apps/{component}/features/ --verbose` → all pass.
+**Invalid:** Any failing BDD scenario.
+
+## VRF-005: Quality Gate Backpressure
+**Severity:** MUST
+**Description:** On every unit completion, ALL gates must pass: coverage ≥80%, BDD 100%, 0 vulns, no TODO.
+**Valid:** `pytest --cov --cov-fail-under=80 && bandit -r src/ -q && ! grep -rn "TODO" src/`
+**Invalid:** Any single gate fails.
+
+## VRF-006: Test Layer Correctness
+**Severity:** MUST
+**Description:** Each BDD scenario MUST be tested at the layer the plan specified. Cross-stack ≠ unit.
+**Valid:** Cross-stack scenarios in `aidlc/tests/cross-stack/` against STACK_URL.
+**Invalid:** Cross-stack scenario implemented as mocked unit test.
+
+## INT-001: Contract as Source of Truth
+**Severity:** MUST
+**Description:** All cross-component APIs and events MUST be defined in `contracts/` (OpenAPI/AsyncAPI/GraphQL) and tagged with `INT-FR-*`.
+**Valid:** `aidlc/contracts/api/auth.yaml` defines POST /auth/login; components use generated types.
+**Invalid:** Duplicate hand-written types across components with no contract file.
+
+## INT-002: Backward-Compatibility by Default
+**Severity:** MUST
+**Description:** Contract changes MUST be backward-compatible. Breaking = field removed, type changed, status code changed, required field added. BLOCKED until human approves MAJOR bump + CHANGELOG entry.
+**Valid:** Adding a new optional field (MINOR).
+**Invalid:** Removing a field without human approval.
+
+## INT-003: Generated Shared Types
+**Severity:** MUST
+**Description:** `aidlc/packages/shared/` generated from `aidlc/contracts/`. Component code MUST import from shared.
+**Valid:** `git diff --exit-code aidlc/packages/shared/` → clean after generation.
+**Invalid:** Hand-edited files under `aidlc/packages/shared/`.
+
+## INT-004: Contract Tests at INT FR Level
+**Severity:** MUST
+**Description:** Every `INT-FR-*` MUST have contract tests in `aidlc/tests/contract/` verifying schema.
+**Valid:** Provider-agnostic contract tests using generated shared types.
+**Invalid:** Contract tests calling real production backend.
+
+## INT-005: Cross-Stack Feature Coverage
+**Severity:** MUST
+**Description:** Every `INT-FR-*` MUST have ≥3 scenarios in `aidlc/features/cross-stack/` implemented in `aidlc/tests/cross-stack/`.
+**Valid:** Cross-stack scenarios running against unified STACK_URL.
+**Invalid:** INT-FR without cross-stack feature file.
+
+## INT-006: Contract Diff Artifact
+**Severity:** MUST
+**Description:** Every contract change MUST produce `aidlc/openspec/changes/{id}/contract-diff.md`.
+**Valid:** Generated by `aidlc/tools/contract_diff.py` with added/removed/changed fields.
+**Invalid:** Contract change merged without contract-diff.md.
+
+## WEB-E2E-001: E2E Test Required
+**Severity:** MUST
+**Description:** If a WEB component exists, `apps/web/tests/e2e/` MUST contain `.spec.ts` files.
+**Valid:** `ls apps/web/tests/e2e/*.spec.ts` returns test files.
+**Invalid:** No `.spec.ts` files found when WEB component exists.
+
+## WEB-E2E-002: E2E Tests Must Pass
+**Severity:** MUST
+**Description:** All Web E2E tests MUST pass before marking verify phase complete.
+**Valid:** `npx playwright test --project=chromium` exits with code 0.
+**Invalid:** Any Playwright test fails.
+
+## WEB-E2E-003: Base URL Must Be Reachable
+**Severity:** MUST
+**Description:** The target application base URL MUST be accessible before running E2E tests.
+**Valid:** `curl -f http://localhost:{PORT}` returns HTTP 200.
+**Invalid:** Cannot connect to the application URL.