@tea-agent/loop-agent 0.19.0 → 0.20.1-beta.0

package/dist/workflows/dag/types.js

@@ -113,6 +113,36 @@ export const dagJsonArtifactGateSchema = z.object({
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
     junitRelativePath: z.string().min(1).optional(),
 });
+const dagFrontendNodeIdSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9-]*$/, "frontend node id must be kebab-case");
+export const dagFrontendPrewriteGateSchema = z.object({
+    schemaVersion: z.literal(1),
+    planFromNodeId: dagFrontendNodeIdSchema,
+    planFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
+    reviewFromNodeId: dagFrontendNodeIdSchema,
+    reviewFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
+    requiredRequirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)).default([]),
+    allowedMockStrategies: z.array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"])).min(1),
+    artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
+    outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
+    openspecCandidatePaths: z
+        .array(z.string().regex(/^openspec\/.+/, "openspec candidate must be repo-relative"))
+        .default([]),
+});
+export const dagFrontendVerificationBundleSchema = z.object({
+    schemaVersion: z.literal(1),
+    mockCommands: z.array(z.string()).default([]),
+    staticCommands: z.array(z.string()).min(1),
+    behaviorCommands: z.array(z.string()).min(1),
+    mockEvidence: dagShellVerifyEvidenceSchema.optional(),
+    staticEvidence: dagShellVerifyEvidenceSchema,
+    behaviorEvidence: dagShellVerifyEvidenceSchema,
+    mode: z.enum(["initial", "repair"]),
+});
+export const dagFrontendReviewContextSchema = z.object({
+    schemaVersion: z.literal(1),
+});
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
     .union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)])
@@ -191,6 +221,9 @@ export const dagShellConfigSchema = z.object({
     }).strict().optional(),
     requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
     jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
+    frontendPrewriteGate: dagFrontendPrewriteGateSchema.optional(),
+    frontendVerificationBundle: dagFrontendVerificationBundleSchema.optional(),
+    frontendReviewContext: dagFrontendReviewContextSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),

package/dist/workflows/dag/validate.js

@@ -456,7 +456,12 @@ function validateShellTaskConfig(task, spec, issues) {
         return;
     }
     const commands = resolveShellCommands(shell);
-    if (commands.length === 0 && !shell.jsonArtifactGate && !shell.backendTestPipeline) {
+    if (commands.length === 0 &&
+        !shell.jsonArtifactGate &&
+        !shell.backendTestPipeline &&
+        !shell.frontendPrewriteGate &&
+        !shell.frontendVerificationBundle &&
+        !shell.frontendReviewContext) {
         issues.push({
             type: "missing-shell-commands",
             message: `shell task ${task.id} requires shell.preset, shell.verdictGate, shell.jsonArtifactGate, shell.backendTestPipeline, and/or non-empty shell.commands`,
@@ -517,6 +522,22 @@ function validateShellTaskConfig(task, spec, issues) {
             }
         }
     }
+    if (shell.frontendPrewriteGate) {
+        const sourceNodeIds = [
+            shell.frontendPrewriteGate.planFromNodeId,
+            ...shell.frontendPrewriteGate.planFallbackFromNodeIds,
+            shell.frontendPrewriteGate.reviewFromNodeId,
+            ...shell.frontendPrewriteGate.reviewFallbackFromNodeIds,
+        ];
+        for (const sourceNodeId of new Set(sourceNodeIds)) {
+            if (!task.depends_on.includes(sourceNodeId)) {
+                issues.push({
+                    type: "missing-dependency",
+                    message: `shell task ${task.id} frontendPrewriteGate source ${sourceNodeId} must be a direct dependency`,
+                });
+            }
+        }
+    }
     validateRepairArtifactGateConfig(task, spec, issues);
     validateShellVerdictGateGovernance(task, commands, issues);
 }

package/docs/README.md

@@ -75,6 +75,7 @@
 
 完整 completed 列表与主题速览见 `exec-plans/completed/README.md`。近期高频归档：
 
+- `exec-plans/completed/2026-07-23-backend-test-human-readable-artifacts.md` — 中文 README/用例卡片、class-based pytest traceability 与逐条 self-contained HTML 报告；真实 `my-webapp` Campaign Round 04 8/8、16 passed
 - `exec-plans/completed/2026-07-22-backend-markdown-gate-fix.md` — backend-test Markdown gate、traceability、中文生成与真实 Campaign 收口
 - `exec-plans/completed/2026-07-22-backend-test-markdown-first-8-node.md` — backend-test Markdown-first 8 节点
 - `exec-plans/completed/2026-07-22-backend-test-report-first-flow.md` — backend-test 报告优先 12 节点

package/docs/templates/agent-dag.schema.json

@@ -303,6 +303,43 @@
             "junitRelativePath": { "type": "string", "minLength": 1 }
           }
         },
