@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0

package/docs/templates/frontend-eval/fixtures/failures/07-mock-production-on.md

@@ -0,0 +1,21 @@
+# Failure fixture: Mock production-on / real-request commented out
+
+- **fixtureId**: `fe-fail-mock-production-on`
+- **triggerSignal**: 生产入口默认启用 Mock、注释真实请求、或 production import test mocks
+- **expectedGateBehavior**: design/review 至少 Important → request-revision；static production/default-real-path 检查应失败或 review 阻断
+- **repairable (M3 预标注)**: `repairable` 若仅激活边界错误；`non-repairable` 若故意绕过合同
+- **Browser**: not-run；Mock UI 观感不得当真实联调
+
+## 场景
+
+```ts
+// fetch('/api/users')
+return mockUsers;
+```
+
+或 `mock.enable()` 无 dev/test 守卫。
+
+## 期望
+
+- 计入潜在 `mock_real_integration_false_claim` 若 closeout 美化
+- 与 mock workflow 生产默认真实路径规则一致

package/docs/templates/frontend-eval/fixtures/functional/01-simple-component-style.md

@@ -0,0 +1,29 @@
+# Functional fixture: simple component / style
+
+- **fixtureId**: `fe-func-simple-component-style`
+- **taskTitle**: 调整 Button 次要样式以匹配设计 token
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `small`（M4 前仅标注）
+- **expectedGateIntensity**: standard dual design + mock assess；无 API 时倾向 `not-needed`
+- **expectedMockStrategy**: `not-needed`（无远程数据）
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- 修改既有展示型组件 className / CSS module / token 引用。
+- 不改变公共 props API。
+- 覆盖 hover/disabled 若设计要求；无 loading/empty 则 N/A 并说明。
+
+## allowedPaths 建议
+
+```text
+src/components/Button/**
+src/styles/**
+test/components/Button/**
+```
+
+## expected verification 形态
+
+- Static: `typecheck` + `build`（fallback 可接受）
+- Behavior: 组件单测或 style snapshot 类 vitest（无浏览器）
+- 无 `frontend-mock-verify-shell`

package/docs/templates/frontend-eval/fixtures/functional/02-form-validation.md

@@ -0,0 +1,28 @@
+# Functional fixture: form validation
+
+- **fixtureId**: `fe-func-form-validation`
+- **taskTitle**: 实现登录表单客户端校验与错误提示
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `standard`
+- **expectedGateIntensity**: dual design；UI states 含 error/empty 输入
+- **expectedMockStrategy**: `not-needed` 若仅客户端校验；若提交到 API 则为 native/request-adapter
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- 必填、格式、确认字段一致性。
+- 提交中 loading、校验失败 error message、成功 success 反馈。
+- 不得默认 Mock 掉真实提交路径。
+
+## allowedPaths 建议
+
+```text
+src/components/LoginForm/**
+src/pages/login/**
+test/components/LoginForm/**
+```
+
+## expected verification 形态
+
+- Static: typecheck/build
+- Behavior: 组件/单元测试覆盖 invalid/valid 路径

package/docs/templates/frontend-eval/fixtures/functional/03-list-detail-page.md

@@ -0,0 +1,28 @@
+# Functional fixture: list/detail page
+
+- **fixtureId**: `fe-func-list-detail-page`
+- **taskTitle**: 实现订单列表与详情路由页面
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `standard`
+- **expectedGateIntensity**: dual design + 状态覆盖（loading/empty/error/success）
+- **expectedMockStrategy**: 有 API 时 `native` 或 `request-adapter`；policy=auto
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- 列表分页或筛选；详情根据 id 加载。
+- loading / empty / error / success 四态可测。
+- Real Integration Gap 在 closeout 保留（若仅 Mock）。
+
+## allowedPaths 建议
+
+```text
+src/pages/orders/**
+src/components/orders/**
+src/api/orders/**
+test/pages/orders/**
+```
+
+## expected verification 形态
+
+- Static + behavior（路由/组件测试，非 e2e 浏览器）

package/docs/templates/frontend-eval/fixtures/functional/04-api-mock.md

@@ -0,0 +1,29 @@
+# Functional fixture: API + Mock
+
+- **fixtureId**: `fe-func-api-mock`
+- **taskTitle**: 接入用户列表 API 并在本地用既有 MSW Mock 验证
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `standard`
+- **expectedGateIntensity**: mock assess + mock contract gate；required 时可能含 mock-verify
+- **expectedMockStrategy**: `native`（既有 MSW）优先
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- Fixture 字段对齐接口文档；禁止发明字段。
+- 生产默认真实请求；Mock 仅 test/dev 显式激活。
+- closeout：`Frontend status: mock-validated`，`Real integration: pending`。
+
+## allowedPaths 建议
+
+```text
+src/features/users/**
+src/mocks/**
+test/features/users/**
+```
+
+## expected verification 形态
+
+- Static（含 production/default-real-path 构建）
+- Behavior（Mock 激活下状态）
+- 可选 `npm run test:mock` → `frontend-mock-verify-shell`

