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

package/skills/frontend-implementation/references/design-spec.md

@@ -2,14 +2,22 @@
 
 ## Required Source Sequence
 
-1. Attempt the configured component/design knowledge-base query first.
-2. If unavailable, failed, timed out, or unmatched, recursively search the project root's exact `openspec/` directory.
-3. Treat relevant matches as the current project's specification for this run.
-4. Only then use component source, tokens, stories, tests, and pages as non-normative repository fallback.
-
-Never skip `openspec/` directly to neighboring-code conventions. Report source
-conflicts instead of combining them. Explicit task requirements remain the contract;
-flag conflicts with knowledge-base or `openspec/` rules.
+Knowledge base and `openspec/` are parallel specification sources:
+
+1. Attempt the configured component/design knowledge-base query first when a
+   connector is available in the execution environment.
+2. Regardless of knowledge-base success, failure, timeout, no match, or no
+   configuration, also recursively search the project root's exact `openspec/`
+   directory for index files and task-relevant specification content.
+3. Treat relevant matches from both sources as the current project's
+   specification for this run.
+4. Only then use component source, tokens, stories, tests, and pages as
+   non-normative repository fallback.
+
+Never skip `openspec/` directly to neighboring-code conventions, even when a
+knowledge-base query returned results. Report source conflicts instead of
+combining them. Explicit task requirements remain the contract; flag conflicts
+with knowledge-base or `openspec/` rules.
 
 ## Knowledge Base Connection — TODO
 

package/skills/frontend-implementation/references/node-contracts.md

@@ -6,22 +6,20 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
 - **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Knowledge base first; else search+read `<repoRoot>/openspec/**` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-mock-assess-pi` + gate**: declares `firstProtocolLine: "MOCK_STRATEGY:"`; canonical output first line
-  `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
-  Pi output mapping promotes the first explicitly labeled Mock strategy line ahead of any preamble, including common bullet, quote, inline-code, fullwidth-colon, `Mock strategy`, and split label/value drift, without inventing or replacing its value; missing, unlabeled, malformed, or blocked strategies still fail closed. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
-- **`frontend-plan-pi` + conditional design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. Initial `VERDICT: pass` uses the original plan directly. Only exact `VERDICT: request-revision` runs read-only plan revision plus final review; there is no `frontend-first-design-gate-shell` or pass-path `PASS_NO_REVISION_NEEDED` node. The effective final gate prefers final review when present, otherwise initial review, and only exact pass authorizes writes; malformed/missing/request-revision fails closed → replan/rerun (not dev-fix). The plan-pi prompt includes the complete `frontend-implementation-contract-v1` JSON Schema loaded from the loop-agent package `docs/templates/` path, plus deterministic source binding, risk level, and allowed implementation targets. The model does not need to search or guess contract fields; `schemaId`, `targetFiles`, `requirementCoverage` are explicitly forbidden.
+- **`frontend-plan-pi` + conditional design loop**: AC → steps, in-bound files, UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap, and exactly one `frontend-implementation-contract-v1` JSON object. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for a reversible seam. `auto` may select `not-needed` when no project Mock capability exists, while keeping real requests default and recording the gap; `required` cannot. Initial design pass uses the original plan; only exact `request-revision` runs read-only revision plus final review. Small-risk runs one design review only.
+- **`frontend-prewrite-gate-shell`**: the sole write authorization. Resolve effective plan/review, require exact pass, retain every REQ/BR/AC id, enforce Mock policy, validate schema/source binding, and materialize `contracts/frontend-implementation-contract.json`. Fallback is allowed only when a conditional primary is absent; an existing malformed primary fails closed. Generation-time blocked Mock produces one deterministic blocking shell node and no writer.
 - **`frontend-implement-pi`**: sole exclusive writer. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. Skipped-Mock `not-needed` keeps real integration pending unless the real backend path has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)
 