+        "frontendPrewriteGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion", "planFromNodeId", "reviewFromNodeId", "allowedMockStrategies", "artifactName", "outputDir"],
+          "properties": {
+            "schemaVersion": { "const": 1 },
+            "planFromNodeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "planFallbackFromNodeIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" } },
+            "reviewFromNodeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "reviewFallbackFromNodeIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" } },
+            "requiredRequirementIds": { "type": "array", "items": { "type": "string", "pattern": "^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$" } },
+            "allowedMockStrategies": { "type": "array", "minItems": 1, "items": { "enum": ["native", "browser-intercept", "request-adapter", "not-needed"] } },
+            "artifactName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.json$" },
+            "outputDir": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" }
+          }
+        },
+        "frontendVerificationBundle": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion", "staticCommands", "behaviorCommands", "staticEvidence", "behaviorEvidence", "mode"],
+          "properties": {
+            "schemaVersion": { "const": 1 },
+            "mockCommands": { "type": "array", "items": { "type": "string" } },
+            "staticCommands": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+            "behaviorCommands": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+            "mockEvidence": { "$ref": "#/$defs/shellVerifyEvidence" },
+            "staticEvidence": { "$ref": "#/$defs/shellVerifyEvidence" },
+            "behaviorEvidence": { "$ref": "#/$defs/shellVerifyEvidence" },
+            "mode": { "enum": ["initial", "repair"] }
+          }
+        },
+        "frontendReviewContext": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion"],
+          "properties": { "schemaVersion": { "const": 1 } }
+        },
         "backendTestPipeline": {
           "enum": ["contracts", "semantic-initial", "execute-parse-initial", "classification-result-context"]
         },
@@ -324,6 +361,9 @@
         { "required": ["verdictGate"] },
         { "required": ["requirementCoverageGate"] },
         { "required": ["jsonArtifactGate"] },
+        { "required": ["frontendPrewriteGate"] },
+        { "required": ["frontendVerificationBundle"] },
+        { "required": ["frontendReviewContext"] },
         { "required": ["backendTestPipeline"] }
       ]
     },

package/docs/templates/backend-test-dag.generate-pytest.prompt.md

@@ -2,205 +2,36 @@
 
 ## Purpose
 