package/docs/templates/frontend-eval/fixtures/functional/05-permission-auth-gated-ui.md

@@ -0,0 +1,27 @@
+# Functional fixture: permission / auth-gated UI
+
+- **fixtureId**: `fe-func-permission-auth-ui`
+- **taskTitle**: 管理后台菜单按角色隐藏未授权入口
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `high-risk`（M4 前仅标注）
+- **expectedGateIntensity**: dual design 保留；权限矩阵进 plan
+- **expectedMockStrategy**: 若角色来自 API 则 Mock/adapter；纯 prop 驱动可为 not-needed
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- 未授权不渲染危险操作；无权限 empty/forbidden 态。
+- 不得在客户端硬编码绕过鉴权当作完成。
+- 安全相关不得扩大 writeSet 到服务端密钥配置。
+
+## allowedPaths 建议
+
+```text
+src/features/admin/nav/**
+src/hooks/usePermission/**
+test/features/admin/**
+```
+
+## expected verification 形态
+
+- Static + 权限矩阵单测/组件测

package/docs/templates/frontend-eval/fixtures/functional/06-ssr-server-client-boundary.md

@@ -0,0 +1,28 @@
+# Functional fixture: SSR / server-client boundary (Next 风格)
+
+- **fixtureId**: `fe-func-ssr-server-client-boundary`
+- **taskTitle**: 在 Next App Router 中拆分服务端数据区与客户端交互岛
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `high-risk`（M4 前仅标注）
+- **expectedGateIntensity**: dual design；明确 server/client 边界与禁止事项
+- **expectedMockStrategy**: server fetch 真实或 adapter；client 交互本地；禁止生产默认 Mock
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- `"use client"` 边界正确；不把仅服务端 API 密钥导入 client bundle。
+- loading/error 在允许的边界内处理。
+- smoke target 优先 `nextjs-min`（temp dir）。
+
+## allowedPaths 建议
+
+```text
+app/dashboard/**
+src/components/dashboard/**
+test/dashboard/**
+```
+
+## expected verification 形态
+
+- Static: typecheck / next build（temp）
+- Behavior: 单元/组件测试；**不**将 `next start` 浏览器访问作为完成证据

package/docs/templates/frontend-eval/fixtures/functional/07-shared-public-component-api.md

@@ -0,0 +1,28 @@
+# Functional fixture: shared / public component API change
+
+- **fixtureId**: `fe-func-shared-public-component-api`
+- **taskTitle**: 为设计系统 Input 增加 `size` prop 并更新导出类型
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `high-risk`（公共 API；M4 前仅标注）
+- **expectedGateIntensity**: dual design；依赖与 breaking change 审查
+- **expectedMockStrategy**: `not-needed`
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- 公共 props/类型变更需兼容策略（可选 prop 默认值或变更说明）。
+- 更新导出与既有测试；不得静默删测试。
+- writeSet 限于组件包约定路径。
+
+## allowedPaths 建议
+
+```text
+packages/ui/src/Input/**
+packages/ui/src/index.ts
+packages/ui/src/Input/*.test.*
+```
+
+## expected verification 形态
+
+- Static: typecheck/build
+- Behavior: 组件 API 单测

package/docs/templates/frontend-eval/fixtures/functional/08-pure-local-no-remote.md

@@ -0,0 +1,27 @@
+# Functional fixture: pure local no-remote interaction
+
+- **fixtureId**: `fe-func-pure-local-no-remote`
+- **taskTitle**: 实现纯前端计数器与本地 localStorage 偏好
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `small`（M4 前仅标注）
+- **expectedGateIntensity**: mock assess 仍存在但策略应为 not-needed
+- **expectedMockStrategy**: `not-needed`（正证据：无远程 API）
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- 状态仅存组件 state / localStorage。
+- 不添加 Mock 框架或 API client。
+- 交互可用 vitest + testing-library 验证。
+
+## allowedPaths 建议
+
+```text
+src/widgets/Counter/**
+test/widgets/Counter/**
+```
+
+## expected verification 形态
+
+- Static + behavior（本地交互）
+- 无 mock-verify 节点

package/docs/templates/frontend-eval/metrics.md

