@tea-agent/loop-agent 0.38.1 → 0.39.0-beta.0

package/dist/workflows/dag/rerun-task.js

@@ -3,7 +3,8 @@ import path from "node:path";
 import { generateTaskDagUseCase } from "../../application/dag/generate-task-dag.js";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { DAG_RUNS_DIR, isTerminalDagRunStatus, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
-import { parseDagSpec } from "./types.js";
+import { deriveDagRerunFeedback } from "./rerun-feedback.js";
+import { parseDagSpec, } from "./types.js";
 export const RERUN_TASK_LINEAGE_REL_PATH = ".runtime/rerun-task-lineage.json";
 export function parseDagRerunTaskArgs(args) {
     if (args.length === 0) {
@@ -218,6 +219,7 @@ async function writeRerunTaskLineage(cwd, newRunId, input) {
         parentRunId: input.parentRunId,
         reason: input.reason,
         requestId: input.requestId,
+        feedback: input.feedback,
         createdAt: new Date().toISOString(),
     }, { repoRoot: cwd, allowCompletedFactsWrite: true });
 }
@@ -228,12 +230,30 @@ function blockedResult(input) {
         reason: input.reason,
         requestId: input.requestId,
         mode: "blocked",
+        feedback: input.feedback ?? {
+            inherited: false,
+            reason: "no-unresolved-verify-review-feedback",
+        },
         blockedReason: input.blockedReason,
         ...(input.note ? { note: input.note } : {}),
         ...(input.taskId ? { taskId: input.taskId } : {}),
         ...(input.conflictPaths ? { conflictPaths: input.conflictPaths } : {}),
     };
 }
+async function readGeneratedRerunFeedback(outputPath) {
+    const raw = JSON.parse(await readFile(outputPath, "utf8"));
+    return parseDagSpec(raw).rerunFeedback;
+}
+function summarizeFeedback(feedback, fallbackReason) {
+    return feedback
+        ? {
+            inherited: true,
+            sourceNodeId: feedback.sourceNodeId,
+            digest: feedback.digest,
+            bindingStatus: feedback.binding.status,
+        }
+        : { inherited: false, reason: fallbackReason };
+}
 function extractRunSummary(generateResult) {
     if (generateResult.mode === "generate+basic-validate")
         return undefined;
@@ -277,7 +297,26 @@ export async function rerunStandaloneTask(input) {
             note: eligibility.note,
         });
     }
+    let parentFeedback;
+    let missingFeedbackReason = "no-unresolved-verify-review-feedback";
+    try {
+        parentFeedback = await deriveDagRerunFeedback({
+            parentRunId: input.parentRunId,
+            taskId: taskResolution.taskId,
+            runDir: located.runDir,
+            spec,
+            state,
+        });
+    }
+    catch {
+        // Feedback is additive recovery context. A corrupt/missing historical
+        // artifact must be reported honestly but must not block an otherwise
+        // eligible full rerun.
+        missingFeedbackReason = "feedback-unavailable";
+    }
     const execute = input.execute ?? true;
+    let effectiveFeedback;
+    let expectedRerunFeedbackDigest;
     // AC-001 generated-output-conflict preflight: when a real execution is
     // requested, first generate the DAG draft (execute:false) so we can inspect
     // the regenerated spec's requireChangedFiles writer write sets against
