@tea-agent/loop-agent 0.1.0-fe-test.0

package/skills/loop-agent/references/verification-and-failure-handling.md

@@ -0,0 +1,148 @@
+# Verification 与失败处理
+
+选择 verify strategy knobs、解读 verify 结果、决定失败后是否继续，或 closeout workflow/runtime/ai_workspace/loop-agent/skill 变更时使用本文。
+
+## Verify strategy 与 completion audit
+
+## Production Readiness v0.1
+
+低/中风险单 repo DAG 任务如果声明 production-ready v0.1，必须按 `ai_workspace/loop-agent/production-readiness.md` 和 `ai_workspace/loop-agent/templates/production-readiness-checklist.md` 收口。
+
+支持范围：
+
+- single repo
+- bounded task
+- explicit task source
+- explicit `allowedPaths` / `forbiddenPaths` / write scope
+- shell verification
+- report / doctor / closeout handoff
+
+非目标：
+
+- automatic merge
+- automatic release
+- production secrets
+- production database
+- high-risk migration
+- online Worker Pool
+- writable Dynamic Workflow sharded migration
+
+失败分类是路由字段，不是主状态；不要覆盖 `.harness/dag-runs/completed/**` 的原始事实。报告和 handoff 应保留：
+
+```text
+raw_failure_category
+dag_normalized_failure_category
+product_line_failure_category
+recommended_follow_up
+```
+
+product-line taxonomy 的事实源是 `ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
+
+### Verify 始终在本地跑
+`verify` step 跑确定性命令（check-repo.sh + tests + typecheck）。**不**调用 pi。因此快且可靠。
+
+### Verify strategy knobs
+需要更紧的 verify 控制时，用 task-level config：
+```json
+{
+  "verifyPreset": "auto",
+  "verifyMode": "serial",
+  "verifyRetryCount": 0,
+  "verifyFailFast": false
+}
+```
+
+- `verifyPreset`：`auto | quick | standard | full`
+  - `auto`：`small -> quick`，`medium -> standard`，`large -> full`
+- 默认 `serial`，优先避免本机测试、构建和治理检查互相争抢资源
+- 确认命令互不影响且机器资源充足时，才显式使用 `parallel`
+- `verifyFailFast` 仅在 `serial` mode 有意义
+- retry 保持小；用于 flaky 环境问题，不要掩盖真实失败
+
+### 长输出处理
+
+- DAG shell 命令和 Worker 子进程只在内存中保留最近一段 stdout/stderr，并在结果中标明是否截断及原始字节数。
+- 需要完整日志时读取运行 artifact 中的 `stdout.txt`、`stderr.txt` 或 DAG 节点的 `commands/*.stdout.txt`、`commands/*.stderr.txt`；不要依赖页面摘要还原全部输出。
+
+### Verify 后的 goal completion audit
+- 有 active task goal 且 `verify` 通过时，loop-agent 跑 goal completion audit。
+- 若 `source/需求.md` 仍有未勾 checklist（`- [ ]`），task **不会**以 completed 结束。
+- 若确定性 requirement coverage audit 发现未覆盖需求，task **不会**以 completed 结束。
+- `explicitly_out_of_scope` 需求（如 `## 非目标` 下）**不算** coverage gap。
+- 独立 audit 报告用 `handoff coverage <task-id> [--json|--markdown]`。
+- task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>' [--json|--markdown]`。默认仅报告；`--patch` 不能伪造 verification evidence。
+
+### supervised repair gate 与 runtime contract 失败
+
+- `repair artifact gate failed: ... no unique governed Pi writer` / `declares repairNodeId "..." but no task with that id exists`：DagSpec 的 `shell.repairArtifactGate` 未声明 `repairNodeId`，或声明的修复节点缺失、不是 gate 直接下游、不是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`/`writeSet` 非空且不与 `forbiddenPaths` 冲突）。用当前 controller 重新生成 supervised DAG，或按上述契约补齐修复节点，不要靠改节点名绕过。
+- `repair artifact field "rootCause" must be a non-empty string`：`request-revision` 的 `REPAIR_ARTIFACT_JSON.rootCause` 为空时 parser 不再容错，诊断必须明确根因。只有 `verdict: "pass"` 且 `rootCause` 为空白时才会被确定性规范化为 `No repair required.`，其余字段（fixScope、verdict mismatch、writer 边界）保持 fail-closed。
+- `missing DECISION_ENVELOPE_JSON fenced block` / `decision-envelope-invalid`：`DECISION_ENVELOPE_JSON` info string 的 Markdown 围栏必须存在且唯一。Parser 接受三反引号及更长围栏，但 opening/closing fence 必须同长度，closing 同行只能有空白；不匹配围栏、裸 JSON、多个围栏、malformed JSON、schema-invalid 与 semantic-invalid 仍 fail-closed。若错误 payload 含 `taskId`、`gate`、`verdict`、`summary` 或 `decision: proceed-to-closeout`，说明 decision prompt/schema 漂移；用包含 canonical schema 示例的当前 controller 重新生成 DAG，不要放宽 parser 接受 legacy 结构。
+- `incompatible DAG runtime contract` / `runtime contract requires ...`：DagSpec 的 `runtimeContract` 要求的能力超出当前 controller。升级 controller 或用当前 controller 重新生成 DAG；该 preflight 在任何节点执行前失败，不会留下半执行的 run。
+- `controller identity drifted` / `artifact was tampered with`：resume 时的 controller 与 run 创建时冻结的 identity 不一致（package 内容、binary 或 fingerprint 变化），或 `controller-identity.json` 被篡改。启动新 run，而不是在漂移后 resume；completed run facts 保持只读。
+
+### Verify 默认保存进度
+`verify` 成功后，loop-agent 默认：
+
+1. 在当前 task scope 内选文件
+2. 跑 `git add`
+3. 创建 commit 保存已验证进度
+
+默认行为：
+
+- `autoCommitAfterVerify: true`
+- commit message：`chore(task): save verified progress for <taskId>`
+
+`task.json` 可选覆盖：
+
+```json
+{
+  "autoCommitAfterVerify": false,
+  "autoCommitMessage": "docs(workflow): save verified progress"
+}
+```
+
+最佳实践：保持 `allowedPaths` 准确。auto-commit 用 task path 约束，避免把无关 dirty 文件扫进 progress commit。
+
+### Cursor bounded write 后的独立复核
+
+显式 `cursor-prompt` sidecar（非默认路径）完成后，主会话必须**独立跑验证命令**，不得用手改代码「补成绿色」：
+
+```bash
+git status --short
+git diff --stat
+bash scripts/check-repo.sh
+npm run lint
+npm test
+npm run typecheck
+loop-agent inspect
+loop-agent docs audit
+loop-agent handoff check <task-id>
+```
+
+Cursor / 主会话自述完成不算 verification fact；以上命令的 exit code 与输出才是完成声明的证据。
+
+### 失败处理（Compatibility / Operator Assist）
+
+主会话定位为 operator，**不是**失败后的实现后备通道。
+
+| 失败类型 | 主会话允许 | 主会话禁止 |
+|---|---|---|
+| 业务/测试失败 | 在同一 bounds 内 **重跑** DAG writer / repair 节点；`dag doctor` / `dag report` | 直接 Edit 业务实现「先修好再说」 |
+| Workflow / runtime 失败 | `dag doctor`、`dag reconcile-run`、记 human gate、升级/重装已发布 controller 后 **新 run**；必要时修 **task source / DAG JSON** 再 validate | 主会话手动完成 scoped implementation 以绕过 CLI |
+| Write guard / path 冲突 | 收紧 `allowedPaths`/`writeSet` 后 regenerate/revalidate | 扩大权限后由主会话直接写 |
+| 需求/架构不清 | Decision Gate / human approval | 边猜边改业务代码 |
+| 意外残留（tmp/scratch） | handoff 前删除 scratch；记录在 report | 把清理当成「顺便重构实现」 |
+
+**默认恢复序列**：diagnose（doctor/report）→ classify → reconcile 或 replan → CLI 重跑 → shell verify。
+**永远不要**：`loop-agent` / `agent-worker` 失败 ⇒ 主会话直接改仓库实现。
+
+### Closeout 规则
+workflow/runtime/ai_workspace/loop-agent/skill 变更结束时：
+```bash
+loop-agent docs audit
+loop-agent handoff check <task-id>
+```
+
+active exec plan 实质完成时，用 `docs archive` 归档并更新 active/completed 索引，勿留 stale active status。
+
+failed DAG run 不应生成成功式 closeout。它应该生成 failure handoff，至少包含 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。

package/skills/playwright-cli/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: playwright-cli
+description: 在 frontend-test DAG 中通过受限的结构化 playwright_cli 工具执行浏览器交互与证据采集。
+---
+
+# Browser Automation with playwright-cli
+
+## frontend-test DAG 契约
+
+本 skill 面向 frontend-test DAG browser child。每个浏览器操作都必须转换为一次结构化
+`playwright_cli` tool call：`{ command, args?, timeoutSeconds? }`。
+
+- 当前运行时不提供任意命令执行入口；不得尝试其他浏览器自动化工具或测试运行器。
+- 缺少普通终端能力不表示浏览器工具不可用；仅当 preflight 或 `playwright_cli` 明确失败时，记录
+  `playwright-cli-unavailable` 或相应 contract error。
+- 不可由受限命令和已记录证据证明的场景必须标记为 `blocked`，不得臆测通过。
+- browser case 只能使用下列 runtime allowlist 中的命令。每个命令行由 controller 转为结构化调用，
+  不直接执行文本命令。
+
+## Runtime allowlist
+
+```text
+open
+close
+goto
+snapshot
+find
+click
+dblclick
+fill
+type
+press
+keydown
+keyup
+hover
+select
+check
+uncheck
+drag
+drop
+upload
+go-back
+go-forward
+reload
+dialog-accept
+dialog-dismiss
+resize
+screenshot
+pdf
+console
+requests
+request
+```
+
+## 推荐执行流程
+
+使用 `testcase/frontend/rag/context.md` 中已由 environment shell 标记为 `reachable` 的非生产 `baseUrl` 和默认浏览器 session；不得创建 named session。交互前先获取 snapshot，并只使用 snapshot 中可见的 ref 或已知安全 locator。
+
+```text
+playwright-cli open --browser=chrome http://localhost:5173
+playwright-cli snapshot
+playwright-cli find "Sign in"
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli find "Welcome"
+playwright-cli close
+```
+
+成功的 `find` 是唯一可用于 UI 语义断言的浏览器证据。`snapshot`、导航、截图、网络观察、
+普通交互和控制台输出均不能单独取得 passed authority。通过的 case 还需要同一 child 的有序
+controller receipts：successful `open` → successful `find` → successful post-execution cleanup。
+
+## 受限证据采集
+
+- UI 状态：先 `snapshot`，完成交互后以成功 `find` 证明用户可见结果。
+- 后端观察：可使用 `requests` 列出已观察到的请求，再以 `request <id>` 查看单个已观察请求。
+  这类观察不能替代成功 `find` 的 UI 语义证据。
+- 文件型证据：`screenshot` 与 `pdf` 必须使用 `--filename <file>`，且文件名由 controller 规范化到当前 case evidence 目录。截图一律写为 `playwright-cli screenshot --filename final.png`；有真实元素 ref 时写为 `playwright-cli screenshot e5 --filename final.png`。`pdf` 写为 `playwright-cli pdf --filename final.pdf`。`snapshot` 不带 filename 时只返回响应；需要文件时写为 `playwright-cli snapshot --filename snapshot.txt`。不得使用 `--path`、`--output`、`--file`，也不得把文件路径作为位置参数。
+- 对话框、上传、拖放和视口变化仅在 case 已给出所需前置条件时使用对应 allowlist 命令。
+
+## 持久化执行事实
+
+每个 browser case 必须在自身 evidenceDir 写入权威的 `execution.md` 与 `case-result.json`，最终报告只读取最后一次写入的文件：
+
+- `case-result.json`：包含匹配的 `caseId`、最终 `status`（`passed`/`failed`/`blocked`）、`evidencePaths`；重跑时用整数 `rerunAttempt` 覆写同一文件，最终状态即报告状态。
+- `execution.md`：当存在可记录的执行事实时，使用固定标题 `### 执行摘要` 与 `### 实际执行步骤`，以便有界确定性报告抽取器展示实际执行步骤与摘要。这两段为可选；缺失只形成 advisory，不会降级已通过状态。
+
+## 阻塞处理
+
+当环境、数据、权限、时序、异常路径或响应内容无法用 RAG、已验证 context URL 和 runtime allowlist 证明时，
+写入 `blocked` evidence，并提供具体 `blockedReason`。不要引入替代执行路径，也不要把隐藏状态或
+未观察到的网络结果当作通过证据。

package/skills/playwright-cli/references/element-attributes.md

@@ -0,0 +1,23 @@
+# Inspecting Element Attributes
+
+When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
+
+## Examples
+
+```bash
+playwright-cli snapshot
+# snapshot shows a button as e7 but doesn't reveal its id or data attributes
+
+# get the element's id
+playwright-cli eval "el => el.id" e7
+
+# get all CSS classes
+playwright-cli eval "el => el.className" e7
+
+# get a specific attribute
+playwright-cli eval "el => el.getAttribute('data-testid')" e7
+playwright-cli eval "el => el.getAttribute('aria-label')" e7
+
+# get a computed style property
+playwright-cli eval "el => getComputedStyle(el).display" e7
+```

package/skills/playwright-cli/references/playwright-tests.md

@@ -0,0 +1,39 @@
+# Running Playwright Tests
+
+To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.
+
+```bash
+# Run all tests
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+
+# Run all tests through a custom npm script
+PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
+```
+
+# Debugging Playwright Tests
+
+To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
+
+**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
+
+Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
+
+```bash
+# Run the test
+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
+# ...
+# ... debugging instructions for "tw-abcdef" session ...
+# ...
+
+# Attach to the test
+playwright-cli attach tw-abcdef
+```
+
+Keep the test running in the background while you explore and look for a fix.
+The test is paused at the start, so you should step over or pause at a particular location
+where the problem is most likely to be.
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
+
+After fixing the test, stop the background test run. Rerun to check that test passes.

package/skills/playwright-cli/references/request-mocking.md

@@ -0,0 +1,87 @@
+# Request Mocking
+
+Intercept, mock, modify, and block network requests.
+
+## CLI Route Commands
+
+```bash
+# Mock with custom status
+playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+playwright-cli route-list
+
+# Remove a route or all routes
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+## URL Patterns
+
+```
+**/api/users           - Exact path match
+**/api/*/details       - Wildcard in path
+**/*.{png,jpg,jpeg}    - Match file extensions
+**/search?q=*          - Match query parameters
+```
+
+## Advanced Mocking with run-code
+
+For conditional responses, request body inspection, response modification, or delays:
+
+### Conditional Response Based on Request
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/login', route => {
+    const body = route.request().postDataJSON();
+    if (body.username === 'admin') {
+      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
+    } else {
+      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
+    }
+  });
+}"
+```
+
+### Modify Real Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/user', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    json.isPremium = true;
+    await route.fulfill({ response, json });
+  });
+}"
+```
+
+### Simulate Network Failures
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/slow', async route => {
+    await new Promise(r => setTimeout(r, 3000));
+    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
+  });
+}"
+```