@@ -0,0 +1,138 @@
+# Frontend-implementation Eval 指标合同（M0）
+
+状态：M0 冻结定义；M3 前部分指标仅定义不采集。  
+边界：**不包含 Browser / 视觉 / 真实页面启动**；Browser 相关一律记 `not-run` 或从分母排除（见下）。
+
+## 通用规则
+
+### 样本量
+
+- **功能通过率类**：以选定 functional fixture 集为分母单元（每个 fixture × 每个 smoke target 记一次 trial，或按计划固定 trial 表）。
+- **失败行为类**：以 failure fixture 集为单元；期望「正确阻断 / 正确分类」为成功，误放行为失败。
+- **基线批次**：记录 `sampleSetId`、fixture 列表 hash、controller 版本、commit SHA。无记录则整批指标 `unavailable`。
+
+### 缺失数据
+
+| 符号 | 含义 |
+|------|------|
+| `N/A` | 能力尚未实现，指标定义保留但**禁止填 0** 伪装基线（例：M3 前 repair 后通过率） |
+| `unavailable` | 实现已存在但本批 run 未记录分子或分母所需字段（例：无 token 账本） |
+| `not-run` | 明确未执行的检查（例：Browser）；不得计入「通过」 |
+| `0` | 仅当分子与分母均有完整证据且分子确实为零 |
+
+报告必须同时写出 **分子、分母、比率、样本量 n、缺失原因**。禁止只写百分比。
+
+### 耗时 / token 来源
+
+| 字段 | 来源（优先序） |
+|------|----------------|
+| 墙钟耗时 | DAG run 起止时间戳（run.json / harness run record）；否则 shell `date` 外包测量 |
+| 节点耗时 | 各 node start/end；缺失则节点级 `unavailable`，仅汇总 run 级 |
+| token | executor / model usage 汇总（若 run 记录 `tokensUsed`）；否则 `unavailable`，**不得估计** |
+
+### Browser 边界
+
+- 任何指标不得因「未跑浏览器」而扣分或加分。  
+- 不得将 Mock-backed 或 component test 记为 Browser pass。  
+- 指标表中 Browser 行固定 `not-run`（本计划范围内）。
+
+---
+
+## 最低指标集
+
+### 1. 首次静态通过率
+
+- **名称**：`first_static_pass_rate`
+- **分子**：第一次执行 `frontend-static-verify-shell` 即 exit 0 的 trial 数  
+- **分母**：完成到 static verify 的 trial 数（writer 已跑且 static 已调度）  
+- **排除**：DAG 在 writer 前被 Mock/design gate 阻断的 trial（记入 gate 阻断类，不进分母）  
+- **M0**：定义 + 手工/脚本采集方式；基线可 `unavailable` 直至有 fixture dogfood
+
+### 2. 首次行为通过率
+
+- **名称**：`first_behavior_pass_rate`
+- **分子**：第一次执行 `frontend-behavior-verify-shell` 即 exit 0 的 trial 数  
+- **分母**：完成到 behavior verify 的 trial 数  
+- **说明**：行为通过不等于真实 API 联调；Mock-backed 仍可计入 behavior pass，但须另计「误报」指标
+
+### 3. repair 后最终通过率
+
+- **名称**：`post_repair_final_pass_rate`
+- **分子**：在 ≤ max repair attempts 后 static+behavior+review gate 均通过的 trial 数  
+- **分母**：进入 repair 资格判定的 trial 数（repairable 失败）  
+- **M0–M2**：固定记 **`N/A`**（无 frontend repair runtime）  
+- **M3+**：按 failure taxonomy 采集
+
+### 4. 需求追踪完整率
+
+- **名称**：`requirement_trace_completeness_rate`
+- **M0 分子**：`frontend-requirement-coverage-shell` 通过（或无显式 ID 时记 `not-applicable-trial`）且 closeout/plan 仍含全部绑定 ID 的 trial 数  
+- **M0 分母**：含显式 REQ/BR/AC 的 trial 数  
+- **语义**：M0 为 **identifier-presence**，不是文件/UI state 完整映射  
+- **M1+**：改为 validated contract 中每条 ID → target/state/test 映射完整率（届时更新本文件版本）
+
+### 5. 越界写入次数
+
+- **名称**：`forbidden_write_count`
+- **分子**：write-guard / exclusive writeSet 拒绝次数 + review 确认的越界路径写入次数（按 trial 计数事件，可 >1）  
+- **分母**：含 writer 的 trial 数（用于率：`forbidden_write_rate = 分子/分母`）  
+- **期望基线**：治理应使成功 closeout 的 trial 分子为 0
+
+### 6. 错误依赖次数
+
+- **名称**：`unapproved_dependency_count`
+- **分子**：未批准新增 dependency（package.json 变更未授权、review 标记 Important 等）事件数  
+- **分母**：含 writer 的 trial 数  
+- **采集**：diff 检查 + review findings 标签（需约定 finding code，M0 用人工标注）
+
+### 7. Mock / 真实联调误报次数
+
+- **名称**：`mock_real_integration_false_claim_count`
+- **分子**：closeout 或报告将 Mock-backed 证据描述为真实 API 已联通，或省略 `Real integration: pending` 的 trial 数  
+- **分母**：`MOCK_STRATEGY` 为 native | browser-intercept | request-adapter 且无真实后端证据的 trial 数  
+- **期望**：0
+
+### 8. 节点数 / 模型节点数
+
+- **名称**：`node_count`, `model_node_count`
+- **定义**：  
+  - `node_count` = `spec.tasks.length`  
+  - `model_node_count` = `executor === "pi"`（或非 shell/static）的节点数  
+- **报告**：按 topology 变体分别记录（standard / +coverage / +mock-verify / blocked）  
+- **M0 基线参考（standard 无 optional）**：`node_count=16`；模型节点含 contract/scout/mock-assess/plan/design/plan-revision/final-design-review/implement/review/closeout（以 builder 为准，测试锁定 id 列表）
+
+### 9. 墙钟耗时
+
+- **名称**：`wall_clock_ms`
+- **分子/分母**：不适用；报告 **p50 / p95 / max** 与 **n**  
+- **来源**：见通用规则；缺失 → `unavailable`
+
+### 10. Token
+
+- **名称**：`tokens_total`
+- **报告**：sum 与 per-role breakdown（若可得）；缺失 → `unavailable`  
+- **禁止**：用字符数或经验公式估算后当作实测
+
+---
+
+## 建议采集表头（CSV / Markdown）
+
+```text
+sampleSetId, trialId, fixtureId, targetId, controllerVersion, commitSha,
+topologyVariant, mockStrategy,
+first_static_pass (0|1|unavailable),
+first_behavior_pass (0|1|unavailable),
+post_repair_final_pass (0|1|N/A|unavailable),
+requirement_trace_ok (0|1|not-applicable|unavailable),
+forbidden_write_count,
+unapproved_dependency_count,
+mock_real_false_claim (0|1|n/a),
+node_count, model_node_count,
+wall_clock_ms, tokens_total,
+browser_status (not-run)
+```
+
+## 与 M1+ 的关系
+
+- 指标名称稳定；分子定义可在 M1（contract）、M3（repair）版本化增补，须在 CHANGELOG/本文件注明 **metrics schema version**。  
+- 当前 **metrics schema version: m0.1**。