@@ -296,15 +335,23 @@ export async function rerunStandaloneTask(input) {
             dryRun: false,
             profile: input.profile ?? "auto",
             profileExplicit: input.profileExplicit ?? false,
+            rerunFeedback: parentFeedback,
         });
         if (preflight.mode === "generate+basic-validate") {
             let conflictPaths = [];
             try {
                 const raw = await readFile(preflight.outputPath, "utf8");
                 const preflightSpec = parseDagSpec(JSON.parse(raw));
+                effectiveFeedback = preflightSpec.rerunFeedback;
+                expectedRerunFeedbackDigest = effectiveFeedback?.digest;
+                if (parentFeedback && !effectiveFeedback) {
+                    throw new Error("rerun feedback missing from generated preflight DAG");
+                }
                 conflictPaths = await assessGeneratedOutputConflict(preflightSpec, input.cwd);
             }
-            catch {
+            catch (error) {
+                if (parentFeedback)
+                    throw error;
                 // If the draft cannot be parsed, fall through to the real execution
                 // path: execution's own validation will surface the structural defect.
                 conflictPaths = [];
@@ -332,7 +379,17 @@ export async function rerunStandaloneTask(input) {
         dryRun: false,
         profile: input.profile ?? "auto",
         profileExplicit: input.profileExplicit ?? false,
+        rerunFeedback: parentFeedback,
+        expectedRerunFeedbackDigest,
     });
+    if (parentFeedback && !effectiveFeedback) {
+        effectiveFeedback = await readGeneratedRerunFeedback(generateResult.outputPath);
+    }
+    if (expectedRerunFeedbackDigest &&
+        effectiveFeedback?.digest !== expectedRerunFeedbackDigest) {
+        throw new Error(`rerun feedback drift after generation: expected ${expectedRerunFeedbackDigest}, got ${effectiveFeedback?.digest ?? "missing"}`);
+    }
+    const feedbackSummary = summarizeFeedback(effectiveFeedback, missingFeedbackReason);
     const newRunId = extractNewRunId(generateResult);
     const runSummary = extractRunSummary(generateResult);
     const completedSuccessfully = !execute ||
@@ -342,6 +399,7 @@ export async function rerunStandaloneTask(input) {
             parentRunId: input.parentRunId,
             reason: input.reason,
             requestId: input.requestId,
+            feedback: feedbackSummary,
         });
     }
     const result = {
@@ -350,6 +408,7 @@ export async function rerunStandaloneTask(input) {
         reason: input.reason,
         requestId: input.requestId,
         mode: "generate+validate+execute",
+        feedback: feedbackSummary,
         taskId: taskResolution.taskId,
         ...(newRunId ? { newRunId } : {}),
         ...(runSummary && !completedSuccessfully && "status" in runSummary

package/dist/workflows/dag/retry-policy.js

@@ -201,6 +201,24 @@ function isExclusivePiImplementer(task) {
         !task.dynamicCondition &&
         !task.dynamicLoopUntil);
 }
+/**
+ * Provider/transport failure categories that can crash a writer executor
+ * after some workspace writes already landed on disk. A continuation may
+ * restart that writer itself; it must never import or normalize the ERROR fact.
+ */
+export const WRITER_TRANSPORT_FAILURE_CATEGORIES = new Set([
+    "unavailable",
+    "network",
+    "rate-limit",
+    "timeout",
+]);
+export function isTransportCrashedExclusiveWriter(task, failureCategory) {
+    if (!task)
+        return false;
+    return (isExclusivePiImplementer(task) &&
+        failureCategory !== undefined &&
+        WRITER_TRANSPORT_FAILURE_CATEGORIES.has(failureCategory));
+}
 /**
  * Static eligibility for the requireChangedFiles writer-empty-diff class.
  * The Pi executor assigns writer-empty-diff only after post-write-guard

package/dist/workflows/dag/types.js

@@ -423,6 +423,8 @@ export const dagBackendTestPipelineSchema = z.enum([
     "markdown-scenario-param",
     "markdown-execute-html",
     "markdown-manifest",
+    "markdown-report",
+    "ingest-backend-test-gap",
 ]);
 export const dagFrontendBrowserToolPreflightSchema = z.object({}).strict();
 export const dagFrontendTestEvidenceValidationSchema = z.object({}).strict();
@@ -600,6 +602,13 @@ export const dagDynamicExpansionSchema = z.object({
         maxTotalTokens: z.number().int().positive().optional(),
     })
         .optional(),
+    /**
+     * When true, any child blocked by the aggregate token budget fails the map
+     * barrier instead of being retained as a case-level blocked outcome.
+     * Backend-test enables this because partial Markdown/pytest module sets are
+     * invalid generation assets; frontend-test keeps the default false.
+     */
+    failOnTokenBudgetExhaustion: z.boolean().optional(),
     /**
      * When true, map child ERROR/auth/timeout is recorded as case-level
      * failed/blocked evidence and the map barrier still succeeds (frontend-test).
@@ -704,6 +713,7 @@ export const dagConvergenceSpecSchema = z
  */
 export const structuredContractOutputSchemaIds = [
     "frontend-implementation-contract-v1",
+    "frontend-implementation-contract-plan-patch-v1",
     "frontend-implementation-contract-revision-patch-v1",
 ];
 export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
@@ -766,9 +776,32 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
         .object({
         schemaId: z.enum(structuredContractOutputSchemaIds),
         retryOnInvalid: z.boolean().default(true),
+        /**
+         * Optional deterministic base object for patch-producing structured
+         * nodes. The frontend plan patch validator applies the model delta to
+         * this run-owned skeleton before strict contract validation.
+         */
+        skeleton: z.record(z.string(), z.unknown()).optional(),
     })
         .strict()
+        .superRefine((value, ctx) => {
+        if (value.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1" &&
+            !value.skeleton) {
+            ctx.addIssue({
+                code: "custom",
+                message: "frontend plan patch output requires a runtime skeleton",
+                path: ["skeleton"],
+            });
+        }
+    })
         .optional(),
+    /**
+     * Opt-in upstream context mode for nodes that must consume a validated,
+     * hash-bound artifact rather than a potentially truncated text preview.
+     * The default remains preview mode for every existing DAG.
+     */
+    artifactFirstUpstreamNodeIds: z.array(z.string()).optional(),
     /**
      * Fail-closed outcome/diff consistency contract for bounded Pi writers.
      * The writer must begin with IMPLEMENTATION_OUTCOME: changed,
@@ -846,6 +879,55 @@ export const dagSourceBindingSchema = z.object({
         .min(1),
     requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
 });
+const dagRerunFeedbackEvidencePathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => !/^(?:[A-Za-z]:[\\/]|[\\/]{2}|\/)/.test(value), "rerun feedback evidence paths must be repository-relative");
+/**
+ * Bounded unresolved verify/review feedback carried by a full task rerun.
+ * This is recovery context, not a mutation of the original task contract.
+ */
+export const dagRerunFeedbackSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("unresolved-terminal-feedback"),
+    parentRunId: z.string().min(1),
+    taskId: z.string().min(1),
+    sourceNodeId: z.string().min(1),
+    verdict: z.enum(["request-revision", "fail"]).optional(),
+    failureCategory: z.string().min(1).optional(),
+    feedbackText: z.string().min(1).max(12_000),
+    evidenceRefs: z
+        .array(z
+        .object({
+        nodeId: z.string().min(1),
+        preservedNodeRecordPath: dagRerunFeedbackEvidencePathSchema,
+    })
+        .strict())
+        .max(8),
+    attemptSummary: z
+        .object({
+        completedPasses: z.number().int().positive(),
+        maxPasses: z.number().int().positive(),
+        terminalReason: z.string().min(1).optional(),
+    })
+        .strict(),
+    binding: z
+        .object({
+        sourceCanonicalHash: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/)
+            .optional(),
+        taskContractCanonicalHash: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/)
+            .optional(),
+        status: z.enum(["exact", "changed", "unknown"]),
+    })
+        .strict(),
+    digest: z.string().regex(/^[a-f0-9]{64}$/),
+})
+    .strict();
 export const dagSpecSchema = z
     .object({
     version: dagVersionSchema,
@@ -857,6 +939,28 @@ export const dagSpecSchema = z
     sourceBinding: dagSourceBindingSchema.optional(),
     /** v4 managed Task Contract binding; only valid on version 4. */
     taskContractBinding: dagTaskContractBindingSchema.optional(),
+    /** Optional unresolved parent-run feedback for a full task rerun. */
+    rerunFeedback: dagRerunFeedbackSchema.optional(),
+    /** Frozen backend-test artifact layout (plan A); absent = historical default testcase/ layout. */
+    backendTestLayout: z
+        .object({
+        testRoot: z.string(),
+        markdownRel: z.string(),
+        scriptRel: z.string(),
+        markdownDir: z.string(),
+        scriptDir: z.string(),
+        readmePath: z.string(),
+        isDefault: z.boolean(),
+    })
+        .optional(),
+    /** Bound user shared-setup document (plan B); absent = no shared setup references expected. */
+    backendTestSharedSetup: z
+        .object({
+        path: z.string(),
+        readPath: z.string(),
+        sha256: z.string(),
+    })
+        .optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
     successCriteria: z.array(z.string()).optional(),

package/dist/workflows/dag/upstream-artifacts.js

@@ -38,6 +38,10 @@ export function relocateNodeArtifactPaths(node, oldRunDir, newRunDir) {
     node.stdoutArtifactPath = rewrite(node.stdoutArtifactPath);
     node.assistantArtifactPath = rewrite(node.assistantArtifactPath);
     node.structuredArtifactPath = rewrite(node.structuredArtifactPath);
+    if (node.frontendPlanOutput) {
+        node.frontendPlanOutput.citationsArtifactPath = rewrite(node.frontendPlanOutput.citationsArtifactPath);
+        node.frontendPlanOutput.rawCandidatePath = rewrite(node.frontendPlanOutput.rawCandidatePath);
+    }
     node.nodeRecordPath = rewrite(node.nodeRecordPath);
 }
 export function relocateConvergenceArtifactPaths(convergence, oldRunDir, newRunDir) {

package/docs/operations/local-development-environment.md

@@ -29,11 +29,7 @@ Cursor Cloud VM 当前有两个需要特别注意的环境问题。
 
 ### Node.js 版本
 
-VM 默认 `node`（`/exec-daemon/node`）可能是 v22.14.0，但可选依赖 `@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 要求 Node.js `>=22.19.0`。版本过低时，`npm install` / `npm ci` 可能跳过这些依赖，随后 `npm run typecheck` 或 `npm run build` 会报告：
-
-```text
-Cannot find module '@earendil-works/...'
-```
+VM 默认 `node`（`/exec-daemon/node`）可能是 v22.14.0，但根包与运行时依赖 `@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 都要求 Node.js `>=22.19.0`。版本过低时，npm 默认模式会报告 `EBADENGINE` 警告；启用 `engine-strict` 时，`npm install` / `npm ci` 会直接失败。即使默认模式完成安装，也不应在不受支持的 Node.js 版本上继续执行 typecheck、build 或 runtime 命令。
 
 在 Cursor Cloud 中执行安装或验证前，先切换到已配置的 Node.js 22：
 

package/docs/skills/vetted-skill-registry.md

@@ -16,10 +16,22 @@ The entries below are local wrappers or existing local skills. They are not whol
 | `code-review-core` | local wrapper inspired by code review practice | `skills/code-review-core/SKILL.md` | reviewer | reviewer | No external tools or network by default. |
 | `codebase-scout` | local wrapper | `skills/codebase-scout/SKILL.md` | scout | scout | Read-only reconnaissance guidance. |
 | `init-capability-evolution` | local wrapper | `skills/init-capability-evolution/SKILL.md` | supervisor, maintenance | optional | Used only when changes may affect target-project initialization, package surface, or init projection rules. |
+| `frontend-implementation` | local existing (frontend hybrid DAG) | `skills/frontend-implementation/SKILL.md` | frontend plan / contract / scout / mock nodes (spec-level `skillsByRole`) | frontend-implementation DAG only | Required refs node-contracts / design-spec / code-standards; injected by `init-hybrid.ts` spec generation and `src/adapters/loop-agent.ts`; projected via init-surface manifest. Not in `DEFAULT_SKILLS_BY_ROLE`. |
+| `frontend-review` | local existing (frontend hybrid DAG) | `skills/frontend-review/SKILL.md` | reviewer (frontend review nodes, spec-level) | frontend-implementation / repair DAGs | Consumed by `init-hybrid.ts` / `frontend-repair.ts` / `shell-executor.ts`; required ref review-findings (maxChars 2800). |
+| `frontend-verification` | local existing (frontend hybrid DAG) | `skills/frontend-verification/SKILL.md` | verifier / closeout (frontend evidence, spec-level) | frontend DAG closeout | Consumed by `shell-executor.ts` / `frontend-repair.ts` / `frontend-review-context.ts`; required ref verification-checklist. |
+| `frontend-design-review` | local existing (frontend hybrid DAG) | `skills/frontend-design-review/SKILL.md` | design-gate reviewer (before any writer) | frontend-implementation DAG design gate | Injected by `init-hybrid.ts`; runs before the prewrite gate authorizes writers; required ref review-checklist. |
+| `frontend-bounded-implement` | local existing (frontend hybrid DAG) | `skills/frontend-bounded-implement/SKILL.md` | implementer (writer nodes, spec-level) | frontend writers after canonical contract gate | Injected by `init-hybrid.ts`; writers run only after the canonical contract gate accepts and only inside the frozen writeSet (ADR 0015/0016 discipline). |
 | `grill-with-docs` | local operator skill adapted from domain grilling + ADR/glossary discipline | `skills/grill-with-docs/SKILL.md` | explicit interactive operator only | never a default DAG role | Resolves decisions via `harness.json.governanceRoot`; required refs `context-format.md` / `adr-format.md`; respects writeSet; not in `DEFAULT_SKILLS_BY_ROLE`. |
+| `grill-me` | local interview question engine wrapper | `skills/grill-me/SKILL.md` | interview runtime dependency (not a DAG role) | never a default DAG role | Question engine lives in `src/worker/console/interview/grill-me.ts` (Console interview / operator-actions); intentionally NOT projected by init-surface manifest — runs in this repo's Console only. |
+| `analyze-product-requirements` | local org-internal Product Analysis V4 skill | `skills/analyze-product-requirements/SKILL.md` | source-prepare dependency (not a DAG role) | never a default DAG role | Loaded by `src/task/source-prepare/prepare.ts` during 任务源 preparation; IRON-LAW freeze semantics on `product-analysis.md`; intentionally NOT projected by init-surface manifest. |
 | `webapp-testing` | local wrapper inspired by frontend/browser testing practice | `skills/webapp-testing/SKILL.md` | verifier, reviewer | optional | Only applies when task explicitly involves browser-rendered behavior; no default Playwright/Semgrep execution. |
 | `playwright-cli` | repo-local Playwright CLI instructions | `skills/playwright-cli/SKILL.md` | FE-test case executor | FE-test only | Direct browser commands require isolated test environments, per-case evidence paths, and explicit credential/data handling. |
 | `playwright-cli-case-generator` | adapted from the repo-local playwright CLI case-generator contract | `skills/playwright-cli-case-generator/SKILL.md` | FE-test case generator | FE-test only | Generates Markdown cases and a compact manifest from RAG facts; does not execute browsers, create test code, or invent API/data constraints. |
+| `analyze-product-dependencies` | local org-internal product dependency analysis | `skills/analyze-product-dependencies/SKILL.md` | explicit interactive operator only | never a default DAG role | PRD → code/API mapping analysis; read-only; no runtime references; not projected. |
+| `browser-tools` | local operator skill (CDP automation) | `skills/browser-tools/SKILL.md` | explicit interactive operator only | never a default DAG role | Requires user-visible Chrome with remote debugging (:9222); credential/data handling reviewed per use; not projected. |
+| `local-jacoco-coverage` | local operator orchestration skill | `skills/local-jacoco-coverage/SKILL.md` | explicit interactive operator only | never a default DAG role | Orchestrates backend-test DAGs with a JaCoCo agent — it drives DAGs, so it must never be loaded by one (no recursion); not projected. |
+| `using-git-worktrees` | local wrapper | `skills/using-git-worktrees/SKILL.md` | explicit interactive operator only | never a default DAG role | Workspace isolation guidance only; no runtime references; not projected. |
+| `improve-codebase-architecture` | local operator skill (copied from shared agent platform 2026-08-21) | `skills/improve-codebase-architecture/SKILL.md` | explicit interactive operator only | never a default DAG role | Interactive architecture review producing a temp HTML report; reads CONTEXT.md glossary + `docs/decisions/` ADRs; cross-directory refs `../grill-with-docs/{context,adr}-format.md` are exempt (see Vetting Rules); not projected. |
 
 ## Verification placement taxonomy
 
@@ -42,6 +54,8 @@ Authoring vocabulary for where a check or verification skill should live. Prefer
 - Default role mappings may reference only repo-local skills that resolve cleanly under `dag validate --strict-skills`.
 - `agent-worker` is explicitly outside default role mappings. Its trigger description must cover `agent-worker`, Feature Packet, TaskSpec, Task Pool, self-host/candidate and the `loop-agent` routing boundary; `scripts/check-skill-entry.sh` enforces this public entry contract.
 - `grill-with-docs` is an explicit interactive operator skill only; it must stay outside `DEFAULT_SKILLS_BY_ROLE`.
+- Registry ↔ disk sync: every `skills/*/SKILL.md` in the repo must have a row above. Operator-local skills are recorded with `never a default DAG role` instead of being omitted, so an audit cannot mistake them for drift.
+- `improve-codebase-architecture` is exempt from the "references stay within the skill directory" rule: it is operator-only, never resolved by DAG skill snapshots, and reuses `grill-with-docs` context/ADR formats by relative path.
 - Optional/security/web skills remain task- or profile-specific until their tool, network, credential, and write behavior is reviewed.
 - This registry records source inspiration, not license clearance for vendored third-party content. Vendoring requires a separate license/security review.
 - `SKILL.md` is the entry point. References must be declared in frontmatter and stay within the skill directory.

package/docs/templates/README.md

@@ -30,7 +30,7 @@
 
 ## Backend-test
 
-- `backend-test-dag.json` — backend-test DAG 模板；其中 `generate-backend-md-cases-pi` 是唯一允许 `writer-empty-diff` 重试的 writer（总共两次，仅限 post-write-guard attribution 确认的空 diff）。
+- `backend-test-dag.json` — backend-test DAG 模板；其中 `generate-backend-md-cases-pi` 是唯一允许 `writer-empty-diff` 重试的 writer（总共两次，仅限 post-write-guard attribution 确认的空 diff）；N2/N5 合同限定 Scenario Partition 必须有源有限域。
 - `backend-test-dag.classify.prompt.md`、`backend-test-dag.generate-pytest.prompt.md`、`backend-test-dag.review-cases.prompt.md`、`backend-test-dag.retrospect.prompt.md` — 分类、生成、审查和复盘提示。
 - `backend-test-analysis.schema.json`、`backend-test-execution.schema.json`、`backend-test-result.schema.json`、`backend-test-case-manifest.schema.json` — 分析、执行、结果与用例清单 schema。