@tea-agent/loop-agent 0.41.1-beta.0 → 0.42.0-next.1

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

@@ -0,0 +1,31 @@
+# Frontend Node Contracts
+
+Pre-write nodes are read-only. Preserve IDs, labels, commands, language, required headings.
+
+## Core nodes
+
+- **`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. Search+read `openspec/schemas/`, `openspec/project-specs/`, `ai_workspace/` first. Output stack, styling, conventions, state/data, test entry points, reuse, risks.
+- **`frontend-plan-pi` + conditional design loop**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; include steps, in-bound files, UI states, reuse, deps, Mock/API, frozen verify entrypoints and integration gaps. DAG freezes a protected skeleton (`schemaVersion`, `sourceBinding`, `riskLevel`, `targets.files`, `mockApi.productionDefaultOff`). Model returns a **JSON-only** editable RFC 7386 patch (`frontend-implementation-contract-plan-patch-v1`) plus one `openspec-citations` block. Runtime compiles canonical `frontend-implementation-contract-v1` and archives raw/extracted/normalized/validation candidates; unresolved optional symbols are dropped and audited. No plan prose; gate renders plan.md. IDs+paths ≠ behavior semantics. Applicable UI states need behavior/implementation/verification; non-applicable states need reasons. Active Mock needs frozen commands; `auto` without confirmed capability/command → `not-needed`; `required` without command → generation-time blocked. Only `request-revision` runs revision+final review; small-risk gets one review.
+  - `uiComponentChoices[]` (optional): `{purpose, component, decision, specReference, rationale}`; `specified` needs `specReference{path,section,line}`; `new` needs null ref+rationale.
+- **`frontend-prewrite-gate-shell`**: sole write authorization. Resolve effective plan (revised if revision ran, else original) + review; require exact pass; retain every REQ/BR/AC id; enforce Mock policy; validate schema/source binding+writeSet containment; materialize `contracts/frontend-implementation-contract.json` from the **single** fenced contract block (multiple candidates fail closed `invalid-output`). Fallback only when conditional primary absent; malformed primary fails closed. Generation-time blocked Mock yields one blocking shell node, no writer.
+  - `verificationTarget.commandLabel` must be a **frozen command label** from `verifyEvidence.commandLabels`; others fail closed (`invalid-output`). Empty frozen set (no `run.json`) skips check.
+  - `mockApi.strategy !== "not-needed"` fails closed when `mockCommandLabels` empty (`no authorized Mock verification commands`).
+  - OpenSpec policy: `task.json.frontendOpenspec.policy` (default `cited`); candidates = `requiredReadPaths` ∪ task-source citations; effective plan must append one fenced `openspec-citations` block (one JSON `{"path","section","line"}` per line). Candidates non-empty but block missing/unparseable → `openspec-citation-block-unparseable`; candidate not cited → `openspec-not-cited`; cited path without read event → `openspec-citation-not-read` (anti-fabrication). Empty candidates skip enforcement. `scan-strict` keeps full-read semantics (`openspec-not-read`); both modes keep `candidate-missing-drift`.
+  - Component conformance: missing `uiComponentChoices` (frozen bucket non-empty + UI-visible work) → `component-choices-missing`; bad/uncited `specReference.path` → `component-spec-reference-invalid` / `component-spec-not-cited`.
+  - revisionPatch mode: revision output is an RFC 7386 merge-patch delta applied on the original canonical contract node (`planFallbackFromNodeIds[0]`); protected skeleton paths remain immutable. Legacy DAGs keep full-contract semantics. Size guard: canonical serialization >64KB → `retryable-invalid` + `contract-too-large`.
+- **`frontend-implement-pi`**: sole regular exclusive writer; uses `frontend-bounded-implement` (not this skill). Stay in `writeSet`; real requests default-on. Atomic handler/intercept/adapter with tests. Stop on forbidden paths/guesses. First line `IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked`; runtime checks against attributed diff. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. `not-needed` keeps real integration pending unless real backend has fresh evidence.
+
+## Contract / trace / stages (M1–M2)
+
+- `frontend-verify-assess-shell` runs Mock/static/behavior groups, binds `verificationTargets` to command labels+evidence, writes `frontend-verification-trace.json`+`frontend-repair-assessment.json`; browser/visual stay `not-run`.
+- `frontend-review-context-shell` captures real diff; combines contract, effective trace, repair assessment, 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)
+
+Only `eligible=true` runs `frontend-repair-pi` (same writeSet; no re-spec; max 1 attempt) + `frontend-reverify-shell`. No-failure 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. Standard/high-risk: 15 top-level nodes; small: 13 (omits revision + final review). Capability seed injects adapters; openspec specs and task sources outrank adapter guidance. A11y: static/component tools only when present; Browser a11y always not-run.

package/skills/frontend-review/SKILL.md

@@ -9,25 +9,17 @@ references:
 
 # Frontend Review
 
-Use for `frontend-review-pi`; read the findings guide and capacity diagnostic first.
-Inputs are `contracts/frontend-review-context.json`, its hash-bound contract
-reference/index and diff fragments, and only source files named by that diff. Use
-indexed contract sections when recommended. Do not reopen task sources, plans,
-design-review prose, OpenSpec, or `ai_workspace/`; the bound context is authoritative.
+Use for `frontend-review-pi`; read the findings guide first. Required inputs are
+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 verification trace, repair assessment, optional
+`frontend-lint-assessment-v1`, and run-owned diff. The diff is authoritative.
 
-## Authoritative Terminal
+## Verdict Contract
 
-Complete the review with exactly one committed typed tool call:
-
-- `approve_review` when no Critical/Important finding remains;
-- `request_review_changes` for a defect, missing required evidence, forbidden
-  write, or unmet acceptance criterion. It must include a typed `issueCategory`,
-  at least one `evidenceRef`, and non-empty findings.
-
-The typed terminal is the only authoritative outcome. Do not require or emit a
-`VERDICT:` line or response-text JSON verdict. A request for review changes ends
-this run and is handled by the recovery controller rather than a same-run repair
-branch.
+The first non-empty line must be exactly `VERDICT: pass` or
+`VERDICT: request-revision`. Any Critical/Important finding, failed or missing
+required check, forbidden write, or unmet acceptance criterion forces revision.
 
 ## Review Scope
 
@@ -35,7 +27,7 @@ branch.
 - Inspect every changed file against allowed, forbidden, and approved write scope.
 - Map criteria to behavior, applicable UI states, tests, and shell evidence.
 - Review state/data flow, validation, async/error behavior, design, responsive/a11y,
-  dependencies, and regression risk when applicable.
+  dependencies, maintenance, and regression risk when applicable.
 - Inspect static, behavior, and available Mock-specific artifacts directly. For Mock
   strategies, compare the endpoint matrix, handler/fixture/adapter and consumer diff;
   require the real request as default, contract-aligned fixtures, production isolation,
@@ -46,8 +38,11 @@ branch.
   baseline-matched diagnostics on unchanged files, and none on writer-changed files.
   Report debt, never `lint passed`; `failed`/`unavailable` blocks. Typecheck, build,
   and test still require successful final exits.
-- Evaluate component/design claims against bound evidence; do not replace it with a
-  repository-wide search or connector query.
+- Component/design claims need both knowledge-base and local openspec evidence. Query
+  the connector when available and always read task-relevant files under
+  `<repoRoot>/openspec/schemas/`, `<repoRoot>/openspec/project-specs/`, and `<repoRoot>/ai_workspace/`.
+  Connector format is TODO; never invent evidence. Only successful `read` calls are
+  observable as "已读取规范文件".
 - Treat shell exit status as authoritative. Do not edit files.
 
 ## Evidence And Output

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

@@ -14,23 +14,24 @@
   `baseline-debt` only with a valid `frontend-lint-assessment-v1`; this is not a
   passed lint result. A changed-file lint diagnostic, new unmatched diagnostic,
   command drift, missing baseline, timeout, or unparseable output is Important.
-- Treat the design evidence already bound in the canonical review context as the
-  source of truth. Do not launch a connector query or repository-wide OpenSpec/
-  `ai_workspace` search to replace frozen evidence; label a missing bound evidence
-  reference accurately instead.
+- Treat knowledge base, `openspec/schemas/`, `openspec/project-specs/`, and `ai_workspace/` as
+  parallel sources. Record connector/query/source/time plus openspec search terms and
+  matched paths/headings; label fallback or unavailable accurately.
 
 ## Review Sequence
 
 1. Establish changed-file inventory and write boundaries.
-2. Compare the bound contract with the approved constraints and cumulative diff.
+2. Compare original requirement with derived contract/constraints.
 3. Map each criterion to code, states, tests, and evidence.
 4. Inspect interactions, state/data/API behavior, failure paths, and regressions.
 5. Check mock selection, contract-to-fixture mapping, activation/default path,
    handler/fixture/adapter and consumer diff, verification, production imports, and
    the real-integration gap.
-6. Check bound design evidence, responsive/a11y behavior, dependencies, and maintenance.
+6. Check design evidence, responsive/a11y behavior, dependencies, and maintenance.
 7. Classify findings and derive the verdict mechanically.
 
+Skipping either directory is Important when design compliance affects acceptance.
+
 ```text
 - [Critical|Important|Minor] path:line — Problem; impact; required correction; evidence.
 ```

package/skills/frontend-verification/SKILL.md

@@ -30,7 +30,7 @@ verdict/findings, and required browser, visual, manual, or knowledge evidence.
   `frontend-lint-assessment-v1` proving only pre-writer diagnostics on unchanged
   files. Report debt count, changed files, and raw evidence. Typecheck/build/test do
   not support debt.
-- Use design and requirement evidence referenced and hash-bound by
+- Use design and requirement evidence already bound inside
   `contracts/frontend-review-context.json`. Closeout must not query connectors,
   re-open task sources, OpenSpec, AI workspace, upstream model prose, or start new
   repository research.

package/skills/loop-agent/references/command-reference.md

@@ -347,8 +347,13 @@ loop-agent dag reconcile-run --run-id <run-id> --action abandon --reason "..."
 loop-agent dag request-interrupt --run-id <run-id> --request-id <id> --target-operation-id <id> --reason-code <code> --reason <detail> [--json]  # 协作中止：写入 interrupt.json（identity CAS）；需配 --expected-runner-pid/--expected-runner-hostname 校验 runner 身份
 loop-agent dag rerun --run-id <run-id> --from-node <node-id> --plan [--json]  # 从节点重跑资格预检（不执行）
 loop-agent dag rerun --run-id <run-id> --from-node <node-id> --plan-hash <sha256> --request-id <key> --reason "..." [--json]  # 安全子图 continuation
+loop-agent dag context show --run-id <run-id> --node-id <node-id> --attempt <n> --json  # 有界 effective-context 摘要
+loop-agent dag context export --run-id <run-id> --node-id <node-id> --attempt <n> --target <generic|pi-session|pi-handoff|readable> --output <bundle.zip>  # 默认 redacted；raw 另需显式确认
+loop-agent dag artifact consumers --run-id <run-id> --node-id <producer> --artifact <relative-path> --json  # 只读 frozen binding consumer
+loop-agent dag artifact revision stage --run-id <run-id> --node-id <producer> --artifact <relative-path> --file <replacement> --request-id <key> --json  # 暂存 revision，不修改 parent
+loop-agent dag artifact revision discard --revision-id <revision-id> --request-id <key> --json
+loop-agent dag rerun --run-id <run-id> --artifact-revision <revision-id> --plan [--json]  # 单产物影响闭包预检
 loop-agent dag rerun-task --run-id <run-id> --reason "..." --request-id <key> [--profile auto] [--task-id <id>] [--json]  # standalone 完整任务重跑
-loop-agent dag follow-up <parent-run-id> [--task-id <id>] [--execute] [--profile auto|minimal|standard|reviewed|supervised]  # 将 frontend review 的 request_review_changes findings 物化为下游 frontend task；默认只创建并返回 task advance 命令
 loop-agent dag request-interrupt --run-id <run-id> --request-id <key> --target-operation-id <op-id> --reason-code <code> --reason "..." --expected-runner-pid <pid> --expected-runner-hostname <host> --expected-runner-started-at <ts> --expected-controller-fingerprint <fingerprint>  # 协作式中止：经 Human Gate 登记 interrupt.json，runner 等当前节点安全收敛后再停调度，不直接 SIGKILL
 loop-agent dag reconcile-tasks --glob '<pattern>'         # 仅报告的 task/run/artifact/verify drift audit
 loop-agent dag final-verification <task-id>               # 生成 closeout DAG，closeout artifact 后再 final verify

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

@@ -16,7 +16,7 @@
 
 对于默认 `standard` 任务，生成器先读取 `source/需求.md` 中的结构化任务类型，再结合 `allowedPaths` 与 React/Next/Vue 强工程证据做确定性分类。确认是前端项目且任务不是明确后端、前后端混合、排除前端或仅文档/测试范围时，默认选择 `frontend-implementation` DAG，不依赖需求关键词。分类不会把普通后端实现路由到 `backend-test`；显式 profile、`workflowPolicy` 或 supervised quality gate 只记录治理强度，不把已识别的前端业务 workflow 换回通用模板。
 
-前端专用链保留独立 contract/scout；plan 通过增量 typed `record_*` 工具提交决策账本并以唯一 `finalize_plan` 收口（无 fenced JSON 文本协议）。写授权由 `frontend-design-policy-shell`（确定性设计检查 + 物化唯一 authoritative `frontend-implementation-contract-v1`）与 `frontend-writer-admission-shell`（唯一写入授权：派生并冻结 writeSet、pre-writer baseline、admission digest，`admitted` 才放行 writer）承接；design review 与 final review 的权威终态是 committed typed tool（`approve_design|request_design_changes`、`approve_review|request_review_changes`）。实现后 `frontend-verify-shell` 合并 lint/Mock/static/behavior/trace；任何验证失败都是 terminal，物化 `frontend-verify-failure-v1` 供 recovery 路由，无同 run repair。`frontend-review-context-shell` 绑定真实 diff 与有效验证证据后再 review/closeout。拓扑按 shape 路由：Micro 7 / Small 10 / Standard-High 11 个顶层节点；Standard/High 完整主链为 `frontend-contract-pi` → `frontend-scout-pi` → `frontend-plan-pi` → `frontend-design-policy-shell` → `frontend-design-review-pi` → `frontend-writer-admission-shell` → `frontend-implement-pi` → `frontend-verify-shell` → `frontend-review-context-shell` → `frontend-review-pi` → `frontend-closeout-shell`，Small 去掉独立 `frontend-design-review-pi`，Micro 为 `frontend-contract-import-shell` → `frontend-writer-admission-shell` → `frontend-implement-pi` → `frontend-verify-shell` → `frontend-review-context-shell` → `frontend-review-pi` → `frontend-closeout-shell`。生成期 blocked Mock 只生成一个确定性阻塞节点且没有 writer。
+前端专用链保留独立 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 生成中文 README 索引与模块用例卡片并独立 Review `testcase/md/**`。第 4 节点只把前置条件、操作步骤、预期结果作为必选章节，并检查 Case ID、业务 AC、步骤/预期和占位措辞；不校验需求来源引用有效性或 Markdown sensitive-shaped 内容。pytest writer 为每次真实接口调用记录脱敏、有界的请求 method/URL/参数摘要和响应 status/body 摘要。第 6 节点只扫描每条 Case 明确映射的 pytest 脚本，同时支持模块级函数和 pytest class 方法，并把缺少请求/响应日志、递归脱敏或有界截断证据记录为 advisory。第 4/6 节点均写 PASS/FAIL findings 而不阻断后续；pytest 仍只运行一次，生成 JUnit，并把 Markdown 名称/场景/脚本映射与同一 JUnit 合成为按测试概览、质量校验、失败概览、用例执行明细和技术证据组织的中文 self-contained HTML 与 Markdown facts。最终 Pi 按固定简洁结构汇总 advisory 状态、执行事实和 L-5 结论。active 流程不要求模型生成 backend-test 业务 JSON。
 
@@ -91,7 +91,7 @@ loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --init-only --canvas-pat
 - **Source binding / recovery**：新生成 DAG 在顶层冻结 `sourceBinding`（任务源相对路径、SHA-256、显式 `REQ/BR/AC`）。前端计划在存在显式编号时经过 `frontend-requirement-coverage-shell`；修订计划为 primary，只在条件分支未产生输出时 fallback 到原计划。主来源存在但缺号时仍在 writer 前 fail closed。中断后重新生成完整 DAG，不要从二手摘要拼接 impl-only DAG；v3 孤立 exclusive writer 若无 `sourceBinding` 且没有只读 planner 上游，会被 strict governance 拒绝。
 - **勿宣称 live smoke 已通过**，除非真实 `dag execute` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
 
-可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/frontend-implementation-dag.json`（自包含的前端实现完整默认链：contract、scout、plan、design policy/review、writer admission、implement、verify、review context/review、closeout；不依赖 runtime builder 或其他模板，执行前替换全部 `REPLACE/WITH/...` 值）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/frontend-test-dag.json`（FE-test RAG：Markdown case manifest、串行 Playwright CLI case 子节点与逐 case 证据）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
+可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/frontend-test-dag.json`（FE-test RAG：Markdown case manifest、串行 Playwright CLI case 子节点与逐 case 证据）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
 
 ### Supervised implementation flow（减少 operator 中途介入）
 

package/dist/commands/dag-follow-up.js

@@ -1,138 +0,0 @@
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-import { FRONTEND_REVIEW_FINDINGS_PRD_REL, readFrontendReviewFindingsPrd, } from "../workflows/dag/frontend-review-findings.js";
-import { locateDagRun } from "../workflows/dag/lifecycle.js";
-import { createTask, getTaskPaths } from "../task/runtime.js";
-import { importPrdDocument } from "../task/source-references.js";
-function parseFlagValue(rawArgs, flag) {
-    const index = rawArgs.indexOf(flag);
-    if (index < 0 || index + 1 >= rawArgs.length)
-        return undefined;
-    return rawArgs[index + 1];
-}
-export function parseDagFollowUpArgs(rawArgs) {
-    const positional = rawArgs.filter((arg) => !arg.startsWith("-"));
-    const parentRunId = positional[0];
-    if (!parentRunId) {
-        throw new Error("usage: dag follow-up <parent-run-id> [--task-id <id>] [--execute] [--profile <profile>]");
-    }
-    return {
-        parentRunId,
-        taskId: parseFlagValue(rawArgs, "--task-id"),
-        execute: rawArgs.includes("--execute"),
-        profile: parseFlagValue(rawArgs, "--profile"),
-    };
-}
-export function deriveFollowUpTaskId(parentRunId) {
-    // Deterministic, valid task id derived from the parent run id.
-    return `${parentRunId}-followup`;
-}
-/** CLI entry: parse raw args and run the follow-up flow. */
-export async function runDagFollowUp(repoRoot, rawArgs) {
-    const parsed = parseDagFollowUpArgs(rawArgs);
-    const result = await runDagFollowUpInternal(repoRoot, parsed.parentRunId, {
-        taskId: parsed.taskId,
-        execute: parsed.execute,
-        profile: parsed.profile,
-    });
-    console.log(JSON.stringify(result, null, 2));
-    if (!result.ok) {
-        process.exitCode = result.mode === "blocked" ? 2 : 1;
-    }
-}
-export async function runDagFollowUpInternal(repoRoot, parentRunId, options = {}) {
-    const located = await locateDagRun(repoRoot, parentRunId);
-    if (!located) {
-        return {
-            ok: false,
-            mode: "invalid",
-            reason: `dag run not found: ${parentRunId}`,
-        };
-    }
-    const prd = await readFrontendReviewFindingsPrd(located.runDir);
-    if (!prd) {
-        return {
-            ok: false,
-            mode: "invalid",
-            reason: `no frontend review findings PRD found in run ${parentRunId} (${FRONTEND_REVIEW_FINDINGS_PRD_REL}); the review must have committed request_review_changes`,
-        };
-    }
-    const taskId = options.taskId ?? deriveFollowUpTaskId(parentRunId);
-    try {
-        await createTask(repoRoot, taskId, `修复 review 发现（parent ${parentRunId}）`);
-    }
-    catch (error) {
-        return {
-            ok: false,
-            mode: "blocked",
-            reason: `failed to create task ${taskId}: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-    // Materialize the PRD draft into the task's source directory so the task
-    // lifecycle can import it as its requirement.
-    const prdMaterialized = path.join(getTaskPaths(repoRoot, taskId).sourceDir, "review-findings-prd.md");
-    try {
-        await mkdir(path.dirname(prdMaterialized), { recursive: true });
-        await importPrdDocument({
-            repoRoot,
-            taskId,
-            filePath: path.join(located.runDir, FRONTEND_REVIEW_FINDINGS_PRD_REL),
-            name: "review-findings-prd",
-        });
-    }
-    catch (error) {
-        return {
-            ok: false,
-            mode: "blocked",
-            reason: `failed to import PRD into task ${taskId}: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-    if (!options.execute) {
-        return {
-            ok: true,
-            mode: "created",
-            taskId,
-            prdPath: prdMaterialized,
-            next: {
-                kind: "advance",
-                command: `loop-agent task advance ${taskId} --task-kind frontend-implementation --json`,
-            },
-        };
-    }
-    // Execute: advance through the frontend DAG.
-    const { advanceTaskLifecycle } = await import("../application/task-lifecycle/advance.js");
-    const profile = options.profile === "auto" ||
-        options.profile === "minimal" ||
-        options.profile === "standard" ||
-        options.profile === "reviewed" ||
-        options.profile === "supervised"
-        ? options.profile
-        : undefined;
-    const result = await advanceTaskLifecycle({
-        repoRoot,
-        taskId,
-        taskKind: "frontend-implementation",
-        taskKindExplicit: true,
-        ...(profile ? { profile, profileExplicit: true } : {}),
-        observer: undefined,
-    });
-    const ok = result.lifecycleState === "run-succeeded" ||
-        result.lifecycleState === "awaiting-write-set-approval";
-    return {
-        ok,
-        mode: ok ? "created" : "blocked",
-        taskId,
-        prdPath: prdMaterialized,
-        reason: ok
-            ? undefined
-            : `advance lifecycleState: ${result.lifecycleState}${result.blockers.length > 0
-                ? `; blockers: ${result.blockers.map((b) => b.code).join(", ")}`
-                : ""}`,
-        next: ok
-            ? undefined
-            : {
-                kind: "advance",
-                command: `loop-agent task advance ${taskId} --task-kind frontend-implementation --json`,
-            },
-    };
-}

package/dist/executors/pi-read-budget-policy.js

@@ -1,239 +0,0 @@
-import { access, open, readFile, stat, } from "node:fs/promises";
-import path from "node:path";
-class PiReadBudgetSoftLimitError extends Error {
-}
-class PiReadAccessDeniedError extends Error {
-}
-class PiReadBudgetGuard {
-    budget;
-    files = new Set();
-    violations = [];
-    bytes = 0;
-    operations = 0;
-    startedAt = Date.now();
-    allowedReadPaths;
-    allowedReadRoots;
-    constructor(budget, readAccess) {
-        this.budget = budget;
-        this.allowedReadPaths = readAccess?.allowedReadPaths
-            ? new Set(readAccess.allowedReadPaths.map((candidate) => path.resolve(candidate)))
-            : undefined;
-        this.allowedReadRoots = (readAccess?.allowedReadRoots ?? []).map((candidate) => path.resolve(candidate));
-    }
-    issues() {
-        return [...this.violations];
-    }
-    report(message) {
-        if (!this.violations.includes(message))
-            this.violations.push(message);
-    }
-    exhaust(message) {
-        if (this.budget.onExhaustion === "return-guidance") {
-            throw new PiReadBudgetSoftLimitError(message);
-        }
-        this.report(message);
-        throw new Error(message);
-    }
-    assertElapsed() {
-        if (this.budget.maxMs === undefined)
-            return;
-        const elapsedMs = Date.now() - this.startedAt;
-        if (elapsedMs > this.budget.maxMs) {
-            const message = `read budget exhausted: ${elapsedMs}ms (budget ${this.budget.maxMs}ms)`;
-            this.exhaust(message);
-        }
-    }
-    beforeToolOperation() {
-        this.assertElapsed();
-        if (this.budget.maxOperations === undefined)
-            return true;
-        if (this.operations >= this.budget.maxOperations) {
-            const message = `read budget exhausted: operation ${this.operations + 1} would exceed ${this.budget.maxOperations} read-only tool calls`;
-            if (this.budget.onExhaustion === "return-guidance")
-                return false;
-            this.exhaust(message);
-        }
-        this.operations += 1;
-        return true;
-    }
-    operationLimitGuidance() {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "[read limit reached: no repository data was read. Do not call discovery tools again; use injected facts, commit remaining record_* facts, then call finalize_plan exactly once.]",
-                },
-            ],
-        };
-    }
-    readAccessGuidance() {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "[read denied: this node may read only named upstream artifacts or Scout-confirmed paths. Do not explore a new repository path; use committed facts or record an evidence gap, then finish the required terminal protocol.]",
-                },
-            ],
-        };
-    }
-    assertReadablePath(absolutePath) {
-        if (!this.allowedReadPaths)
-            return;
-        const resolved = path.resolve(absolutePath);
-        if (this.allowedReadPaths.has(resolved))
-            return;
-        if (this.allowedReadRoots.some((root) => resolved === root || resolved.startsWith(`${root}${path.sep}`)))
-            return;
-        throw new PiReadAccessDeniedError(`read access denied: ${resolved}`);
-    }
-    reserveFile(absolutePath) {
-        this.assertElapsed();
-        if (this.files.has(absolutePath))
-            return;
-        if (this.files.size >= this.budget.maxFiles) {
-            const message = `read budget exhausted: file ${absolutePath} would exceed ${this.budget.maxFiles} files`;
-            this.exhaust(message);
-        }
-        this.files.add(absolutePath);
-    }
-    reserveBytes(bytes) {
-        this.assertElapsed();
-        const remaining = Math.max(0, this.budget.maxBytes - this.bytes);
-        if (remaining === 0) {
-            const message = `read budget exhausted: ${this.bytes} bytes (budget ${this.budget.maxBytes})`;
-            this.exhaust(message);
-        }
-        const granted = Math.min(bytes, remaining);
-        if (granted < bytes && this.budget.onExhaustion === "return-guidance") {
-            this.exhaust(`read budget exhausted: ${bytes} requested bytes would exceed ${this.budget.maxBytes} bytes`);
-        }
-        this.bytes += granted;
-        if (granted < bytes) {
-            this.report(`read budget truncated: ${bytes} requested bytes at ${this.bytes}/${this.budget.maxBytes} bytes`);
-        }
-        return granted;
-    }
-    async readFile(absolutePath) {
-        this.assertReadablePath(absolutePath);
-        this.reserveFile(absolutePath);
-        const metadata = await stat(absolutePath);
-        const granted = this.reserveBytes(metadata.size);
-        if (granted === metadata.size)
-            return await readFile(absolutePath);
-        const handle = await open(absolutePath, "r");
-        try {
-            const buffer = Buffer.allocUnsafe(granted);
-            const { bytesRead } = await handle.read(buffer, 0, granted, 0);
-            return buffer.subarray(0, bytesRead);
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    async access(absolutePath) {
-        this.assertReadablePath(absolutePath);
-        this.reserveFile(absolutePath);
-        await access(absolutePath);
-    }
-    limitToolResult(result) {
-        if (!result || typeof result !== "object" || !Array.isArray(result.content)) {
-            return result;
-        }
-        const content = result.content.map((item) => {
-            if (!item || item.type !== "text" || typeof item.text !== "string") {
-                this.report("read budget truncated: non-text tool result omitted");
-                return {
-                    type: "text",
-                    text: "[read budget reached: non-text result omitted]",
-                };
-            }
-            const granted = this.reserveBytes(Buffer.byteLength(item.text));
-            return {
-                ...item,
-                text: truncateUtf8(item.text, granted),
-            };
-        });
-        return { ...result, content };
-    }
-}
-function truncateUtf8(text, maxBytes) {
-    if (Buffer.byteLength(text) <= maxBytes)
-        return text;
-    const marker = "\n[read result truncated by node budget]";
-    const markerBytes = Buffer.byteLength(marker);
-    if (maxBytes <= markerBytes)
-        return truncateUtf8Prefix(marker, maxBytes);
-    const contentBudget = maxBytes - markerBytes;
-    return `${truncateUtf8Prefix(text, contentBudget)}${marker}`;
-}
-function truncateUtf8Prefix(text, maxBytes) {
-    let result = "";
-    let bytes = 0;
-    for (const codePoint of text) {
-        const size = Buffer.byteLength(codePoint);
-        if (bytes + size > maxBytes)
-            break;
-        result += codePoint;
-        bytes += size;
-    }
-    return result;
-}
-function wrapTool(definition, guard, consumeResult) {
-    return {
-        ...definition,
-        async execute(...args) {
-            try {
-                if (!guard.beforeToolOperation())
-                    return guard.operationLimitGuidance();
-                const result = await definition.execute(...args);
-                return consumeResult ? guard.limitToolResult(result) : result;
-            }
-            catch (error) {
-                if (error instanceof PiReadBudgetSoftLimitError) {
-                    return guard.operationLimitGuidance();
-                }
-                if (error instanceof PiReadAccessDeniedError) {
-                    return guard.readAccessGuidance();
-                }
-                throw error;
-            }
-        },
-    };
-}
-/**
- * Override Pi's built-in read-only tools with SDK definitions that meter the
- * content before it reaches the model. The read tool caps filesystem bytes at
- * the operation boundary; grep/find/ls have their returned payload clipped
- * before the agent receives it. This is SDK-only by design: the CLI backend
- * cannot inject same-name built-in overrides safely.
- */
-export async function createPiReadBudgetCustomTools(input) {
-    const sdk = (await import("@earendil-works/pi-coding-agent"));
-    const createReadToolDefinition = sdk.createReadToolDefinition;
-    const createGrepToolDefinition = sdk.createGrepToolDefinition;
-    const createFindToolDefinition = sdk.createFindToolDefinition;
-    const createLsToolDefinition = sdk.createLsToolDefinition;
-    if (typeof createReadToolDefinition !== "function" ||
-        typeof createGrepToolDefinition !== "function" ||
-        typeof createFindToolDefinition !== "function" ||
-        typeof createLsToolDefinition !== "function") {
-        throw new Error("pi read budget policy unavailable: SDK read/grep/find/ls tool factories missing");
-    }
-    const guard = new PiReadBudgetGuard(input.budget, input.readAccess);
-    const read = wrapTool(createReadToolDefinition(input.repoRoot, {
-        operations: {
-            readFile: (absolutePath) => guard.readFile(absolutePath),
-            access: (absolutePath) => guard.access(absolutePath),
-        },
-    }), guard, false);
-    const grep = wrapTool(createGrepToolDefinition(input.repoRoot), guard, true);
-    const find = wrapTool(createFindToolDefinition(input.repoRoot), guard, true);
-    const ls = wrapTool(createLsToolDefinition(input.repoRoot), guard, true);
-    if (read.name !== "read" ||
-        grep.name !== "grep" ||
-        find.name !== "find" ||
-        ls.name !== "ls") {
-        throw new Error("pi read budget policy unavailable: SDK tool name mismatch");
-    }
-    return { customTools: [read, grep, find, ls], issues: () => guard.issues() };
-}

package/dist/worker/console/frontend-human-decision-adapter.js

@@ -1,19 +0,0 @@
-import { parseFrontendHumanDecisionProjection } from "../../workflows/dag/frontend-human-decision.js";
-/** Worker/Console persistence seam. Canonical validation and freshness remain in the workflow service. */
-export function createFrontendHumanDecisionAdapter(store) {
-    return {
-        async load(operationId) {
-            const record = await store.get(operationId);
-            if (!record || record.revision === undefined || !record.frontendHumanDecision)
-                return undefined;
-            return { revision: record.revision, projection: parseFrontendHumanDecisionProjection(record.frontendHumanDecision) };
-        },
-        materialize(input) {
-            return store.materializeFrontendHumanDecision(input);
-        },
-        consume(input) {
-            return store.consumeFrontendHumanDecision(input);
-        },
-        initializeSplit: store.initializeFrontendHumanApprovedSplit.bind(store),
-    };
-}

package/dist/worker/console/frontend-split-operation-adapter.js

@@ -1,20 +0,0 @@
-import { FrontendSplitOrchestrator, frontendSplitProjectionSchema, } from "../../workflows/dag/frontend-split-application-service.js";
-/** Worker/Console boundary adapter. All orchestration policy remains canonical. */
-export function createFrontendSplitOperationAdapter(dependencies) {
-    const ports = {
-        load: async (operationId) => {
-            const record = await dependencies.store.get(operationId);
-            return record?.frontendSplit === undefined ? undefined : frontendSplitProjectionSchema.parse(record.frontendSplit);
-        },
-        compareAndSwap: (input) => dependencies.store.compareAndSwapFrontendSplit(input),
-        materialize: async (request) => {
-            const result = await dependencies.materializer.materialize(request);
-            return { taskId: result.taskId, operationId: result.operationId };
-        },
-        schedule: dependencies.schedule,
-        auditStale: dependencies.auditStale,
-        loadChildCloseoutFacts: (input) => dependencies.store.loadChildCloseoutFacts(input),
-        settleAggregate: (input) => dependencies.store.settleFrontendSplitAggregate({ ...input, prepareAggregate: dependencies.prepareAggregate }),
-    };
-    return new FrontendSplitOrchestrator(ports);
-}