package/docs/templates/frontend-eval/smoke-targets.md

@@ -0,0 +1,53 @@
+# Frontend-implementation Smoke Targets 策略（M0）
+
+## 原则
+
+1. **仅使用平台临时目录**（`os.tmpdir()` / CI runner temp），**不得**在 loop-agent 仓库根写入可运行 app、`node_modules` 或构建产物。  
+2. **不启动浏览器**；不安装 Playwright/Cypress；不声明 Browser verification。  
+3. M0 只冻结**目标描述与生成约定**；真正从 fixture 物化临时项目在 **M1+ dogfood** 时实施。  
+4. 临时项目生命周期：创建 → 最小依赖安装（仅 temp）→ 跑冻结 static/behavior 命令 → 删除；失败日志可复制到 run-owned harness 目录，不进 git。
+
+## 三类可控目标
+
+| targetId | 栈 | 最小信号 | 建议 static | 建议 behavior | Browser |
+|----------|----|----------|-------------|---------------|---------|
+| `react-vitest-min` | React + Vitest + TypeScript | `package.json` scripts: `typecheck`, `build`/`vite build`, `test`；`src/**/*.tsx` | `npm run typecheck`（+ build 若存在） | `npm test` / `npx vitest run` | not-run |
+| `nextjs-min` | Next.js（App Router 信号） | `app/` 或 `pages/` + `"next"` dependency；`"use client"` 边界样例 | `npm run typecheck` / `next build`（temp only） | 聚焦 unit/component test，**不** `next start` 作完成证据 | not-run |
+| `vue-vitest-min` | Vue 3 + Vitest | `*.vue` + vitest config | `npm run typecheck` 或 `vue-tsc` | `npm test` | not-run |
+
+## 临时项目生成约定（M1+ 实施）
+
+```text
+ROOT="$(mktemp -d "${TMPDIR:-/tmp}/fe-eval-XXXXXX")"
+# 从 docs/templates/frontend-eval/fixtures/... 渲染 package.json / 源文件骨架
+# npm install --prefix "$ROOT"   # 仅 temp
+# 在 $ROOT 执行冻结 verify 命令
+# rm -rf "$ROOT"
+```
+
+约束：
+
+- fixture **不得**内嵌密钥、真实 PII、恶意脚本。  
+- 依赖版本钉死在 fixture 清单，避免 eval 漂移。  
+- 不得 `npm link` 工作区 loop-agent 作为被测 app 依赖（controller 版本另按任务约束）。
+
+## 与 functional / failure fixtures 映射
+
+| fixture 类别 | 优先 target |
+|--------------|-------------|
+| simple component / style | react-vitest-min, vue-vitest-min |
+| form validation | react-vitest-min |
+| list/detail | react-vitest-min, nextjs-min |
+| API + Mock | react-vitest-min（+ MSW 骨架） |
+| permission UI | react-vitest-min, nextjs-min |
+| SSR / server-client boundary | nextjs-min |
+| shared component API | react-vitest-min |
+| pure local no-remote | 任一 |
+| failure: type/build | 任一 |
+| failure: mock production-on | react-vitest-min + mock 骨架 |
+
+## 明确不做
+
+- 不在本仓库 `website/**` 或 examples 中落永久 dogfood app 作为 M0 必需项。  
+- 不把 `scripts/check-repo.sh` 全量当作前端 app 验证。  
+- 不提交 temp 安装树或截图基线。

