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

package/dist/workflows/dag/repair-artifact.js

@@ -13,12 +13,51 @@ export const repairArtifactSchema = z.object({
     schemaVersion: z.literal(1),
     verdict: z.enum(["pass", "request-revision"]),
     failureClass: repairFailureClassSchema,
-    rootCause: z.string().min(1),
+    rootCause: z
+        .string()
+        .min(1, { message: 'repair artifact field "rootCause" must be a non-empty string' }),
     fixScope: z.array(z.string().min(1)).default([]),
     invariant: z.string().min(1),
     evidenceRefs: z.array(z.string().min(1)).default([]),
     rawLogFallbackAllowed: z.boolean().default(false),
 });
+/**
+ * Canonical rootCause substituted when a `verdict: "pass"` repair artifact
+ * arrives with an empty or whitespace-only rootCause. Keeps the persisted
+ * RepairArtifact schema-valid without weakening request-revision diagnostics.
+ */
+export const PASS_VERDICT_DEFAULT_ROOT_CAUSE = "No repair required.";
+/**
+ * Normalize model-emitted repair artifacts deterministically at the parser
+ * boundary: a `verdict: "pass"` artifact with an empty/whitespace-only
+ * rootCause is rewritten to the canonical default so it still satisfies the
+ * strict schema. request-revision and other fields are left untouched so the
+ * strict diagnostics and write boundaries remain fail-closed.
+ */
+function normalizePassArtifactRootCause(parsed) {
+    if (parsed &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed) &&
+        parsed.verdict === "pass") {
+        const record = parsed;
+        const rootCause = record.rootCause;
+        if (typeof rootCause === "string" && rootCause.trim().length === 0) {
+            return { ...record, rootCause: PASS_VERDICT_DEFAULT_ROOT_CAUSE };
+        }
+    }
+    return parsed;
+}
+/**
+ * Render a single Zod issue as a field-path-aware message so callers can locate
+ * invalid repair-artifact fields instead of seeing bare min-length text.
+ */
+function describeZodIssue(issue) {
+    const path = issue.path && issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    if (issue.message && !/^String must contain/.test(issue.message)) {
+        return `field "${path}": ${issue.message} (code ${issue.code})`;
+    }
+    return `field "${path}" is invalid (code ${issue.code})`;
+}
 const REPAIR_ARTIFACT_FENCE = /```(?:REPAIR_ARTIFACT_JSON|json)\s*([\s\S]*?)```/gi;
 function extractCandidateJsonBlocks(text) {
     const blocks = [];
@@ -42,11 +81,12 @@ export function parseRepairArtifactFromText(text) {
     for (const candidate of candidates) {
         try {
             const parsed = JSON.parse(candidate);
-            const result = repairArtifactSchema.safeParse(parsed);
+            const normalized = normalizePassArtifactRootCause(parsed);
+            const result = repairArtifactSchema.safeParse(normalized);
             if (result.success) {
                 return { ok: true, artifact: result.data };
             }
-            errors.push(result.error.issues.map((issue) => issue.message).join(", "));
+            errors.push(result.error.issues.map((issue) => describeZodIssue(issue)).join(", "));
         }
         catch (error) {
             errors.push(error instanceof Error ? error.message : String(error));

package/dist/workflows/dag/skill-instructions.js

@@ -3,8 +3,8 @@ import { access, readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-export const DEFAULT_SKILL_INSTRUCTION_MAX_CHARS = 2_500;
-export const DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS = 10_000;
+export const DEFAULT_SKILL_INSTRUCTION_MAX_CHARS = 3_000;
+export const DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS = 12_000;
 const SKILL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 async function fileExists(filePath) {
     try {
@@ -413,7 +413,9 @@ async function findFirstExistingFile(candidates) {
 async function resolveLearnedPatternInstructions(input) {
     const repoSlug = path.basename(input.cwd).replace(/[^A-Za-z0-9_-]+/g, "-");
     const candidates = [
+        normalizeCandidate(path.join(input.cwd, ".agents", "skills", "loop-agent", "references", "learned", `${repoSlug}.md`)),
         normalizeCandidate(path.join(input.cwd, "skills", "loop-agent", "references", "learned", `${repoSlug}.md`)),
+        normalizeCandidate(path.join(input.cwd, ".agents", "skills", "loop-agent", "references", "learned", "default.md")),
         normalizeCandidate(path.join(input.cwd, "skills", "loop-agent", "references", "learned", "default.md")),
         normalizeCandidate(path.join(input.cwd, "tools", "loop-agent", "skill", "references", "learned", `${repoSlug}.md`)),
         normalizeCandidate(path.join(input.cwd, "tools", "loop-agent", "skill", "references", "learned", "default.md")),

package/dist/workflows/dag/types.js

@@ -63,13 +63,26 @@ export const dagVerdictGateSchema = z.object({
     label: z.string().min(1).optional(),
 });
 export const dagRequirementCoverageGateSchema = z.object({
-    fromNodeIds: z.array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fromNodeIds must be kebab-case")).min(1),
-    requiredIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/, "requiredIds must use REQ-*, BR-*, or AC-* identifiers")).min(1),
+    fromNodeIds: z
+        .array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fromNodeIds must be kebab-case"))
+        .min(1),
+    requiredIds: z
+        .array(z
+        .string()
+        .regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/, "requiredIds must use REQ-*, BR-*, or AC-* identifiers"))
+        .min(1),
     label: z.string().min(1).optional(),
 });
+export const dagJsonArtifactSchemaIdSchema = z.enum([
+    "backend-test-analysis-v1",
+    "backend-test-execution-v1",
+    "backend-test-result-v1",
+    "backend-test-case-manifest-v1",
+    "frontend-implementation-contract-v1",
+]);
 export const dagJsonArtifactGateSchema = z.object({
     fromNodeId: z.string().regex(/^[a-z][a-z0-9-]*$/),
-    schemaId: z.literal("backend-test-analysis-v1"),
+    schemaId: dagJsonArtifactSchemaIdSchema,
     artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
 });
@@ -117,6 +130,8 @@ export const dagShellConfigSchema = z.object({
     jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),
+    /** fail (default): any nonzero command fails the node. record: finish node FINISHED with failure facts for downstream assess/repair. */
+    nonZeroExitPolicy: z.enum(["fail", "record"]).optional(),
     envAllowlist: z.array(z.string()).optional(),
     timeoutMs: z.number().optional(),
     cwd: z.string().optional(),
@@ -153,10 +168,12 @@ export const dagDynamicExpansionSchema = z.object({
         .string()
         .regex(/^[a-z][a-z0-9-]*$/, "childIdPrefix must be kebab-case"),
     childTask: dagDynamicExpansionChildTaskSchema,
-    tokenBudget: z.object({
+    tokenBudget: z
+        .object({
         maxTokensPerCase: z.number().int().positive().optional(),
         maxTotalTokens: z.number().int().positive().optional(),
-    }).optional(),
+    })
+        .optional(),
 });
 export const dagDynamicReductionSchema = z.object({
     type: z.literal("verified_findings_report"),
@@ -286,11 +303,15 @@ export const dagEvaluationBindingSchema = z
 export const dagSourceBindingSchema = z.object({
     schemaVersion: z.literal(1),
     taskId: z.string().min(1),
-    sources: z.array(z.object({
+    sources: z
+        .array(z.object({
         kind: z.enum(["requirement", "constraint", "reference"]),
         path: z.string().min(1),
-        sha256: z.string().regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
-    })).min(1),
+        sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
+    }))
+        .min(1),
     requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
 });
 export const dagSpecSchema = z

package/docs/README.md

@@ -1,106 +1,107 @@
-# 文档索引
-
-`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
-
-顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
-
-**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
-
-站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
-
-## 核心文档
-
-- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
-- `development-principles.md` — 仓库开发原则
-- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
-- `architecture/README.md` — 架构文档目录索引与阅读路径
-- `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
-- `architecture/dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期
-- `architecture/worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe
-- `architecture/facts-and-state.md` — harness 事实与状态、canonical/derived、可写/只读边界
-- `architecture/evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向
-- `feature-workflow.md` — 有边界的功能工作流
-- `verification-matrix.md` — 验证命令选择
-- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
-- `loop-agent-harness.md` — runtime 与 command surface 概览
-- `agent-dag-runner.md` — Agent DAG runner 指南
-- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
-- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
-- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
-- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
-- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
-
-## 近期完成合同（入口）
-
-完整列表见 `exec-plans/completed/README.md`。近期高频入口：
-
-- `exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md` — Website IA、双树边界与 docs-converge
-- `exec-plans/completed/2026-07-13-versioned-self-hosting-bootstrap.md` — 版本化自举与 candidate canary
-- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime
-- `exec-plans/completed/2026-07-12-observe-warm-console-redesign.md` — Observe 暖白运行控制台
-- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout 与 dogfood 收口（M2-01～08 见 completed 索引）
-
-## 设计思想来源
-
-- `../website/docs/practices/` — Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 与社区 agent harness 实践资料。当前仓库的“人类掌舵、智能体执行”、仓库即记录系统、小步增量、结构化 handoff 和 shell verification 纪律均受这些实践启发；权威执行规则仍以本目录治理文档、根目录 AGENTS.md、harness.json、skills 目录和脚本检查为准。
-
-## 方法论
-
-- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
-- `harness-methodology-verification.md` — 完成声明前的验证纪律
-- `harness-methodology-debugging.md` — 修复前的系统化调试工作流
-
-## 产物目录
-
-- `design/README.md` — 设计草稿、契约映射与路线图（含 design/dynamic-workflow-dag-engine-roadmap.md）
-- `exec-plans/active/README.md` — 进行中的执行计划
-- `exec-plans/completed/README.md` — 已完成的执行计划（全量）
-- `progress/README.md` — 进度交接日志（全量）
-- `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
-- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
-- `skills/README.md` — repo-local skill registry and vetting notes
-- `templates/` — 可复用的规划、报告与 DAG 模板
-
-## 仓库 Skills
-
-- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
-- `../skills/agent-worker/` — Feature Packet / Task Pool / versioned self-hosting 的可选 outer-loop operator skill；不进入默认 DAG role skills
-- 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
-
-## 模板
-
-- `templates/project-start-checklist.md` — 开工前检查清单
-- `templates/feature-spec.md` — 有边界的功能规格
-- `templates/sprint-contract.md` — 实现契约与验收标准
-- `templates/exec-plan.md` — 非平凡工作的执行计划
-- `templates/progress-log.md` — 进度与交接日志
-- `templates/qa-report.md` — 验证与 QA 证据
-- `templates/worker-dogfood-setup.md` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
-- `templates/worker-dogfood-evidence.md` — controller fingerprint、skill snapshot、canary、BE/FE/QA、Observe 与 failure evidence 模板
-- `templates/harness.schema.json` — `harness.json` 的 IDE JSON Schema，随初始化投影到目标项目
-- `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
-- `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
-- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
+# 文档索引
+
+`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
+
+顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
+
+**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
+
+站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
+
+## 核心文档
+
+- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
+- `development-principles.md` — 仓库开发原则
+- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
+- `architecture/README.md` — 架构文档目录索引与阅读路径
+- `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
+- `architecture/dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期
+- `architecture/worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe
+- `architecture/facts-and-state.md` — harness 事实与状态、canonical/derived、可写/只读边界
+- `architecture/evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向
+- `feature-workflow.md` — 有边界的功能工作流
+- `verification-matrix.md` — 验证命令选择
+- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
+- `loop-agent-harness.md` — runtime 与 command surface 概览
+- `agent-dag-runner.md` — Agent DAG runner 指南
+- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
+- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
+- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
+- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
+- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
+
+## 近期完成合同（入口）
+
+完整列表见 `exec-plans/completed/README.md`。近期高频入口：
+
+- `exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md` — Website IA、双树边界与 docs-converge
+- `exec-plans/completed/2026-07-13-versioned-self-hosting-bootstrap.md` — 版本化自举与 candidate canary
+- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime
+- `exec-plans/completed/2026-07-12-observe-warm-console-redesign.md` — Observe 暖白运行控制台
+- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout 与 dogfood 收口（M2-01～08 见 completed 索引）
+
+## 设计思想来源
+
+- `../website/docs/practices/` — Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 与社区 agent harness 实践资料。当前仓库的“人类掌舵、智能体执行”、仓库即记录系统、小步增量、结构化 handoff 和 shell verification 纪律均受这些实践启发；权威执行规则仍以本目录治理文档、根目录 AGENTS.md、harness.json、skills 目录和脚本检查为准。
+
+## 方法论
+
+- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
+- `harness-methodology-verification.md` — 完成声明前的验证纪律
+- `harness-methodology-debugging.md` — 修复前的系统化调试工作流
+
+## 产物目录
+
+- `design/README.md` — 设计草稿、契约映射与路线图（含 design/dynamic-workflow-dag-engine-roadmap.md）
+- `exec-plans/active/README.md` — 进行中的执行计划
+- `exec-plans/completed/README.md` — 已完成的执行计划（全量）
+- `progress/README.md` — 进度交接日志（全量）
+- `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
+- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
+- `skills/README.md` — repo-local skill registry and vetting notes
+- `templates/` — 可复用的规划、报告与 DAG 模板
+
+## 仓库 Skills
+
+- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
+- `../skills/agent-worker/` — Feature Packet / Task Pool / versioned self-hosting 的可选 outer-loop operator skill；不进入默认 DAG role skills
+- 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
+
+## 模板
+
+- `templates/project-start-checklist.md` — 开工前检查清单
+- `templates/feature-spec.md` — 有边界的功能规格
+- `templates/sprint-contract.md` — 实现契约与验收标准
+- `templates/exec-plan.md` — 非平凡工作的执行计划
+- `templates/progress-log.md` — 进度与交接日志
+- `templates/qa-report.md` — 验证与 QA 证据
+- `templates/worker-dogfood-setup.md` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
+- `templates/worker-dogfood-evidence.md` — controller fingerprint、skill snapshot、canary、BE/FE/QA、Observe 与 failure evidence 模板
+- `templates/harness.schema.json` — `harness.json` 的 IDE JSON Schema，随初始化投影到目标项目
+- `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
+- `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
+- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
 - `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
+- `templates/branch-merge-report.md` — 跨分支合并的功能保留、冲突解析、init/update 与 package surface 审计模板
 - `templates/adr.md` — 架构决策记录（ADR）
-
-## 维护
-
-文档变更后运行：
-
-```bash
-node bin/loop-agent.js docs audit --repo-root .
-bash scripts/check-doc-index.sh
-bash scripts/check-doc-links.sh
-bash scripts/check-repo.sh
-```
-
-涉及 `website/docs/` 时再跑 `npm run docs:build`，并按 `skills/loop-agent/references/docs-converge.md` 同步 `overview/roadmap.md` 等站上活页。
-
-Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
-
-完整本地门禁：
-
-```bash
-bash scripts/ci.sh
-```
+
+## 维护
+
+文档变更后运行：
+
+```bash
+node bin/loop-agent.js docs audit --repo-root .
+bash scripts/check-doc-index.sh
+bash scripts/check-doc-links.sh
+bash scripts/check-repo.sh
+```
+
+涉及 `website/docs/` 时再跑 `npm run docs:build`，并按 `skills/loop-agent/references/docs-converge.md` 同步 `overview/roadmap.md` 等站上活页。
+
+Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+完整本地门禁：
+
+```bash
+bash scripts/ci.sh
+```