-Use this prompt for a **pytest code generation** node: `executor: "pi"`, `role: "implementer"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The implementer converts validated backend functional test cases into pytest automation code with 1:1 traceability. The independent case review is advisory evidence and does not authorize this writer.
+供 `generate-backend-pytest-pi` 使用。该节点是 `executor: "pi"`、`role: "implementer"`、`toolProfile: "write"` 的受限 writer，只把已经通过 Markdown gate 的最终用例转换为 pytest 资产。
 
-Do **not** create a new executor type. This is a standard `executor: pi` writer node.
+## 当前合同
 
-## Recommended DAG Node Shape
-
-```json
-{
-  "id": "generate-backend-pytest-pi",
-  "depends_on": ["backend-test-case-manifest-shell", "validate-backend-test-contracts-shell"],
-  "complexity": "HIGH",
-  "executor": "pi",
-  "role": "implementer",
-  "toolProfile": "write",
-  "writePolicy": "exclusive",
-  "writeSet": ["testcase/**/test_*.py", "testcase/**/helpers/**", "testcase/**/factories/**"],
-  "allowedPaths": ["**"],
-  "forbiddenPaths": [".harness/**", "artifacts/**"],
-  "outputContract": "Pytest test files under testcase/ with 1:1 mapping to functional test case IDs; optional helpers/factories. Summary lists generated files, test function count, and any skipped cases with reasons.",
-  "subtask_prompt_markdown": "./backend-test-dag.generate-pytest.prompt.md"
-}
-```
-
-## Prompt Body
-
-You are the Backend Test DAG **pytest code generator**.
-
-Your job is to convert reviewed test cases under `testcase/md/` into pytest automation code. Write test files under `testcase/` only. Stay within `writeSet`. Do not write root `artifacts/**`.
-
-### Output Steps (do in order)
-
-1. First, output a brief summary: how many files, how many test functions planned
-2. Then write each test file under `testcase/`
-
-### Inputs
-
-1. **Validated test cases and manifest** — files under `testcase/md/` plus run-owned `contracts/backend-test-case-manifest.json`. The case review runs independently as advisory evidence.
-2. **Validated Backend Test Analysis v2** — run-owned `contracts/backend-test-analysis.json`.
-3. **Validated Backend Test Execution Contract v1** — run-owned `contracts/backend-test-execution.json` from `backend-test-execution-contract-shell` (fixtures, env *names*, `testRoot`, `targetMode`, authenticationMode).
-4. **Target project conventions** — read `conftest.py`, `pytest.ini` / `pyproject.toml` to understand conventions, but do NOT modify them.
-
-Do NOT re-read source documents for free-form analysis. Use only validated cases, manifest, and contracts. Use only fixture/env/testRoot facts already present in the execution contract; never invent production credentials or secret values.
-
-When `targetMode` is `in-process` (including demoted local npm/node managed servers): bootstrap the service inside function-scoped pytest fixtures under `testcase/**` (for example subprocess `node server.js` / `startWelcomeServer` with `PORT=0`). Never require host-injected base URL env vars such as `WELCOME_BASE_URL` / `API_BASE_URL` — the clean-env pytest shell will not provide them.
-
-### Conversion Rules
-
-#### File Naming
-
-- Every test file must start with `test_` prefix (e.g. `test_order.py`, `test_user_api.py`)
-- pytest collects tests from files matching `test_*.py` or `*_test.py` — use `test_` prefix exclusively
-- Never create test files without the `test_` prefix
-
-#### Write Boundary
-
-- Only **create new** files under writeSet:
-  - `testcase/**/test_*.py`
-  - `testcase/**/helpers/**` (optional pure helpers)
-  - `testcase/**/factories/**` (optional test data factories)
-- Do NOT modify existing files: `conftest.py`, `pytest.ini`, `pyproject.toml`, `setup.cfg`, `__init__.py`, or any other framework/config file
-- Reuse existing fixtures; if required helpers are missing, create NEW helper/factory modules under the writeSet paths above — never edit root conftest
-- Read existing framework files to understand conventions, but treat them as immutable
-- Do NOT write production code, `.env`, secrets, or credential files
-
-#### Naming Conflict Resolution
-
-- If a file with the target name already exists under `testcase/`, add a numeric suffix: `test_order.py` → `test_order_01.py` → `test_order_02.py`
-- Never overwrite or append to existing files — each test script must be a standalone file
-- Check for existing files before writing; if `test_<module>.py` exists, use `test_<module>_01.py`
-
-#### 1:1 Traceability
-
-Every functional test case ID (`BE-<MODULE>-<NNN>`) must map to exactly one pytest function:
+- 输入：最终 `testcase/md/**`、run-owned 环境报告与 Markdown 校验报告，以及有界的 pytest config / `conftest.py`。
+- 禁止重新读取 `source/**`、新增测试场景、重新分配 AC、执行 pytest、修改生产代码/配置或输出业务 JSON。
+- 写入范围：`testcase/**/test_*.py`、`testcase/**/helpers/**`、`testcase/**/factories/**`。
+- pytest 可以使用模块级 `test_*` 函数，也可以使用 pytest 测试类中的 `test_*` 方法；不得为了追溯强迫目标项目放弃现有 class-based 风格。
+- 每个最终 Markdown Case ID 必须出现在至少一个真实测试函数/方法区域中，优先同时出现在函数/方法名和 docstring：
 
 ```python
-# testcase/md/BE-ORDER-001 → testcase/test_order.py
-def test_BE_ORDER_001_create_order_with_valid_data():
-    """BE-ORDER-001: Create order with valid request body."""
-    ...
+class TestOrderApi:
+    def test_BE_ORDER_001_create_order(self) -> None:
+        """BE-ORDER-001 创建合法订单。"""
+        ...
 ```
 
-- Function name: `test_<CASE_ID_with_underscores>` (e.g. `test_BE_ORDER_001_...`)
-- Docstring first line: `<CASE_ID>: <Case Title>`
-
-#### File Organization
-
-- All test files go under `testcase/` directory in the host project root
-- Group test files by MODULE segment: `BE-ORDER-*` → `testcase/test_order.py`, `BE-USER-*` → `testcase/test_user.py`
-- Follow existing project conventions for import style, fixture scope
-
-#### Fixture Strategy
-
-- Reuse existing project fixtures from `conftest.py` when available (read-only)
-- Do not create or modify root fixture/configuration files (`conftest.py`, pytest.ini, …)
-- Optional NEW helpers/factories may live under `testcase/**/helpers/**` or `testcase/**/factories/**` only
-- Prefer `@pytest.fixture(scope="function")` for test isolation
-- Use `@pytest.mark.parametrize` for boundary condition cases with multiple inputs
-
-#### Test Integrity
-
-- Tests verify implementation correctness — if a test fails, the implementation likely has a bug, not the test
-- Do NOT weaken assertions, remove test cases, or modify test logic to make tests pass
-- Do NOT add workarounds, skips, or try/except blocks to hide failures without explicit justification
-- Report all failures honestly in the output; the downstream `execute-backend-pytest-shell` node captures exit codes and stdout/stderr as-is
-
-#### Test Data Preparation Rules (MUST follow)
-
-**When Setup is Needed**
-
-Setup phase is REQUIRED only when test cases need pre-existing data:
-- Query/Read APIs: need data to exist before querying
-- Update/Delete APIs: need data to exist before modifying
-- State transition tests: need data in specific state
-
-Setup phase is NOT needed for:
-- Create APIs: testing the creation itself
-- Validation tests: testing input validation with invalid data
-
-**Data Setup Strategy**
-
-When setup is needed:
-1. Use `@pytest.fixture(scope='module')` or `@pytest.fixture(scope='session')` to prepare shared test data
-2. All test cases in the file share the same pre-constructed data
-
-**Data Construction Priority**
-
-1. **API-first**: Use documented APIs from `analyze-inputs-pi` / reviewed cases
-2. **Reuse existing conftest fixtures** (read-only)
-3. **Direct DB writes are last resort** and only via safe test-DB fixtures with rollback/isolation
-4. If neither API nor safe DB fixture exists, **skip with an explicit gap note** — do not invent credentials or touch live data
-
-**API Data Construction**
-
-- Prefer the `analyze-inputs-pi` API Endpoints section and reviewed cases for method/path/fields
-- Chain API calls only when cases document multi-step preconditions
-- Store created resource IDs in fixtures for reuse
-- Do **not** broadly search host route/controller trees for secrets, `.env`, private keys, or production configs
-- Read host API definitions only when needed to resolve a field name already referenced by reviewed cases
-
-**Database Data Construction (restricted)**
-
-- Allowed only via existing `conftest.py` test-DB fixtures with transaction rollback or equivalent isolation
-- Never hardcode connection strings, passwords, tokens, or cloud credentials
-- Never target production/shared non-test databases
-- If isolation is unclear, report the gap instead of writing DB rows
-
-#### Assertion Rules (MUST follow)
-
-**Positive Path (成功场景)**
-
-MUST assert ALL of the following:
-1. HTTP status code: as defined in API spec (e.g. 200, 201)
-2. Response structure: key fields exist in response body
-3. Specific values: each field equals expected value from test case
-4. Data type: each field is correct type
-
-**Negative Path (异常场景)**
-
-MUST assert ALL of the following:
-1. HTTP status code: as defined in API spec (e.g. 400, 404, 500)
-2. Error code field: field name from API spec (e.g. code, error_code, errcode, ret)
-3. Error message field: field name from API spec (e.g. message, msg, errmsg, error)
-
-**Field Name Resolution**
-
-Field names MUST come from the upstream `analyze-inputs-pi` output (API Endpoints section), NOT hardcoded. For example:
-- If API spec defines `{"ret": 0, "msg": "success"}`, assert `response.json()["ret"]` and `response.json()["msg"]`
-- If API spec defines `{"code": 4001, "message": "error"}`, assert `response.json()["code"]` and `response.json()["message"]`
-
-
-#### Conditional Test Implementation (include ONLY if test cases exist)
-
-- **Authentication tests**: implement ONLY if `testcase/md/` contains auth-related cases
-  - Use `@pytest.mark.auth` marker
-  - Test no token, expired token, invalid token, insufficient permissions, cross-user access
-- **Timeout tests**: implement ONLY if `testcase/md/` contains timeout-related cases
-  - Use `@pytest.mark.timeout` marker
-  - Use `unittest.mock.patch` or `pytest-mock` to simulate slow responses
-- If no such cases exist in the reviewed test cases, do NOT add these tests
-
-#### Markers
-
-- `@pytest.mark.positive` — happy path cases
-- `@pytest.mark.negative` — error/exception cases
-- `@pytest.mark.boundary` — edge cases
-- `@pytest.mark.<MODULE>` — module-specific marker (e.g. `@pytest.mark.order`)
-
-#### Skip Policy
-
-If a test case cannot be automated (requires external service not mockable, requires manual verification), add it with `@pytest.mark.skip(reason="...")` and document the reason. Do not omit the function — traceability requires it exists.
+- 断言只来自 `### 预期结果` / `### Expected Results`；setup 只来自 `### 前置条件`、`### 测试数据`、`### 自动化映射` 或对应历史英文分节。
+- 禁止 `skip` / `xfail`、吞断言、宽异常静默通过、mock 替代真实目标、删除用例或弱化断言。
+- best-effort 清理只能捕获所选 HTTP client 实际抛出的窄 transport exception，例如 `requests.RequestException` 或 `urllib.error.URLError`；禁止 `except:`、`except Exception`、`except BaseException` 后 `pass`。
+- 同一 Case ID 可以由多个 pytest 函数覆盖；额外映射会进入 traceability 报告，但不能伪造未在 Markdown 中定义的业务场景。
+- 测试失败必须诚实保留，后续节点只执行一次 pytest，并从同一 JUnit 生成 HTML/facts。
 
-### Output Shape (after summary line)
+## 推荐输出
 
-After the mandatory summary line, provide:
+写入文件后，用简短中文总结：
 
-1. **Generated Files** — list of files written under `tests/backend/`.
-2. **Function Mapping Table** — `| Test Case ID | Pytest Function | File | Marker |`.
-3. **Skipped Cases** — if any, list with reason.
-4. **Conventions Observed** — note project fixtures/config discovered and followed.
-5. **Residual Risks** — cases that may need manual verification or environment setup.
+1. 生成或更新了哪些测试文件；
+2. Case ID → 脚本 → pytest 函数/方法映射；
+3. 复用的 fixture/config；
+4. 仍存在的环境或自动化缺口。
 
-Do not include chain-of-thought. Do not write root `artifacts/**`.
+不得输出 chain-of-thought，不得执行 pytest。

package/docs/templates/backend-test-dag.json

@@ -68,8 +68,8 @@
   "executorModels": {
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
-      "HIGH": "gpt-5.5"
+      "MED": "grok-4.5",
+      "HIGH": "gpt-5.6-sol"
     }
   },
   "tasks": [
@@ -124,8 +124,8 @@
         ".harness/dag-runs/**",
         "artifacts/**"
       ],
-      "outputContract": "Write testcase/md/README.md plus module Markdown cases using BE-<MODULE>-<NNN>. Use Chinese for human-readable content while preserving required machine-readable identifiers and section headings; no JSON, pytest execution, production code or config writes.",
-      "subtask_prompt": "Read the upstream environment report. Generate a Markdown-first backend test strategy and cases under testcase/md/**.\n\nWrite human-readable content in Simplified Chinese by default: document titles, case titles, strategy explanations, preconditions, test-data descriptions, step descriptions, expected-result descriptions, automation notes, table headers and evidence-gap explanations. Keep English only where it is part of a machine-readable contract or established technical literal, including Case IDs, AC/REQ/BR IDs, exact section headings, HTTP methods, paths, field names, enum values, commands, filenames, code symbols and source citations. Do not add an English translation when Chinese already conveys the meaning.\n\nEvery case heading is `## BE-<MODULE>-<NNN> <中文用例标题>` and contains these exact machine-readable headings: `### Acceptance Criteria`, `### Source References`, `### Preconditions`, `### Test Data`, `### Steps`, `### Expected Results`, and `### Automation Notes`. API cases also contain `### Endpoint` with Method and Path. Under those headings, write descriptions in Chinese while preserving exact IDs, values and protocol literals.\n\nCreate testcase/md/README.md in Chinese. It should concisely explain the test objective, environment/target, isolation and cleanup strategy, module index, traceability summary, assertion principles, evidence gaps and non-goals. Prefer readable Chinese tables and lists over repeated boilerplate.\n\nExpected Results must be concrete, independently assertable Chinese statements. Each result should name the observable HTTP status, response field/value, state transition or membership condition instead of vague phrases such as ‘works correctly’ or ‘符合预期’. Steps must be executable and ordered. Use only environment-supported fixtures/targets/isolation. Record evidence gaps in Chinese instead of inventing behavior or credentials. Do not emit JSON, pytest, or execute commands.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and copy `path` exactly into Markdown Source References. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.\n\nRead only precise indexed references needed for AC/API/field/rule evidence; references remain authoritative over derived text."
+      "outputContract": "Write a Chinese, human-readable testcase/md/README.md plus module Markdown case cards using BE-<MODULE>-<NNN>; keep machine IDs/literals exact and do not execute pytest or modify production code/config.",
+      "subtask_prompt": "Read the upstream environment report. Generate a Markdown-first backend test strategy and cases under testcase/md/**.\n\nWrite human-readable content in Simplified Chinese by default. Keep English only for machine-readable IDs and technical literals such as Case/AC/REQ/BR IDs, HTTP methods, paths, field names, enum values, commands, filenames, code symbols and exact source citations.\n\nCreate testcase/md/README.md as the concise entry page: test objective, target/environment, isolation/cleanup, module summary and a linked case index table with Case ID, Chinese case name, scenario type, endpoint and expected status/result. Avoid repeating every case body in README.\n\nWrite each module as readable case cards. Every case starts with `## BE-<MODULE>-<NNN>｜<中文用例名称>` and uses these Chinese headings: `### 测试目的`, `### 验收标准`, `### 需求依据`, `### 前置条件`, optional `### 测试数据`, `### 操作步骤`, `### 预期结果`, and `### 自动化映射`. API metadata may use a compact table under the case heading. The deterministic validator also accepts legacy English headings, but new output should use this Chinese presentation.\n\nPlace steps and their expected results in a compact readable table when that improves clarity; otherwise keep numbered executable steps and numbered/bulleted independently assertable results. Every result must name the observable HTTP status, response field/value, state transition or membership condition, never vague wording such as ‘符合预期’.\n\nIn `自动化映射`, record the planned script path and pytest function name when known. Put implementation-only restrictions in a concise `<details>` block rather than dominating the main case flow. Use only environment-supported fixtures/targets/isolation, record evidence gaps in Chinese, and do not emit JSON, pytest, or execute commands.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and copy `path` exactly into Markdown Source References. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.\n\nRead only precise indexed references needed for AC/API/field/rule evidence; references remain authoritative over derived text."
     },
     {
       "id": "review-and-revise-backend-md-cases-pi",
@@ -149,7 +149,7 @@
         "artifacts/**"
       ],
       "outputContract": "Review source fidelity and directly revise only testcase/md/**; return concise Markdown, never JSON.",
-      "subtask_prompt": "Independently review generated Markdown cases against each case Source References and environment evidence. Preserve and improve the Simplified Chinese presentation: human-readable titles, prose, table headers, steps, expected results and notes should be Chinese unless the token is a machine-readable ID, exact required heading, HTTP/API literal, field/enum value, path, filename, command or code symbol.\n\nCheck AC completeness/meaning, endpoint, fields/shape, status/error codes, rules, states, documented boundaries/auth, positive/negative coverage, executable steps and assertable results. Also reject avoidable English prose, duplicated bilingual wording, vague Chinese results such as ‘符合预期’, and literal translations that obscure the observable assertion.\n\nCorrect testcase/md/** directly: add documented omissions, remove unsupported cases, fix mappings/expectations, merge duplicates, improve unclear Chinese wording, or record gaps in Chinese. Do not translate or alter Case IDs, AC/REQ/BR IDs, exact required section headings, HTTP methods, paths, field names, enum values, filenames, code symbols or Source References. Avoid cosmetic rewrites that do not improve correctness or readability.\n\nRead only precise referenced source paths plus requirement sections needed for uncovered ACs. Do not scan the repository, modify source/**, generate pytest, execute tests, or emit JSON.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and keep `path` as the exact Markdown Source References citation. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails."
+      "subtask_prompt": "Independently review generated Markdown cases against each case 需求依据 and environment evidence. Treat the files as human-facing test documentation: require a clear Chinese name and scenario/purpose, compact metadata, readable steps/results, and a concise automation mapping while preserving exact machine IDs and technical literals.\n\nCheck AC completeness/meaning, endpoint, fields/shape, status/error codes, rules, states, documented boundaries/auth, positive/negative coverage, executable steps and assertable results. Reject avoidable English prose, duplicated bilingual wording, repeated boilerplate, oversized unstructured sections, vague results such as ‘符合预期’, and missing script/function mapping where it can be derived.\n\nCorrect testcase/md/** directly: add documented omissions, remove unsupported cases, fix mappings/expectations, merge duplicates, improve navigation/tables/Chinese wording, or record gaps in Chinese. Keep Case IDs, AC/REQ/BR IDs, HTTP methods, paths, fields, enum values, filenames, code symbols and source citations exact. The validator accepts Chinese and legacy English section aliases; retain or converge to the Chinese human-readable headings without losing structure.\n\nRead only precise referenced source paths plus requirement sections needed for uncovered ACs. Do not scan the repository, modify source/**, generate pytest, execute tests, or emit JSON.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and keep `path` as the exact Markdown Source References citation. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails."
     },
     {
       "id": "validate-backend-md-cases-shell",
@@ -203,7 +203,7 @@
         "artifacts/**"
       ],
       "outputContract": "Convert every final automatable Markdown case into pytest assets whose actual test function region contains the exact Case ID, preferably in the function name or docstring; no JSON and no pytest execution.",
-      "subtask_prompt": "Convert validated testcase/md/** to pytest using upstream environment and validation evidence plus only bounded pytest config/conftest.\n\nEnsure every final Markdown Case ID appears in at least one real top-level test_* function region, preferably as `test_BE_<MODULE>_<NNN>_<description>` or in that function's docstring. Multiple test functions may cover one Case ID; assertions come only from Expected Results and setup comes only from Preconditions/Test Data/Automation Notes.\n\nDo not read source/**, add cases, reassign ACs, modify conftest/config/production code, use skip/xfail, swallow assertions, execute pytest, or emit JSON."
+      "subtask_prompt": "Convert validated testcase/md/** to pytest using upstream environment and validation evidence plus only bounded pytest config/conftest.\n\nEnsure every final Markdown Case ID appears in at least one real pytest test function or pytest test class method region, preferably as `test_BE_<MODULE>_<NNN>_<description>` and in that function/method docstring. Module-level functions and class-based pytest methods are both supported. Multiple test functions may cover one Case ID; assertions come only from 预期结果/Expected Results and setup comes only from 前置条件/测试数据/自动化映射 or their legacy English aliases.\n\nDo not read source/**, add cases, reassign ACs, modify conftest/config/production code, use skip/xfail, swallow assertions, execute pytest, or emit JSON. For best-effort cleanup, catch only the narrow transport exception actually raised by the selected HTTP client (for example `requests.RequestException` or `urllib.error.URLError`); never use bare `except`, `Exception`, or `BaseException` with `pass`."
     },
     {
       "id": "backend-test-traceability-gate-shell",
@@ -224,7 +224,7 @@
         "artifacts/**"
       ],
       "outputContract": "Run-owned reports/backend-test-traceability.md proving every real Markdown Case ID is covered by at least one pytest test function.",
-      "subtask_prompt": "Fail closed only when a real Markdown case heading has no associated top-level pytest test function. Accept exact Case IDs in the function name or its decorator/body/docstring region; report multiple mappings and extra automation Case IDs without blocking. Continue to reject skip/xfail or swallowed exceptions.",
+      "subtask_prompt": "Fail closed only when a real Markdown case heading has no associated pytest test function or class method. Accept exact Case IDs in the function/method name or its decorator/body/docstring region; report multiple mappings and extra automation Case IDs without blocking. Continue to reject skip/xfail or swallowed exceptions.",
       "shell": {
         "commands": [],
         "backendTestPipeline": "markdown-traceability",
@@ -251,7 +251,7 @@
         "artifacts/**"
       ],
       "outputContract": "One pytest execution producing valid JUnit, self-contained HTML and reports/backend-test-facts.md; exit 0/1 with valid evidence continues.",
-      "subtask_prompt": "Execute pytest exactly once. Validate JUnit, render self-contained HTML from that JUnit without rerun, and preserve failures as facts.",
+      "subtask_prompt": "Execute pytest exactly once. Validate JUnit, render the primary self-contained Chinese HTML report from the same JUnit plus final Markdown case metadata without rerun, list every case with name/scenario/script/function/result/duration, and preserve failure summaries plus expandable technical details as facts.",
       "shell": {
         "commands": [
           "mkdir -p \"${HARNESS_DAG_RUN_DIR}/reports\"; PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 python -m pytest testcase/ -v -p no:cacheprovider --junitxml=\"${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml\"; STATUS=$?; printf \"%s\" \"${STATUS}\" > \"${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt\"; if { [ \"${STATUS}\" -eq 0 ] || [ \"${STATUS}\" -eq 1 ]; } && [ -s \"${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml\" ]; then exit 0; fi; exit \"${STATUS}\""

package/docs/templates/backend-test-dag.review-cases.prompt.md

@@ -2,88 +2,35 @@
 
 ## Purpose
 
-Use this prompt for the single read-only **backend test case review** node: `executor: "pi"`, `role: "reviewer"`, `writePolicy: "read-only"`. The reviewer audits generated backend functional test cases for completeness, format compliance, and traceability to source requirements. The verdict is advisory evidence consumed by canonical context, retrospective, and L-5; it neither authorizes nor blocks the pytest writer.
+供 `review-and-revise-backend-md-cases-pi` 使用。该节点是 `executor: "pi"`、`role: "reviewer"`、`toolProfile: "write"` 的受限 reviewer，只能直接修订 `testcase/md/**`，不得生成 pytest 或修改任务源、生产代码和配置。
 
-Do **not** create `executor: reviewer`. Reviewer is a **role** on `executor: pi`.
+## 当前合同
 
-## Recommended DAG Node Shape
+把 Markdown 用例视为面向测试、研发、产品与评审人员的正式文档，而不是模型中间产物。
 
-```json
-{
-  "id": "review-backend-cases-pi",
-  "depends_on": ["backend-test-case-manifest-shell", "backend-test-analysis-contract-shell"],
-  "complexity": "HIGH",
-  "executor": "pi",
-  "role": "reviewer",
-  "writePolicy": "read-only",
-  "allowedPaths": ["**"],
-  "forbiddenPaths": [".harness/**", "artifacts/**"],
-  "outputContract": "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision; followed by Findings and Coverage Assessment. No file writes.",
-  "subtask_prompt_markdown": "./backend-test-dag.review-cases.prompt.md"
-}
-```
+### 阅读体验
 
-## Prompt Body
+- `testcase/md/README.md` 是简洁入口，包含测试目标、环境、隔离/清理策略、模块汇总和可跳转的用例索引。
+- 模块文件采用中文用例卡片；每条以 `## BE-<MODULE>-<NNN>｜<中文用例名称>` 开始。
+- 新文档优先使用：`测试目的`、`验收标准`、`需求依据`、`前置条件`、`测试数据`、`操作步骤`、`预期结果`、`自动化映射`。
+- validator 同时接受上述中文分节和历史英文分节；机器 ID、HTTP 方法、路径、字段、枚举、文件名、函数名与 source citation 必须保持精确。
+- 步骤和预期可以用紧凑表格，也可以分别使用编号/项目列表；必须可执行、可独立断言。
+- 自动化内部限制应简短或放进 `<details>`，不能淹没人类主要阅读路径。
 
-You are the Backend Test DAG **test case reviewer** (read-only).
+### 正确性
 
-Your job is to audit the generated backend functional test cases for completeness, format compliance, requirement coverage, and traceability. You are **not** an implementer or test generator. Do not edit repository files, including root `artifacts/**`.
+- 对照每条 `需求依据` 和环境报告检查 AC、接口、字段/响应形状、状态码、错误语义、状态转换、正向/异常/边界场景。
+- 删除无依据场景、合并重复用例、补齐有依据的遗漏；无法确认的内容写入中文证据缺口，不猜测行为或凭据。
+- 拒绝“符合预期”“正常工作”等模糊结果，以及无意义的中英双写和大段重复 boilerplate。
+- 若能确定脚本与函数命名，在 `自动化映射` 中写明计划脚本路径与 pytest 函数/方法名。
 
-### Mandatory First Line
+## 推荐输出
 
-The **first non-empty line** of your response must be exactly one of:
+完成文件修订后，仅用简短中文说明：
 
-- `VERDICT: pass`
-- `VERDICT: request-revision`
+- 修订了哪些文档；
+- 用例数与主要模块；
+- 修复了哪些需求一致性或阅读问题；
+- 仍有哪些证据缺口。
 
-No preamble, heading, or blank lines before the verdict line.
-
-### Inputs to Review
-
-1. **Acceptance criteria / analysis** — from the validated Backend Test Analysis v1 artifact materialized by `backend-test-analysis-contract-shell` (`contracts/backend-test-analysis.json` under the current DAG run). Do not treat free-form Markdown from `analyze-inputs-pi` as the contract.
-2. **Case Manifest v1** — `contracts/backend-test-case-manifest.json` (schemaId `backend-test-case-manifest-v1`). Prefer `coverageSummary` and caseId↔acIds from this artifact; do not invent coverage percentages.
-3. **Generated test cases** — files under `testcase/md/`.
-
-Do NOT re-read source documents. Use the validated analysis artifact, case manifest, and generated cases only.
-
-### Review Checklist
-
-| Area | Check | Severity if Missing |
-|------|-------|---------------------|
-| **ID format** | Every test case ID matches `BE-<MODULE>-<NNN>` (e.g. `BE-ORDER-001`) | Critical |
-| **Positive path coverage** | Happy-path scenarios for each acceptance criterion | Critical |
-| **Negative path coverage** | Error/exception scenarios (invalid input, not found, state violations) | Important |
-| **Boundary conditions** | Edge cases (empty input, max length, edge values) | Important |
-| **State transitions** | Illegal state changes covered | Important |
-| **Requirement traceability** | Each acceptance criterion (AC-xxx) maps to at least one test case ID (manifest coverageSummary or evidenceGaps) | Critical |
-| **Manifest consistency** | Markdown case bodies **and** any AC matrix list the **same full** `BE-*` ids as Case Manifest v1 `caseId`→`acIds`. Never claim "all cases" / "全部用例" cover an AC unless every case maps that AC. | Critical |
-| **Planned automation** | Missing `test_*.py` before generate-pytest is **Informational only**, not Critical | Informational |
-| **Out-of-scope ACs** | Flyway / frontend e2e / `mvn test` etc. already in manifest `evidenceGaps` must not be treated as uncovered Critical | Informational |
-| **Case structure** | Each case has: ID, Title, Precondition, Steps, Expected Result | Important |
-| **No duplicate IDs** | All test case IDs are unique across files | Critical |
-
-### Conditional Coverage (check ONLY if mentioned in upstream analysis)
-
-- **Authentication coverage**: check ONLY if the validated analysis artifact mentions auth mechanism (JWT, OAuth2, API Key, etc.)
-- **Timeout coverage**: check ONLY if the validated analysis artifact mentions timeout handling or degradation strategy
-- If not mentioned in the validated analysis artifact, do NOT flag as missing
-
-### Verdict Rules
-
-| Condition | Verdict |
-|-----------|---------|
-| All Critical checks pass, Important checks have no more than 2 findings | `VERDICT: pass` |
-| Any Critical check fails | `VERDICT: request-revision` |
-| More than 2 Important findings | `VERDICT: request-revision` |
-| Only Informational findings | `VERDICT: pass` (with findings listed) |
-
-### Output Shape (after verdict line)
-
-1. **Coverage Assessment** — table mapping each AC to covering **full** test case IDs (or "uncovered" / gap).
-2. **Findings** — bullet list tagged `Critical`, `Important`, or `Informational`.
-3. **Statistics** — total case count, positive/negative/boundary breakdown, module distribution.
-4. **Required follow-up** (only when `request-revision`) — numbered, concrete MD corrections for a separate follow-up task. These findings do not authorize edits in the current run.
-
-### Fail-fast note
-
-There is no final review or in-run revision writer. Any `request-revision` verdict remains auditable advisory evidence and must be reported downstream; it does not stop pytest generation.
+不得输出 JSON，不得执行测试。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.19.0",
+  "version": "0.20.1-beta.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-design-review/SKILL.md

@@ -10,9 +10,11 @@ references:
 # Frontend Design Review
 
 For frontend design review nodes. Read the checklist; audit contract, scout, Mock
-strategy, effective plan, task bounds, and traceable design evidence. The knowledge-
-base connector is TODO: never invent results. If unavailable or unmatched, require
-`<repoRoot>/openspec/**` search/read evidence before repository conventions.
+strategy, effective plan, task bounds, and traceable design evidence.
+Knowledge base and `openspec/` are parallel specification sources. Query the
+knowledge-base connector when available; regardless of result, also search and
+read `<repoRoot>/openspec/**` before accepting repository conventions. The
+connector format is TODO: never invent results.
 
 ## Verdict Contract
 

package/skills/frontend-design-review/references/review-checklist.md

@@ -9,8 +9,9 @@
 ## Project Fit
 
 - Reuse components, hooks, API helpers, mocks, schemas, router patterns, tokens, and theme rules.
-- Cite knowledge-base or `openspec/`; failed/empty knowledge queries must search `<repoRoot>/openspec/**`.
-- Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths.
+- Cite knowledge base and `openspec/` as parallel sources; failed or empty
+  knowledge queries must still search `<repoRoot>/openspec/**`.
+- Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths for both.
 
 ## Interaction / Quality