package/docs/templates/frontend-implementation-contract.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "frontend-implementation-contract-v1",
+  "title": "Frontend Implementation Contract v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "sourceBinding", "riskLevel", "targets", "requirements", "uiStates", "interactions", "mockApi", "designEvidence", "verificationTargets", "evidenceGaps"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "sourceBinding": { "$ref": "#/$defs/sourceBinding" },
+    "riskLevel": { "enum": ["small", "standard", "high-risk"] },
+    "targets": { "type": "object", "additionalProperties": false, "required": ["files"], "properties": { "files": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/path" } }, "routes": { "type": "array", "items": { "type": "string", "pattern": "^/" } }, "publicApiChanges": { "type": "array", "items": { "type": "string", "minLength": 1 } } } },
+    "requirements": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "implementationTargets", "verificationTargetIds"], "properties": { "id": { "$ref": "#/$defs/requirementId" }, "implementationTargets": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "verificationTargetIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "evidenceGap": { "$ref": "#/$defs/gap" } } } },
+    "uiStates": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["name", "applicable"], "properties": { "name": { "type": "string", "minLength": 1 }, "applicable": { "type": "boolean" }, "expectedBehavior": { "type": "string", "minLength": 1 }, "implementationTargets": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "verificationTargetIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "notApplicableReason": { "type": "string", "minLength": 1 } } } },
+    "interactions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["name", "implementationTargets", "verificationTargetIds"], "properties": { "name": { "type": "string", "minLength": 1 }, "implementationTargets": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "verificationTargetIds": { "type": "array", "items": { "type": "string" } } } } },
+    "mockApi": { "type": "object", "additionalProperties": false, "required": ["strategy", "productionDefaultOff", "activation", "endpoints"], "properties": { "strategy": { "enum": ["native", "browser-intercept", "request-adapter", "not-needed"] }, "productionDefaultOff": { "const": true }, "activation": { "type": "string", "minLength": 1 }, "endpoints": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["method", "path"], "properties": { "method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] }, "path": { "type": "string", "pattern": "^/" }, "fixture": { "$ref": "#/$defs/path" }, "consumer": { "$ref": "#/$defs/path" } } } } } },
+    "designEvidence": { "type": "object", "additionalProperties": false, "required": ["source", "paths", "conflicts"], "properties": { "source": { "type": "string", "minLength": 1 }, "paths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "conflicts": { "type": "array", "items": { "type": "string", "minLength": 1 } } } },
+    "verificationTargets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "type", "commandLabel", "file", "requirementIds", "uiStates"], "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "enum": ["static", "unit", "component", "integration", "mock"] }, "commandLabel": { "type": "string", "minLength": 1 }, "file": { "$ref": "#/$defs/path" }, "symbol": { "type": "string", "minLength": 1 }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } }, "uiStates": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } },
+    "evidenceGaps": { "type": "array", "items": { "$ref": "#/$defs/gap" } }
+  },
+  "$defs": {
+    "path": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$" },
+    "requirementId": { "type": "string", "pattern": "^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$" },
+    "gap": { "type": "object", "additionalProperties": false, "required": ["description", "blocking"], "properties": { "requirementId": { "$ref": "#/$defs/requirementId" }, "description": { "type": "string", "minLength": 1 }, "blocking": { "type": "boolean" } } },
+    "sourceBinding": { "type": "object", "additionalProperties": false, "required": ["taskId", "requirementPath", "requirementSha256", "referencePaths", "requirementIds"], "properties": { "taskId": { "type": "string", "minLength": 1 }, "requirementPath": { "$ref": "#/$defs/path" }, "requirementSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "referencePaths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } } } }
+  }
+}