package/skills/playwright-cli/references/running-code.md

@@ -0,0 +1,241 @@
+# Running Custom Playwright Code
+
+Use `run-code` to execute arbitrary Playwright code for advanced scenarios not covered by CLI commands.
+
+## Syntax
+
+```bash
+playwright-cli run-code "async page => {
+  // Your Playwright code here
+  // Access page.context() for browser context operations
+}"
+```
+
+You can also load the function from a file:
+
+```bash
+playwright-cli run-code --filename=./my-script.js
+```
+
+
+The code must be a single function expression, it is wrapped in `(...)` and evaluated.
+import/export/require syntax is not supported.
+
+## Geolocation
+
+```bash
+# Grant geolocation permission and set location
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
+}"
+
+# Set location to London
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
+}"
+
+# Clear geolocation override
+playwright-cli run-code "async page => {
+  await page.context().clearPermissions();
+}"
+```
+
+## Permissions
+
+```bash
+# Grant multiple permissions
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions([
+    'geolocation',
+    'notifications',
+    'camera',
+    'microphone'
+  ]);
+}"
+
+# Grant permissions for specific origin
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read'], {
+    origin: 'https://example.com'
+  });
+}"
+```
+
+## Media Emulation
+
+```bash
+# Emulate dark color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+}"
+
+# Emulate light color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'light' });
+}"
+
+# Emulate reduced motion
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+}"
+
+# Emulate print media
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ media: 'print' });
+}"
+```
+
+## Wait Strategies
+
+```bash
+# Wait for network idle
+playwright-cli run-code "async page => {
+  await page.waitForLoadState('networkidle');
+}"
+
+# Wait for specific element
+playwright-cli run-code "async page => {
+  await page.locator('.loading').waitFor({ state: 'hidden' });
+}"
+
+# Wait for function to return true
+playwright-cli run-code "async page => {
+  await page.waitForFunction(() => window.appReady === true);
+}"
+
+# Wait with timeout
+playwright-cli run-code "async page => {
+  await page.locator('.result').waitFor({ timeout: 10000 });
+}"
+```
+
+## Frames and Iframes
+
+```bash
+# Work with iframe
+playwright-cli run-code "async page => {
+  const frame = page.locator('iframe#my-iframe').contentFrame();
+  await frame.locator('button').click();
+}"
+
+# Get all frames
+playwright-cli run-code "async page => {
+  const frames = page.frames();
+  return frames.map(f => f.url());
+}"
+```
+
+## File Downloads
+
+```bash
+# Handle file download
+playwright-cli run-code "async page => {
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('link', { name: 'Download' }).click();
+  const download = await downloadPromise;
+  await download.saveAs('./downloaded-file.pdf');
+  return download.suggestedFilename();
+}"
+```
+
+## Clipboard
+
+```bash
+# Read clipboard (requires permission)
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read']);
+  return await page.evaluate(() => navigator.clipboard.readText());
+}"
+
+# Write to clipboard
+playwright-cli run-code "async page => {
+  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
+}"
+```
+
+## Page Information
+
+```bash
+# Get page title
+playwright-cli run-code "async page => {
+  return await page.title();
+}"
+
+# Get current URL
+playwright-cli run-code "async page => {
+  return page.url();
+}"
+
+# Get page content
+playwright-cli run-code "async page => {
+  return await page.content();
+}"
+
+# Get viewport size
+playwright-cli run-code "async page => {
+  return page.viewportSize();
+}"
+```
+
+## JavaScript Execution
+
+```bash
+# Execute JavaScript and return result
+playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    return {
+      userAgent: navigator.userAgent,
+      language: navigator.language,
+      cookiesEnabled: navigator.cookieEnabled
+    };
+  });
+}"
+
+# Pass arguments to evaluate
+playwright-cli run-code "async page => {
+  const multiplier = 5;
+  return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
+}"
+```
+
+## Error Handling
+
+```bash
+# Try-catch in run-code
+playwright-cli run-code "async page => {
+  try {
+    await page.getByRole('button', { name: 'Submit' }).click({ timeout: 1000 });
+    return 'clicked';
+  } catch (e) {
+    return 'element not found';
+  }
+}"
+```
+
+## Complex Workflows
+
+```bash
+# Login and save state
+playwright-cli run-code "async page => {
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('secret');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: 'auth.json' });
+  return 'Login successful';
+}"
+
+# Scrape data from multiple pages
+playwright-cli run-code "async page => {
+  const results = [];
+  for (let i = 1; i <= 3; i++) {
+    await page.goto(\`https://example.com/page/\${i}\`);
+    const items = await page.locator('.item').allTextContents();
+    results.push(...items);
+  }
+  return results;
+}"
+```