-- Contract shell: `jsonArtifactGate` → `contracts/frontend-implementation-contract.json` from the effective plan (one fenced JSON or pure JSON); schemaId `frontend-implementation-contract-v1`. Revision is primary and original plan is fallback only when the conditional revision output is absent. Requirement coverage uses the same primary/fallback rule. An existing malformed/schema-invalid/incomplete primary fails closed; fallback never masks it. Final design + implement depend on the artifact; `MOCK_STRATEGY: blocked` not implementable.
-- Trace shell: `frontend-verification-trace-gate` binds contract `verificationTargets` to static/behavior records (`commandLabels`, file exists, optional symbol). Assess `MOCK_STRATEGY:` must match `mockApi.strategy` when present. Writes `contracts/frontend-verification-trace.json`. Browser/visual always `not-run`.
+- `frontend-verify-assess-shell` runs Mock/static/behavior command groups, binds contract `verificationTargets` to command labels and file/symbol evidence, then writes `frontend-verification-trace.json` and `frontend-repair-assessment.json`. Browser/visual remain `not-run`.
+- `frontend-review-context-shell` captures the real diff and combines contract, effective trace, repair assessment, and diff into `contracts/frontend-review-context.json`.
 - Implement stages: (1) contract confirm (2) tests sync (3) component/UI (4) API/Mock (5) frozen checks (6) diff cleanup. Summary: Contract Ref, Changed Files, Requirements, UI States, Tests, Verification Attempts, Deviations, Residual Risks.
 
 ## Repair (M3)
 
-static/behavior/trace may `nonZeroExitPolicy: record`. Assess emits pure JSON and writes `contracts/frontend-repair-assessment.json`. Only `eligible=true` runs `frontend-repair-pi` (same writeSet as implement; no re-spec; max 1 attempt), reverify, and retrace. No-failure condition-skips that branch, while diff/review/read-only `frontend-closeout-pi` continue on initial evidence. Repair-contract fails closed on non-repairable (contract/path/dependency/credential/deploy/spec-unclear), writeSet expansion, ERROR, or hard skip; `all-or-condition-skip` never softens those failures.
+Only `eligible=true` runs `frontend-repair-pi` (same writeSet as implement; no re-spec; max 1 attempt) and `frontend-reverify-shell`. No failure condition-skips both. Non-repairable contract/path/dependency/credential/deploy/spec-unclear failures fail closed.
 
 ## Risk & capability (M4–M6)
 
-Deterministic risk (no model); high-risk beats small; supervised never small. Small may drop the initial design review + conditional revision branch; its retained final review audits `frontend-plan-pi`, and contract shell retargets to that plan without fallback. Capability seed injects adapters; openspec/task sources outrank. A11y: static/component tools only when present; Browser a11y always not-run.
+Deterministic risk (no model); high-risk beats small; supervised never small. Standard/high-risk contain 15 top-level nodes; small contains 13 by omitting revision and final review. Capability seed injects adapters; openspec/task sources outrank. A11y: static/component tools only when present; Browser a11y always not-run.

package/skills/frontend-review/SKILL.md

@@ -10,14 +10,11 @@ references:
 # Frontend Review
 
 Use for `frontend-review-pi`; read the findings guide first. Required inputs are
-original task/reference material, contract/constraints, Mock assessment, original and
-revised/confirmed plan, final design verdict, implementation summary, actual diff,
-and static/behavior/optional Mock shell evidence. The actual diff is the run-owned
-`frontend-worktree-diff-shell` artifacts: `contracts/frontend-worktree-diff.json` and
-`artifacts/diff_patch.patch` under the current DAG run directory. When those artifacts
-exist, treat them as the authoritative actual diff—do not request revision solely for
-"missing diff". Only force revision for a missing actual diff when both artifacts are
-absent; never invent a diff from an implementation summary alone.
+original task/reference material, effective plan/design branch, implementation summary,
+and `contracts/frontend-review-context.json`. That canonical context binds the validated
+implementation contract, effective initial-or-post-repair verification trace, repair
+assessment, and run-owned actual diff. Treat its diff as authoritative; never invent a
+diff from an implementation summary alone.
 
 ## Verdict Contract
 
@@ -37,7 +34,13 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
   and no false real-integration claim. `not-needed` needs applicable real/no-remote
   evidence, or an explicit default-auto skipped-Mock rationale with the Real
   Integration Gap preserved when no project Mock capability is confirmed.
-- Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openspec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence. Execute explicit `grep`/`find` to locate spec files and `read` to load them before referencing their rules. Only successful `read` tool calls are observable as "已读取规范文件" in the spec-evidence inspector.
+- Component/design claims require traceable evidence from two parallel sources:
+  knowledge base and `<repoRoot>/openspec/**`. Query the knowledge-base connector
+  when available; regardless of result, also read `<repoRoot>/openspec/**`.
+  The connector format is TODO; never claim a query or fallback search without
+  evidence. Execute explicit `grep`/`find` to locate spec files and `read` to
+  load them before referencing their rules. Only successful `read` tool calls are
+  observable as "已读取规范文件" in the spec-evidence inspector.
 - Treat shell exit status as authoritative. Do not edit files.
 
 ## Evidence And Output

package/skills/frontend-review/references/review-findings.md

@@ -11,7 +11,11 @@
 - Cite tight file locations, exact commands/results, or named DAG artifacts.
 - Never invent evidence; name the missing check. An implementation summary is not the actual diff.
 - Failed required static/behavior verification is at least Important unless proven unrelated.
-- A knowledge-base claim records connector/query, source ID/version, and retrieval time. If absent, failed, or unmatched, review evidence must show `<repoRoot>/openspec/**` search terms and matched paths/headings; label `openspec fallback`, `repository fallback`, or `unavailable` accurately.
+- Treat the knowledge base and `openspec/` as parallel sources. Record
+  connector/query, source ID/version, and retrieval time for knowledge-base
+  claims. Regardless of that result, evidence must show
+  `<repoRoot>/openspec/**` search terms and matched paths/headings; label
+  `openspec`, `repository fallback`, or `unavailable` accurately.
 
 ## Review Sequence
 

package/skills/frontend-verification/SKILL.md

@@ -24,9 +24,11 @@ verdict/findings, and required browser, visual, manual, or knowledge evidence.
 - Mock-backed behavior proves frontend rendering and state transitions only. It never
   proves backend readiness, transport compatibility, or real API integration.
 - Unavailable commands remain gaps.
-- Resolve design evidence via knowledge base, then `<repoRoot>/openspec/**` after
-  failure/no match. Its connector format remains TODO; never invent it. An applied
-  `openspec fallback` is available project evidence.
+- Resolve design evidence from two parallel sources: query the execution environment's
+  knowledge base connector when available; regardless of result, also read
+  `<repoRoot>/openspec/**` for index and task-relevant specification content.
+  The connector format remains TODO; never invent it. Applied `openspec` rules
+  from successful reads are available project evidence.
 - Separate Mock service/handler checks from page consumption and record the
   dev/test-only boundary; handler tests alone do not prove page use.
 

package/skills/frontend-verification/references/verification-checklist.md

@@ -12,8 +12,9 @@
 
 ## Design And Component Evidence
 
-- Claims cite knowledge-base retrieval or `<repoRoot>/openspec/**` fallback.
-- Evidence records query/source/time or fallback search terms, paths, headings, and applied rules.
+- Claims cite two parallel sources: knowledge-base retrieval and
+  `<repoRoot>/openspec/**`.
+- Evidence records query/source/time for knowledge base plus openspec search terms, paths, headings, and applied rules for both.
 - Relevant `openspec/` matches satisfy source availability; missing both sources blocks explicit compliance or required design decisions.
 
 ## Status

package/skills/loop-agent/references/hybrid-dag.md

@@ -16,10 +16,10 @@
 
 对于默认 `standard` 任务，生成器根据标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类。只有高置信的前端实现需求自动选择 `frontend-implementation` DAG；后端、前后端混合、明确排除前端或证据不足的需求继续使用 governance profile 选出的模板。分类不会把普通后端实现路由到 `backend-test`，也不会替换由显式 profile、`workflowPolicy` 或 supervised quality gate 选中的 supervised 模板。
 