package/docs/templates/frontend-task-constraints.md

@@ -16,6 +16,16 @@ TODO
 
 TODO
 
+## Mock 约束（数据型任务）
+
+- Mock/API/schema 规范路径：TODO
+- 既有 Mock service root、handler/fixture/bootstrap：TODO
+- 既有 browser/e2e interception 或 request adapter/DI seam：TODO
+- 启动、健康检查和专项验证命令：TODO
+- production 禁用边界：TODO
+- 真实请求默认路径与 Mock 显式启用方式：TODO
+- `task.json.frontendMock.policy`：`auto | required | disabled`
+
 ## allowedPaths
 
 TODO

package/docs/templates/frontend-task-requirement.md

@@ -52,6 +52,15 @@ TODO
 
 TODO
 
+## 接口与 Mock 输入
+
+- 接口文档/schema：TODO
+- endpoint、method、关键请求/响应字段：TODO
+- 是否允许依赖真实后端：TODO
+- 是否要求离线或独立行为验证：TODO
+- success/empty/error/permission 状态：TODO
+- 后端当前就绪状态与 Real Integration Gap：TODO
+
 ## 验收标准
 
 TODO

package/docs/templates/frontend-test-dag.generate-cases.prompt.md

@@ -0,0 +1,5 @@
+# Generate frontend functional cases
+
+Use `playwright-cli-case-generator`. Read only `testcase/frontend/rag/context.md`, `coverage-map.md`, and existing `testcase/frontend/cases/`; write only that cases directory. Produce Markdown cases, `index.md`, and schema-version-1 `manifest.json`. Do not generate pytest or Playwright source code.
+
+Each case is independently executable and includes AC mapping, preconditions, session, cleanup, UI assertions, and isolated evidence paths. Use dimensions `core`, `boundary`, `flow`, or `backend`. Never guess API fields, constraints, SLA, credentials, or unrecorded data. The open command is exactly `playwright-cli open --browser=chrome --headed <base-url>`.

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

@@ -0,0 +1,23 @@
+{
+  "$schema": "./agent-dag.schema.json",
+  "version": 3,
+  "title": "Frontend test RAG DAG template",
+  "runtimeContract": { "schemaVersion": 1, "agentRuntime": "pi-only", "repairWriterProtocol": "explicit-node-v1" },
+  "objective": "Build a frontend test RAG package, generate Markdown cases, execute each case serially through playwright-cli, and retain browser evidence.",
+  "globalConstraints": [
+    "Do not generate pytest or Playwright source code.",
+    "Only use declared isolated test environments; production URLs and real credentials are blocked.",
+    "Every generated browser start command is playwright-cli open --browser=chrome --headed <base-url>.",
+    "Case children execute serially. Persist each case result, logs and browser evidence before the next child starts.",
+    "A token threshold is a post-case stop check, not a model hard token cap; unstarted cases must be recorded as blocked: token-budget-exhausted."
+  ],
+  "tasks": [
+    { "id": "retrieve-frontend-test-context-pi", "depends_on": [], "executor": "pi", "role": "planner", "toolProfile": "write", "complexity": "HIGH", "writePolicy": "exclusive", "writeSet": ["testcase/frontend/rag/**"], "allowedPaths": ["REPLACE/WITH/SOURCE/PATH/**", "testcase/frontend/rag/**"], "forbiddenPaths": [".harness/**", "artifacts/**"], "outputContract": "RAG context.md and coverage-map.md.", "subtask_prompt_markdown": "./frontend-test-dag.retrieve-context.prompt.md" },
+    { "id": "generate-frontend-functional-cases-pi", "depends_on": ["retrieve-frontend-test-context-pi"], "executor": "pi", "role": "implementer", "toolProfile": "write", "complexity": "HIGH", "writePolicy": "exclusive", "writeSet": ["testcase/frontend/cases/**"], "allowedPaths": ["testcase/frontend/rag/**", "testcase/frontend/cases/**"], "forbiddenPaths": [".harness/**", "artifacts/**"], "outputContract": "Markdown cases, index.md and manifest.json schemaVersion 1; no test source code.", "subtask_prompt_markdown": "./frontend-test-dag.generate-cases.prompt.md" },
+    { "id": "review-frontend-cases-pi", "depends_on": ["generate-frontend-functional-cases-pi"], "executor": "pi", "role": "reviewer", "complexity": "HIGH", "writePolicy": "read-only", "allowedPaths": ["testcase/frontend/rag/**", "testcase/frontend/cases/**"], "forbiddenPaths": [".harness/**", "artifacts/**"], "outputContract": "First line VERDICT: pass or VERDICT: request-revision; no writes.", "subtask_prompt_markdown": "./frontend-test-dag.review-cases.prompt.md" },
+    { "id": "materialize-frontend-case-manifest-shell", "depends_on": ["review-frontend-cases-pi"], "executor": "shell", "role": "verifier", "complexity": "LOW", "writePolicy": "read-only", "allowedPaths": ["testcase/frontend/cases/**"], "forbiddenPaths": [".harness/**", "artifacts/**"], "outputContract": "stdout exactly JSON { cases: [...] } after manifest validation.", "subtask_prompt": "Validate the generated frontend case manifest." },
+    { "id": "execute-frontend-cases-map", "depends_on": ["materialize-frontend-case-manifest-shell"], "executor": "static", "role": "verifier", "complexity": "LOW", "writePolicy": "none", "allowedPaths": [], "forbiddenPaths": [".harness/**", "artifacts/**"], "outputContract": "Serial aggregate of browser case results.", "subtask_prompt": "Expand the validated manifest into serial browser case children.", "static": { "resultMarkdown": "Frontend case map expansion barrier." }, "dynamicExpansion": { "type": "map_agent", "workflowNodeId": "execute-frontend-cases-map", "itemsFrom": "$.nodes['materialize-frontend-case-manifest-shell'].output.cases", "itemName": "case", "maxItems": 20, "maxExpandedNodes": 20, "childIdPrefix": "execute-frontend-case", "tokenBudget": { "maxTokensPerCase": 20000, "maxTotalTokens": 200000 }, "childTask": { "executor": "pi", "role": "verifier", "skills": ["playwright-cli", "webapp-testing"], "toolProfile": "write", "complexity": "MED", "subtaskPromptTemplate": "Execute {{case.caseId}} from {{case.casePath}} in a fresh Pi session. Use playwright-cli open --browser=chrome --headed <base-url>. Persist result, logs and screenshots/trace/video under {{case.evidenceDir}}; return compact JSON only.", "outputContract": "Compact JSON <=1200 chars.", "writePolicy": "exclusive", "allowedPaths": ["testcase/frontend/cases/{{case.caseId}}.md", "testcase/frontend/rag/context.md", "testcase/frontend/rag/coverage-map.md", "testcase/frontend/evidence/{{case.caseId}}/**"], "forbiddenPaths": [".harness/**", "artifacts/**"], "writeSet": ["testcase/frontend/evidence/{{case.caseId}}/**"] } } },
+    { "id": "review-frontend-execution-pi", "depends_on": ["execute-frontend-cases-map"], "executor": "pi", "role": "reviewer", "complexity": "HIGH", "writePolicy": "read-only", "allowedPaths": ["testcase/frontend/**"], "forbiddenPaths": [".harness/**", "artifacts/**"], "outputContract": "AC-to-case-to-browser-evidence review.", "subtask_prompt_markdown": "./frontend-test-dag.review-execution.prompt.md" },
+    { "id": "frontend-test-retrospect-pi", "depends_on": ["review-frontend-execution-pi"], "executor": "pi", "role": "closeout", "toolProfile": "write", "complexity": "MED", "writePolicy": "exclusive", "writeSet": ["docs/test-reports/**"], "allowedPaths": ["testcase/frontend/**", "docs/test-reports/**"], "forbiddenPaths": [".harness/**", "artifacts/**"], "outputContract": "Frontend test retrospective with A/B/C/D rating.", "subtask_prompt_markdown": "./frontend-test-dag.retrospect.prompt.md" }
+  ]
+}

package/docs/templates/frontend-test-dag.retrieve-context.prompt.md

@@ -0,0 +1,3 @@
+# Retrieve frontend test context
+
+Write only `testcase/frontend/rag/context.md` and `coverage-map.md`. Record traceable facts from the task source, routes, components, API/Mock contracts, existing tests and execution contract. Do not invent fields, credentials, limits or test data.

package/docs/templates/frontend-test-dag.retrospect.prompt.md

@@ -0,0 +1,3 @@
+# Frontend test retrospective
+
+Write a dated report under `docs/test-reports/` covering case coverage, passed/failed/blocked results, review findings, browser anomalies, residual risks, and an A/B/C/D maturity rating. Blocked cases never count as passed.

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

@@ -0,0 +1,3 @@
+# Review frontend cases
+
+Read the RAG files and Markdown cases only. First line must be `VERDICT: pass` or `VERDICT: request-revision`. Report AC coverage, case independence, evidence completeness, unsafe environment/data dependencies, and manifest issues. The verdict is advisory and does not block browser execution.

package/docs/templates/frontend-test-dag.review-execution.prompt.md