-前端专用链在 `frontend-scout-pi` 后加入只读 `frontend-mock-assess-pi` 和确定性 contract gate，根据接口契约、后端就绪度、生成期能力 seed 与固化验证入口选择 `native|browser-intercept|request-adapter|not-needed|blocked`。策略直接传给 plan、条件 design review、唯一 writer、实现 review 和 closeout；真实请求保持默认，缺少契约、生产隔离、注释真实请求或显式 required 合同不完整时 gate 阻塞。standard/full 拓扑的 initial design pass 直接使用 original plan，只有 request-revision 才运行 plan revision 和 final review；small-risk 拓扑保留 final review 作为对 original plan 的单一审查。已删除 `frontend-first-design-gate-shell`，保留的 final gate 只接受生效 initial/final verdict 的 pass。可选 `frontendMock` 配置声明 `auto|required|disabled`、既有服务目录与专项命令；默认 `auto` 下没有已确认 Mock 能力时跳过 Mock 继续实现并保留真实联调缺口，不安全或不完整的显式 required 合同只生成无 writer 的评估链，有可信命令时才增加 `frontend-mock-verify-shell`。Mock-backed 证据只证明前端状态；跳过 Mock 且未调用后端时 closeout 报告 `Frontend status: locally-validated` 与 `Real integration: pending`。初始验证后的 assessment 输出 JSON，只有 `eligible=true` 才运行 repair/reverify/retrace；绿色路径跳过该分支后仍继续 diff/review/只读 `frontend-closeout-pi`，non-repairable 或 `ERROR` 仍硬阻断。
+前端专用链保留独立 contract/scout；plan 同时选择 Mock/API 策略并输出结构化 implementation contract。design initial pass 直接使用原计划，只有 request-revision 才运行 revision/final review；small-risk 只执行一次 design review。`frontend-prewrite-gate-shell` 合并生效 verdict、REQ/BR/AC 覆盖、Mock policy 和 contract 物化，是唯一写入授权。实现后 `frontend-verify-assess-shell` 合并 Mock/static/behavior/trace/assessment；只有 `eligible=true` 才运行同 writeSet 的 repair 和 `frontend-reverify-shell`。`frontend-review-context-shell` 绑定真实 diff 与有效验证证据后再 review/closeout。standard/high-risk 为 15 个顶层节点，small-risk 为 13；绿色路径执行 11 个节点、7 次 Pi。生成期 blocked Mock 只生成一个确定性阻塞节点且没有 writer。
 
 
-> Backend-test Markdown-first：先由确定性环境 Shell 检查 clean env 中 Python/pytest、常见配置、conftest/fixture、test root、server entry 和 HTML renderer，失败时不消耗模型调用。随后 Pi 生成并独立 Review `testcase/md/**`，Shell 校验 Case ID、AC/source traceability、章节、步骤、可断言预期与 secret 安全；pytest writer 仅转换最终 Markdown，不重读 `source/**`。traceability 是执行前唯一资产硬门；pytest 只运行一次，生成 JUnit，并从同一 JUnit 生成 self-contained HTML 与 Markdown facts。最终 Pi 只解释事实并生成 Markdown 报告和 L-5 结论。active 流程不要求模型生成 backend-test 业务 JSON。
+> Backend-test Markdown-first：先由确定性环境 Shell 检查 clean env 中 Python/pytest、常见配置、conftest/fixture、test root、server entry 和 HTML renderer，失败时不消耗模型调用。随后 Pi 生成中文 README 索引与模块用例卡片并独立 Review `testcase/md/**`，Shell 校验 Case ID、AC/source traceability、中文或历史英文分节、步骤、可断言预期与 secret 安全；pytest writer 仅转换最终 Markdown，不重读 `source/**`。traceability 同时支持模块级函数和 pytest 测试类方法；pytest 只运行一次，生成 JUnit，并把 Markdown 名称/场景/脚本映射与同一 JUnit 合成为逐条中文 self-contained HTML 主报告和 Markdown facts。最终 Pi 只解释事实并生成 Markdown 报告和 L-5 结论。active 流程不要求模型生成 backend-test 业务 JSON。
 
 显式专用 `taskKind` 保持兼容并优先于任务源分类。`backend-test` 选择固定 **8 个真实顶层节点**的 Markdown-first DAG：环境硬门、Markdown cases、独立 Review/修订、Markdown gate、pytest 转换、确定性 traceability、单次 pytest + JUnit/HTML/facts、最终 Markdown 报告与 L-5。历史 JSON contract/materializer 可继续读取旧 DAG，但新 runtime/template 不再生成模型业务 JSON。`knowledge-sync` 与 `knowledge-graph-bootstrap` 继续通过各自显式 taskKind 选择知识回写/图谱开荒 DAG。治理等级仍由 `minimal|standard|reviewed|supervised` 推断。