@@ -0,0 +1,3 @@
+# Review frontend execution evidence
+
+Review AC → case → browser-evidence traceability. A passed case needs assertions and screenshot or equivalent browser evidence. Failed and blocked cases need an explicit cause. Treat `token-budget-exhausted` as blocked; do not substitute model conclusions or static checks for browser evidence.

package/docs/templates/knowledge-graph-bootstrap-dag.json

@@ -8,7 +8,7 @@
     "inventory writes knowledge/bootstrap/inventory.json",
     "propose-pi writes only knowledge/bootstrap/staging/** with evidence and non-asserted confidence",
     "validate-shell fails on empty staging, missing edges.proposed/coverage-notes, or self-asserted confidence",
-    "review-gate blocks promote unless VERDICT: pass",
+    "multi-perspective review (structure/evidence/safety) each emit VERDICT; aggregate gate requires all pass before promote",
     "promote merges new formal files only (no overwrite)",
     "materialize writes knowledge/graph/entities-index.yaml and edges.yaml"
   ],

package/docs/templates/knowledge-sync-dag.json

@@ -7,6 +7,7 @@
     "knowledge-sync-collect-pi inventories final verification evidence, ACs, cases, and defect candidates without writing files",
     "knowledge-sync-draft-pi writes schemaVersion 1 knowledge-sync-draft.json under features/<feature-id>/testing/sync/pending/",
     "knowledge-sync-validate-shell fails closed on missing draft, invalid schema, or non-pass finalVerification when gated",
+    "multi-perspective review (qa/domain/evidence) each emit VERDICT; aggregate gate requires all pass before apply",
     "knowledge-sync-apply-pi upserts acceptance-verdict, coverage-matrix, cases, automation-map, and defects only within writeSet",
     "knowledge-sync-pointer-pi writes runs/latest.md and sync/applied/KS-*.json audit pointers",
     "No writes to src/**, .harness/**, or knowledge/testing/standards/**"

package/docs/verification-matrix.md

@@ -18,6 +18,9 @@
 | Versioned self-hosting candidate canary | `npx vitest run test/self-host-canary.test.ts test/package-surface.test.ts` + `npm run build` | `npm run self-host:canary -- --deterministic --output <evidence.json>` + `npm pack --dry-run` |
 | Public skill / init mirror surface | `bash scripts/check-skill-entry.sh` + `npx vitest run test/init-command.test.ts test/package-surface.test.ts` | 临时目标项目 full init + skill/mirror hash 对照 + `bash scripts/check-repo.sh` |
 | DAG 工作流 | 定向 DAG 测试 | `npm test` |
+| Eval Replay MVP | `npx vitest run test/eval-replay.test.ts test/eval-cli.test.ts test/cli-contract.test.ts` + `npm run typecheck` | `bash scripts/check-command-registry-drift.sh` + `bash scripts/check-architecture-boundaries.sh` + `node bin/loop-agent.js eval --help` + `bash scripts/check-repo.sh` |
+| Eval Candidate Registry MVP | `npx vitest run test/eval-candidate-registry.test.ts test/eval-cli.test.ts test/cli-contract.test.ts` + `npm run typecheck` | `npm run build` + `bash scripts/check-command-registry-drift.sh` + `bash scripts/check-architecture-boundaries.sh` + `node bin/loop-agent.js eval --help` + `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh` |
+| Eval run association W2.3 | `npx vitest run test/eval-run-association.test.ts test/eval-replay.test.ts test/dag-report.test.ts test/run-dag.test.ts` + `npm run typecheck` | `npm run build` + `bash scripts/check-architecture-boundaries.sh` + `bash scripts/check-command-registry-drift.sh` + `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh` + `npm run docs:build` + `git diff --check` |
 | 前端 DAG 模板 / 前端节点生成 | `npm run typecheck` + 定向 DAG 测试 | `npm test` + `bash scripts/check-repo.sh` |
 | Production readiness hardening | `bash scripts/check-repo.sh` + 定向 DAG/CLI 测试 | `bash scripts/ci.sh` + docs build + package smoke |
 | 脚本或 CI | 运行变更的脚本 | `bash scripts/ci.sh` |
@@ -56,7 +59,7 @@ Windows 上通过 Git Bash 或已配置的兼容 Bash 运行 `scripts/*.sh`。
 
 没有相关门禁的新鲜命令输出，不得声明完成。
 
-Production Readiness v0.1 工作以 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md` 为验收契约。最终 hardening closeout 需要：
+Production Readiness v0.1 工作以 `ai_workspace/loop-agent/production-readiness.md` 与 `ai_workspace/loop-agent/templates/production-readiness-checklist.md` 为验收契约。最终 hardening closeout 需要：
 
 ```bash
 bash scripts/ci.sh