@tea-agent/loop-agent 0.17.2 → 0.18.0

package/dist/workflows/dag/init-hybrid.js

@@ -21,6 +21,7 @@ import { resolveExecutorModelMatrices } from "../../executors/model-routing.js";
 import { normalizeTaskRequirementText, resolveTaskDagTemplateSelection, } from "./task-demand-routing.js";
 import { BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT, buildBackendTestExecutionPreflightShellSnippet, } from "./backend-test-execution-contract.js";
 import { buildBackendTestOutcomeGateShellSnippet } from "./backend-test-result-contract.js";
+import { buildBackendTestIntakeContext } from "./backend-test-intake-context.js";
 import { buildFrontendTestOutcomeGateShellSnippet } from "./frontend-test-result-contract.js";
 import { classifyFrontendRisk, } from "./frontend-risk.js";
 import { discoverFrontendProjectCapability, } from "./frontend-project-capability.js";
@@ -29,7 +30,7 @@ const REQUIREMENT_FILE = "需求.md";
 const CONSTRAINT_FILE = "执行约束.md";
 const REFERENCE_DIRECTORY = "references";
 const MAX_SOURCE_EXCERPT_CHARS = 2000;
-const MAX_SOURCE_REFERENCE_DOCUMENTS = 8;
+const MAX_INLINE_SOURCE_REFERENCE_DOCUMENTS = 8;
 const INTERACTIVE_UI_DELIVERY_CONTRACT = [
     "[INTERACTIVE_UI_DELIVERY_CONTRACT]",
     "This is an interactive UI delivery task.",
@@ -981,7 +982,7 @@ function buildSourceContextBlock(sources) {
         });
         parts.push("## Task source: 执行约束.md", constraintExcerpt.text);
     }
-    for (const reference of sources.referenceDocuments ?? []) {
+    for (const reference of (sources.referenceDocuments ?? []).slice(0, MAX_INLINE_SOURCE_REFERENCE_DOCUMENTS)) {
         const relativePath = path
             .relative(path.join(sources.taskDir, "source"), reference.path)
             .replaceAll(path.sep, "/");
@@ -1027,9 +1028,7 @@ async function loadMaterializedSourceReferences(sourceDir) {
     }
     await collect(referenceDir);
     referencePaths.sort((left, right) => left.localeCompare(right));
-    return Promise.all(referencePaths
-        .slice(0, MAX_SOURCE_REFERENCE_DOCUMENTS)
-        .map(async (filePath) => ({
+    return Promise.all(referencePaths.map(async (filePath) => ({
         path: filePath,
         markdown: await readFile(filePath, "utf-8"),
     })));
@@ -3285,119 +3284,104 @@ const BACKEND_TEST_SKILLS_BY_ROLE = {
     verifier: ["verification-before-completion", "systematic-debugging"],
     closeout: ["loop-agent", "verification-before-completion"],
 };
-function buildBackendTestHybridDag(sources) {
+async function buildBackendTestHybridDag(sources) {
     const { taskConfig } = sources;
-    const globalConstraints = [
-        ...taskConfig.hardConstraints,
-        ...STANDARD_GLOBAL_CONSTRAINTS,
-        "backend-test-dag uses exactly 12 real top-level tasks and executes pytest exactly once.",
-        "Case review is advisory evidence consumed by canonical context, retrospective, and L-5; it does not authorize or block the pytest writer.",
-        "Deterministic traceability is the only generated-asset hard gate before pytest.",
-        "Analysis, execution, manifest, case review, traceability, single-run result, classification, canonical context, retrospective and L-5 evidence remain run-owned and fail-closed.",
-        "Functional test case IDs must use BE-<MODULE>-<NNN> format.",
-        "pytest writers may only create the initially declared testcase assets; production code, config, skip/xfail, swallowed failures and mock substitution are forbidden.",
-    ];
-    const analyze = buildAnalyzeInputsNode(sources);
-    analyze.id = "analyze-and-discover-backend-test-pi";
-    analyze.outputContract =
-        "Pure JSON envelope {analysis: Backend Test Analysis v2, execution: Backend Test Execution Contract v1}; no prose or writes.";
-    analyze.subtask_prompt = `${analyze.subtask_prompt}\n\nAlso perform the read-only environment discovery described by Backend Test Execution Contract v1. Return exactly one JSON envelope with top-level keys analysis and execution; analysis must satisfy v2 and execution must satisfy v1.`;
-    const contracts = {
-        id: "validate-backend-test-contracts-shell",
-        depends_on: [analyze.id],
-        role: "verifier",
-        executor: "shell",
-        complexity: "LOW",
-        writePolicy: "read-only",
-        allowedPaths: commonReadOnlyPaths(sources),
-        forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Materialize and validate contracts/backend-test-analysis.json and contracts/backend-test-execution.json.",
-        subtask_prompt: "Validate both backend-test intake contracts fail-closed.",
-        shell: {
-            commands: [],
-            backendTestPipeline: "contracts",
-            cwd: ".",
-            timeoutMs: 60000,
-        },
-    };
-    const generateCases = buildGenerateBackendFunctionalCasesNode(sources);
-    generateCases.id = "generate-backend-cases-and-manifest-pi";
-    generateCases.depends_on = [contracts.id];
-    generateCases.outputContract =
-        "Write testcase/md/** and end with one fenced json Backend Test Case Manifest v1 block matching the strict field contract.";
-    generateCases.subtask_prompt += `\n\nAfter writing Markdown, end assistant output with exactly one fenced json block containing Backend Test Case Manifest v1 derived from the written cases.\n\n${BACKEND_TEST_CASE_MANIFEST_OUTPUT_INSTRUCTIONS}`;
-    const manifest = buildBackendTestCaseManifestGateNode(sources, {
-        dependsOn: [generateCases.id],
-        fromNodeId: generateCases.id,
-    });
-    const reviewCases = buildReviewBackendCasesNode(sources, {
-        dependsOn: [manifest.id, contracts.id, "generate-backend-pytest-pi"],
-    });
-    const generatePytest = buildGenerateBackendPytestNode(sources);
-    generatePytest.depends_on = [manifest.id, contracts.id];
-    const traceability = buildBackendTestTraceabilityGateNode(sources, {
-        dependsOn: [generatePytest.id, manifest.id],
-    });
-    const execute = buildExecuteBackendPytestNode(sources, {
-        id: "execute-and-parse-backend-pytest-shell",
-        dependsOn: [traceability.id, contracts.id],
-        reportStem: "backend-test-initial",
+    const ro = commonReadOnlyPaths(sources);
+    const forbidden = commonForbiddenPaths(sources);
+    const intake = await buildBackendTestIntakeContext(sources);
+    const shellNode = (id, depends_on, pipeline, prompt, outputContract, commands = [], timeoutMs = 60000) => ({
+        id, depends_on, role: "verifier", executor: "shell", complexity: "LOW",
+        writePolicy: "read-only", allowedPaths: ro, forbiddenPaths: forbidden,
+        outputContract, subtask_prompt: prompt,
+        shell: { commands, backendTestPipeline: pipeline, cwd: ".", timeoutMs,
+            ...(commands.length ? { envAllowlist: collectBackendTestShellEnvAllowlist(sources) } : {}) },
     });
-    execute.shell.backendTestPipeline = "execute-parse-initial";
-    const classify = buildClassifyBackendTestResultNode(sources);
-    classify.depends_on = [execute.id];
-    const context = {
-        id: "materialize-classification-and-result-context-shell",
-        depends_on: [classify.id, manifest.id, reviewCases.id, traceability.id],
-        role: "verifier",
-        executor: "shell",
-        complexity: "LOW",
-        writePolicy: "read-only",
-        allowedPaths: commonReadOnlyPaths(sources),
-        forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Materialize Classification v1, copy the unique initial Result to canonical contracts/backend-test-result.json, and emit Result + Manifest + Classification + advisory case review + traceability context.",
-        subtask_prompt: "Validate classification and materialize canonical single-run result context with auditable case review and traceability evidence, without repair eligibility or rerun.",
-        shell: {
-            commands: [],
-            backendTestPipeline: "classification-result-context",
-            cwd: ".",
-            timeoutMs: 60000,
-        },
+    const environment = shellNode("validate-backend-test-environment-shell", [], "markdown-environment", "Fail fast before model work when Python/pytest cannot run in the clean shell. Inspect only bounded common config, conftest, test-root and server-entry candidates; never read .env values or credentials.", "Run-owned reports/backend-test-environment.md with PASS/FAIL runtime, bounded project discovery, fixture and HTML-renderer facts; no secret values.", ["python --version", "python -m pytest --version", "python -m pytest --help"]);
+    const generateCases = {
+        id: "generate-backend-md-cases-pi", depends_on: [environment.id], role: "implementer",
+        executor: "pi", toolProfile: "write", complexity: "MED", writePolicy: "exclusive",
+        writeSet: ["testcase/md/**"], allowedPaths: ["testcase/md/**"], forbiddenPaths: forbidden,
+        outputContract: "Write testcase/md/README.md plus module Markdown cases using BE-<MODULE>-<NNN>. Use Chinese for human-readable content while preserving required machine-readable identifiers and section headings; no JSON, pytest execution, production code or config writes.",
+        subtask_prompt: [
+            "Read the upstream environment report. Generate a Markdown-first backend test strategy and cases under testcase/md/**.",
+            "Write human-readable content in Simplified Chinese by default: document titles, case titles, strategy explanations, preconditions, test-data descriptions, step descriptions, expected-result descriptions, automation notes, table headers and evidence-gap explanations. Keep English only where it is part of a machine-readable contract or established technical literal, including Case IDs, AC/REQ/BR IDs, exact section headings, HTTP methods, paths, field names, enum values, commands, filenames, code symbols and source citations. Do not add an English translation when Chinese already conveys the meaning.",
+            "Every case heading is `## BE-<MODULE>-<NNN> <中文用例标题>` and contains these exact machine-readable headings: `### Acceptance Criteria`, `### Source References`, `### Preconditions`, `### Test Data`, `### Steps`, `### Expected Results`, and `### Automation Notes`. API cases also contain `### Endpoint` with Method and Path. Under those headings, write descriptions in Chinese while preserving exact IDs, values and protocol literals.",
+            "Create testcase/md/README.md in Chinese. It should concisely explain the test objective, environment/target, isolation and cleanup strategy, module index, traceability summary, assertion principles, evidence gaps and non-goals. Prefer readable Chinese tables and lists over repeated boilerplate.",
+            "Expected Results must be concrete, independently assertable Chinese statements. Each result should name the observable HTTP status, response field/value, state transition or membership condition instead of vague phrases such as ‘works correctly’ or ‘符合预期’. Steps must be executable and ordered. Use only environment-supported fixtures/targets/isolation. Record evidence gaps in Chinese instead of inventing behavior or credentials. Do not emit JSON, pytest, or execute commands.",
+            intake.boundedSourceContext, "## Authoritative reference index", JSON.stringify(intake.referenceIndex, null, 2),
+            "For each index entry, use `readPath` for Pi read-tool calls and copy `path` exactly into Markdown Source References. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.",
+            "Read only precise indexed references needed for AC/API/field/rule evidence; references remain authoritative over derived text.",
+        ].join("\n\n"),
+    };
+    const reviewCases = {
+        id: "review-and-revise-backend-md-cases-pi", depends_on: [generateCases.id], role: "reviewer",
+        executor: "pi", toolProfile: "write", complexity: "MED", writePolicy: "exclusive",
+        writeSet: ["testcase/md/**"], allowedPaths: ["testcase/md/**"], forbiddenPaths: forbidden,
+        outputContract: "Review source fidelity and directly revise only testcase/md/**; return concise Markdown, never JSON.",
+        subtask_prompt: [
+            "Independently review generated Markdown cases against each case Source References and environment evidence. Preserve and improve the Simplified Chinese presentation: human-readable titles, prose, table headers, steps, expected results and notes should be Chinese unless the token is a machine-readable ID, exact required heading, HTTP/API literal, field/enum value, path, filename, command or code symbol.",
+            "Check AC completeness/meaning, endpoint, fields/shape, status/error codes, rules, states, documented boundaries/auth, positive/negative coverage, executable steps and assertable results. Also reject avoidable English prose, duplicated bilingual wording, vague Chinese results such as ‘符合预期’, and literal translations that obscure the observable assertion.",
+            "Correct testcase/md/** directly: add documented omissions, remove unsupported cases, fix mappings/expectations, merge duplicates, improve unclear Chinese wording, or record gaps in Chinese. Do not translate or alter Case IDs, AC/REQ/BR IDs, exact required section headings, HTTP methods, paths, field names, enum values, filenames, code symbols or Source References. Avoid cosmetic rewrites that do not improve correctness or readability.",
+            "Read only precise referenced source paths plus requirement sections needed for uncovered ACs. Do not scan the repository, modify source/**, generate pytest, execute tests, or emit JSON.",
+            intake.boundedSourceContext, "## Authoritative reference index", JSON.stringify(intake.referenceIndex, null, 2),
+            "For each index entry, use `readPath` for Pi read-tool calls and keep `path` as the exact Markdown Source References citation. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.",
+        ].join("\n\n"),
+    };
+    const validateCases = shellNode("validate-backend-md-cases-shell", [reviewCases.id], "markdown-cases", "Fail closed on missing/duplicate IDs, sections, AC coverage, source references, executable steps, assertable results, placeholders or secret-shaped content.", "Run-owned reports/backend-md-case-validation.md proving final Markdown quality and safety.");
+    const generatePytest = {
+        id: "generate-backend-pytest-pi", depends_on: [validateCases.id], role: "implementer",
+        executor: "pi", toolProfile: "write", complexity: "HIGH", writePolicy: "exclusive",
+        writeSet: ["testcase/**/test_*.py", "testcase/**/helpers/**", "testcase/**/factories/**"],
+        allowedPaths: Array.from(new Set([...ro, "testcase/**"])), forbiddenPaths: forbidden,
+        outputContract: "Convert every final automatable Markdown case one-to-one into pytest assets under the narrow writeSet; no JSON and no pytest execution.",
+        subtask_prompt: [
+            "Convert validated testcase/md/** to pytest using upstream environment and validation evidence plus only bounded pytest config/conftest.",
+            "Each case maps to one `test_BE_<MODULE>_<NNN>_<description>` function whose first docstring line contains the exact Case ID. Assertions come only from Expected Results; setup comes only from Preconditions/Test Data/Automation Notes.",
+            "Do not read source/**, add cases, reassign ACs, modify conftest/config/production code, use skip/xfail, swallow assertions, execute pytest, or emit JSON.",
+        ].join("\n\n"),
+    };
+    const traceability = shellNode("backend-test-traceability-gate-shell", [generatePytest.id], "markdown-traceability", "Fail closed on missing, duplicate or extra Case ID mappings, mismatched docstrings, skip/xfail or swallowed exceptions.", "Run-owned reports/backend-test-traceability.md proving Markdown-to-pytest one-to-one mapping.");
+    const pytestCommand = [
+        'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
+        'PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 python -m pytest testcase/ -v -p no:cacheprovider --junitxml="${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml"',
+        "STATUS=$?", 'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
+        'if { [ "${STATUS}" -eq 0 ] || [ "${STATUS}" -eq 1 ]; } && [ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml" ]; then exit 0; fi',
+        'exit "${STATUS}"',
+    ].join("; ");
+    const execute = shellNode("execute-backend-pytest-and-html-report-shell", [traceability.id], "markdown-execute-html", "Execute pytest exactly once. Validate JUnit, render self-contained HTML from that JUnit without rerun, and preserve failures as facts.", "One pytest execution producing valid JUnit, self-contained HTML and reports/backend-test-facts.md; exit 0/1 with valid evidence continues.", [pytestCommand], 300000);
+    const canWriteReport = taskAllowsBackendTestReportWrite(sources);
+    const report = {
+        id: "backend-test-report-and-l5-pi", depends_on: [execute.id], role: "closeout", executor: "pi", complexity: "MED",
+        ...(canWriteReport
+            ? { toolProfile: "write", writePolicy: "exclusive", writeSet: ["docs/test-reports/**"], allowedPaths: ["docs/test-reports/**"] }
+            : { writePolicy: "read-only", allowedPaths: ro }),
+        forbiddenPaths: forbidden,
+        outputContract: canWriteReport ? "Final Markdown report and L-5 conclusion under docs/test-reports/**; no JSON." : "Final Markdown report and L-5 conclusion in assistant output; no JSON or writes.",
+        subtask_prompt: [
+            "Generate the final Markdown report from upstream facts and run-owned environment, case-validation, traceability, JUnit and HTML evidence. Do not emit JSON.",
+            "Include environment, case quality/review, automation mapping, exact pytest facts, failure classification/analysis, risks, regression recommendations, evidence paths/hashes, coverage/stability availability, and L-5 READY/NOT READY.",
+            "Never override Shell/JUnit facts. One run cannot prove FlakyTest. Missing coverage/stability is Unavailable. L-5 requires pass=100%, AC=100%, automation>=90%, stability>=95% n>=5, line>=80%, branch>=70%, skipped=0 and no blocking Critical risk.",
+            canWriteReport ? "Write only under docs/test-reports/**." : "Keep the full report in assistant output.",
+        ].join("\n\n"),
     };
-    const retrospect = buildTestRetrospectNode(sources);
-    retrospect.depends_on = [context.id];
-    retrospect.subtask_prompt = retrospect.subtask_prompt.replaceAll("select-effective-backend-test-result-shell", context.id);
-    const l5Metrics = buildL5MetricsNode(sources);
-    l5Metrics.depends_on = [retrospect.id];
-    const tasks = [
-        analyze,
-        contracts,
-        generateCases,
-        manifest,
-        reviewCases,
-        generatePytest,
-        traceability,
-        execute,
-        classify,
-        context,
-        retrospect,
-        l5Metrics,
-    ];
     const spec = {
-        version: 3,
-        title: `Backend test DAG: ${taskConfig.title}`,
+        version: 3, title: `Backend test DAG: ${taskConfig.title}`,
         runtimeContract: GENERATED_DAG_RUNTIME_CONTRACT,
         outputLanguage: sources.outputLanguage ?? DEFAULT_DAG_OUTPUT_LANGUAGE,
         objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
         successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
-        globalConstraints,
-        defaults: {
-            ...BACKEND_TEST_DEFAULTS,
-            contextProfile: taskConfig.contextProfile,
-        },
+        globalConstraints: [
+            ...taskConfig.hardConstraints, ...STANDARD_GLOBAL_CONSTRAINTS,
+            "backend-test-dag uses exactly 8 real top-level tasks and executes pytest exactly once.",
+            "Model nodes produce Markdown and pytest assets, never backend-test business JSON envelopes.",
+            "Environment, Markdown validation, traceability, JUnit, HTML and execution facts are deterministic fail-closed evidence.",
+            "Only Markdown case generation/review may read source facts; pytest generation must not read source/**.",
+            "Functional case IDs use BE-<MODULE>-<NNN>; production code/config, skip/xfail, repair and rerun are forbidden.",
+        ],
+        defaults: { ...BACKEND_TEST_DEFAULTS, contextProfile: taskConfig.contextProfile },
         skillsByRole: BACKEND_TEST_SKILLS_BY_ROLE,
         executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
-        tasks,
+        tasks: [environment, generateCases, reviewCases, validateCases, generatePytest, traceability, execute, report],
     };
     applyDefaultReadOnlyRetryPolicy(spec);
     parseDagSpec(spec);
@@ -4797,7 +4781,7 @@ async function buildHybridDagForTemplate(sources, template) {
     else if (template === "frontend-test-dag")
         spec = buildFrontendTestHybridDag(sources);
     else if (template === "backend-test-dag")
-        spec = buildBackendTestHybridDag(sources);
+        spec = await buildBackendTestHybridDag(sources);
     else if (template === "knowledge-sync-dag")
         spec = buildKnowledgeSyncHybridDag(sources);
     else if (template === "knowledge-graph-bootstrap-dag")

package/dist/workflows/dag/types.js

@@ -177,6 +177,10 @@ export const dagBackendTestPipelineSchema = z.enum([
     "semantic-initial",
     "execute-parse-initial",
     "classification-result-context",
+    "markdown-environment",
+    "markdown-cases",
+    "markdown-traceability",
+    "markdown-execute-html",
 ]);
 export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),

package/dist/workflows/loop/benchmark.js

@@ -465,7 +465,7 @@ export function formatLoopBenchmarkMarkdown(result) {
         "",
         "```bash",
         "cd .",
-        "npm run dev -- loop-benchmark --markdown --output docs/reports/2026-06-30-loop-agent-loop-benchmark.md",
+        "npm run dev -- loop-benchmark --markdown --output docs/reports/dogfood/2026-06-30-loop-agent-loop-benchmark.md",
         "```",
         "",
         "## Recommendation",

package/docs/README.md

@@ -6,46 +6,85 @@
 
 **索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
 
+**维护日：2026-07-22** — 索引对齐仓库头 `@tea-agent/loop-agent@0.17.2`、reports 按类型分子目录，以及 progress / completed 导读制；版本与能力细节以 `CHANGELOG.md`、`reports/current-capability-summary.md` 与 active plans 为准。
+
 站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
 
-## 核心文档
+## 阅读路径
+
+1. 根目录 `AGENTS.md` + 本索引（地图）
+2. 活契约：`development-principles.md` → `feature-workflow.md` → `verification-matrix.md`
+3. Runtime / DAG：`loop-agent-harness.md` → `agent-dag-runner.md` → 需要时再读 `agent-dag-recovery-playbook.md`
+4. 架构边界：`architecture/runtime-boundaries.md`，再按 `architecture/README.md` 往下读
+5. 产物目录：active plan → progress handoff → reports 证据；设计输入见 `design/README.md`
+
+## 活契约（根目录）
+
+根目录 `docs/*.md` 是**当前仍生效**的操作契约与手册，不按日期归档、不按主题再拆子目录。
 
-- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
 - `development-principles.md` — 仓库开发原则
-- `github-collaboration.md` — 内部研发人员的轻量 GitHub 协作指南：短分支、简短 PR、CI 与 Squash Merge
-- `local-development-environment.md` — Cursor Cloud 等特定本地开发环境的已知问题与排障方法
-- `branch-merge-guideline.md` — 分支合并标准流程：快速/标准/深度模式、功能保留、冲突解析、init/package 审计与 source-SHA 报告
-- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
-- `architecture/README.md` — 架构文档目录索引与阅读路径
+- `feature-workflow.md` — 有边界的功能工作流、taskKind / profile、DAG 与 handoff 纪律
+- `verification-matrix.md` — 验证命令选择
+- `loop-agent-harness.md` — runtime 与 command surface 概览
+- `agent-dag-runner.md` — Agent DAG runner 指南
+- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
+- `backend-test-live-campaign.md` — backend-test 控制器修复与真实宿主循环验证：双仓库隔离、全新 Task/DAG/Run、首错即停、证据归档和中文用例合同
+- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
+- `branch-merge-guideline.md` — 分支合并：快速/标准/深度模式、功能保留、冲突解析、init/package 审计与 source-SHA 报告
+- `github-collaboration.md` — 内部轻量 GitHub 协作：短分支、简短 PR、CI 与 Squash Merge
+- `local-development-environment.md` — Cursor Cloud 等特定本地环境的已知问题与排障
+- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar（非受治理 writer）
+- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 的机器校验契约
+
+## 架构
+
+入口与阅读顺序见 `architecture/README.md`。
+
+- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向（边界真源）
 - `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/backend-test-workflow.md` — 已实现的 backend-test 15 节点单次执行全流程、pass-only 评审门禁、run-owned artifacts 与最终 outcome
-- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
-- `design/agent-worker-fullstack-workflow-integration.md` — 已实现的 workflow routing、Task Outcome、artifact-aware Ready、`fullstack-v1` 与 Verification Bundle，以及后续 failure routing / execute-existing 领域设计
-- `design/fullstack-end-to-end-delivery-optimization-roadmap.md` — 当前全栈端到端优化的收敛路线图：先完成 release train / Delivery，再冻结 Final Verification 权威、Environment Contract、分类恢复与 Observe 指标
-- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
-- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
 
-## 近期完成合同（入口）
+## 设计入口（非实现证明）
+
+完整索引与归档策略见 `design/README.md`。下列为当前高频活入口：
+
+- `design/backend-test-workflow.md` — backend-test Markdown-first 8 节点流程、单次 pytest、run-owned artifacts 与 L-5
+- `design/frontend-mock-data-workflow.md` — 前端 Mock 节点、触发条件、规范证据与失败路由
+- `design/frontend-implementation-workflow.md` — 前端实现 / 评审 / 验证工作流
+- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的任务源绑定与中断恢复
+- `design/agent-worker-fullstack-workflow-integration.md` — workflow routing、Task Outcome、artifact-aware Ready、`fullstack-v1` 与 Verification Bundle
+- `design/fullstack-end-to-end-delivery-optimization-roadmap.md` — 全栈端到端优化收敛路线图（release train / Delivery / Final Verification）
+- `design/local-operator-console-from-pi-web.md` — Operator Console 设计输入；MVP 已随 `0.17.0`–`0.17.2` 发布
+- `design/taskspec-to-loop-agent-mapping.md` — TaskSpec → loop-agent task 兼容契约（文档镜像；runtime 真源在代码）
 
-完整列表见 `exec-plans/completed/README.md`。近期高频入口：
+已实现且仅作历史说明的设计见 `design/archive/`（例如 `design/archive/2026-07-14-loop-agent-self-update-notifier.md`）。
 
-- `exec-plans/completed/2026-07-18-observe-ops-surface-and-rich-timeline.md` — Observe 运营面/执行面重排、检查器半屏与富执行过程
-- `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 索引）
+## 进行中 / 近期完成
+
+进行中的完整列表见 `exec-plans/active/README.md`。当前高频 active：
+
+- `exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` — 全栈 release train（0.16.X → 0.17.X；Delivery 仍 open）
+- `exec-plans/active/2026-07-21-frontend-test-dag-success-rate.md` — frontend-test 成功率 hardening（formal smoke 待收口）
+- `exec-plans/active/2026-07-18-backend-test-live-provider-smoke.md` — 真实 provider smoke（blocked-external）
+- `exec-plans/active/2026-07-20-l5-test-report-metrics.md` — L-5 / coverage（实现完成，待审阅归档）
+- `exec-plans/active/2026-07-16-recursive-self-improvement-eval-lab.md` — Eval Lab（实现完成，可归档）
+
+完整 completed 列表与主题速览见 `exec-plans/completed/README.md`。近期高频归档：
+
+- `exec-plans/completed/2026-07-22-backend-markdown-gate-fix.md` — backend-test Markdown gate、traceability、中文生成与真实 Campaign 收口
+- `exec-plans/completed/2026-07-22-backend-test-markdown-first-8-node.md` — backend-test Markdown-first 8 节点
+- `exec-plans/completed/2026-07-22-backend-test-report-first-flow.md` — backend-test 报告优先 12 节点
+- `exec-plans/completed/2026-07-22-backend-test-intake-efficiency.md` — backend-test 首节点 intake 收敛
+- `exec-plans/completed/2026-07-21-console-phase-1-3.md` — Operator Console Phase 1–3 MVP（0.17.0–0.17.2）
+- `exec-plans/completed/2026-07-21-console-phase-0-5-task-contract.md` — Task Contract / operator envelope / DagSpec v4
+- `exec-plans/completed/2026-07-20-frontend-test-rag-outcome-hardening.md` — frontend-test 结果链与 UX 收口
+- `exec-plans/completed/2026-07-19-taskspec-workflow-routing.md` — TaskSpec workflow routing / Outcome / fullstack-v1（M0–M3）
+- `exec-plans/completed/2026-07-19-fullstack-dogfood-remediation.md` — 全栈 dogfood 源码修复基线（live 移交 active train）
+- `exec-plans/completed/2026-07-18-observe-ops-surface-and-rich-timeline.md` — Observe 运营面/执行面与富过程时间线
+- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime（历史主线入口）
 
 ## 设计思想来源
 
@@ -59,14 +98,18 @@
 
 ## 产物目录
 
-- `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 模板
+| 目录 | 角色 | 索引约定 |
+| --- | --- | --- |
+| `design/README.md` | 设计输入与路线图 | 已实现可迁 `design/archive/`；根设计页保留活输入 |
+| `exec-plans/active/README.md` | 进行中合同 | 源码仓库可放正文；npm 包只带 README 契约 |
+| `exec-plans/completed/README.md` | 已归档合同 | 导读 + 主题速览 + 全量；本身即归档位，不再套 archive |
+| `progress/README.md` | 跨会话 handoff | 导读 + 全量；短交接，不堆长证据 |
+| `reports/README.md` | 验证 / dogfood / merge / init-evolution 证据 | 导读 + 按类型子目录（`reports/feature/`、`reports/init-evolution/`、`reports/merge/`、`reports/fullstack-dogfood/`、`reports/dogfood/`）；活摘要 `reports/current-capability-summary.md` |
+| `decisions/README.md` | ADR | 0001–0004 等；决策边界以 ADR 正文为准 |
+| `skills/README.md` | repo-local skill registry | vetting notes |
+| `templates/` | 可复用规划 / 报告 / DAG 模板 | 见下方模板列表 |
+
+分工一句话：`exec-plans` 写合同，`progress` 写怎么接下一会话，`reports` 写可引用证据。
 
 ## 仓库 Skills
 
@@ -79,7 +122,7 @@
 - `templates/project-start-checklist.md` — 开工前检查清单
 - `templates/feature-spec.md` — 有边界的功能规格
 - `templates/sprint-contract.md` — 实现契约与验收标准
-- `templates/exec-plan.md` — 非平凡工作的执行计划
+- `templates/exec-plan.md` — 非平凡工作的执行计划（active → completed 落点说明见模板头）
 - `templates/progress-log.md` — 进度与交接日志
 - `templates/qa-report.md` — 验证与 QA 证据
 - `templates/worker-dogfood-setup.md` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
@@ -88,8 +131,8 @@
 - `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` — 跨分支合并的模式选择、功能保留、冲突解析、source drift、init/update 与 package surface 审计模板
+- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板（落盘 `reports/init-evolution/`）
+- `templates/branch-merge-report.md` — 跨分支合并报告模板（落盘 `reports/merge/`）
 - `templates/adr.md` — 架构决策记录（ADR）
 
 ## 维护
@@ -112,3 +155,5 @@ Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文
 ```bash
 bash scripts/ci.sh
 ```
+
+根目录活契约正文只在行为/命令面真正变化时修改；本索引只负责入口与导航，不复述子目录全量列表。

package/docs/architecture/README.md

@@ -2,6 +2,8 @@
 
 本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
 
+**维护日：2026-07-22** — 索引与演进叙述对齐仓库头 `@tea-agent/loop-agent@0.17.2`（Task Contract / Local Operator Console / 专用 taskKind DAG / reports 分子目录）。边界表仍以 `runtime-boundaries.md` 与 `scripts/check-*.sh` 为准。
+
 ## 阅读路径
 
 建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
@@ -9,18 +11,20 @@
 1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
 2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
 3. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
-4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe。
+4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature、Observe 与 Console。
 5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
 6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
 
 ## 事实与规划的区分
 
-- **当前事实源**：`src/` 源码、发布 CLI、`ai_workspace/loop-agent/exec-plans/completed/`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0003。
-- **规划/设计输入**：`ai_workspace/loop-agent/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
+- **当前事实源**：`src/` 源码、发布 CLI、`docs/exec-plans/completed/`、`docs/reports/current-capability-summary.md`、ADR 0001–0005。
+- **规划/设计输入**：`docs/design/`（含 fullstack / Console / 六个月规划等）。页首校准条与 completed plan 未背书前，**不是**已实现证明。
+- 目标项目初始化后，治理根目录通常为 `ai_workspace/loop-agent/`（与本源仓 `docs/` 同源契约投影）；站上用法在 `website/docs/`。
 - 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
 
 ## 与其他文档的分工
 
 - 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
 - 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
-- 本目录文档随发布包发布（npm `files` 显式条目 + `ai_workspace/loop-agent/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+- 产物索引：`docs/exec-plans/*`、`docs/progress/`、`docs/reports/`（reports 按类型子目录；见各目录 README）。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `docs/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。

package/docs/architecture/dag-execution.md

@@ -34,12 +34,19 @@ src/commands/dag-validate.ts  runDagValidate
   → src/application/dag/validate-dag.ts  validateDagUseCase
 ```
 
-### runtime contract preflight 与 repair writer 解析
+### runtime contract preflight、repair writer 与 Task Contract binding
 
 - `src/workflows/dag/runtime-contract.ts` `assertRuntimeContractCompatible` 依据 controller capabilities（`DAG_CONTROLLER_CAPABILITIES`：`agentRuntime="pi-only"`、`repairWriterProtocol="explicit-node-v1"`）校验 DagSpec v3 必需的 `runtimeContract`。v3 让旧 controller 在解析阶段拒绝；新 controller 的 `validateDagUseCase`、`runDagUseCase`、`runDag` 与 resume 还会校验 capability 和可选最低版本，不兼容在任何节点执行前 fail-fast。legacy v1/v2 DagSpec 可读但没有 v3 握手。
+- **DagSpec v4（0.17.0+）**：新 writer 生成默认携带 `taskContractBinding`（managed Task Contract）。exclusive writer（`writePolicy: "exclusive"`）启动门禁要求 v4 binding；只读 / static / shell 历史 DAG 可继续执行。operator capabilities 声明 `generatedSpecVersion: 4` 与 binding schema（`src/shared/operator/capabilities.ts`）。CLI 面见 `loop-agent task contract *` 与 Console confirm-run。
 - `src/workflows/dag/repair-artifact.ts` `resolveRepairTaskForGate` 解析 `shell.repairArtifactGate`：优先显式 `repairNodeId`，否则推导唯一的下游受治理 Pi writer（`repairWriterContractIssues` 校验 executor/toolProfile/writePolicy/path 契约）。`validate.ts` 与 `node-execution.ts` 复用同一 resolver，runtime 不再按节点名硬编码。
 - `src/workflows/dag/controller-identity.ts` 在 run 创建前要求 controller identity 可解析，再由 `captureControllerIdentity` 冻结到 `<runDir>/controller-identity.json`；`verifyControllerIdentityForResume` 在 resume 前重新校验并对漂移、篡改或 legacy-unpinned run fail closed。
 
+### 专用 taskKind 与模板选择（架构摘要）
+
+- `initHybridDagFromTask` 按 `task.json.taskKind`（及前端需求自动分类）选择专用拓扑：`frontend-implementation`、`frontend-test`、`backend-test`、`knowledge-sync`、`knowledge-graph-bootstrap` 等；默认 `standard` 走 governance profile 通用实现链。
+- **backend-test（0.17.x）**：Markdown-first 固定短链（环境硬门 → Markdown 用例/Review → 单次 pytest + HTML → 报告与 L-5）；不在本页展开节点清单，见 `docs/design/backend-test-workflow.md` 与 completed markdown-first plan。
+- 专用模板不是新的 governance profile：风险等级仍由 profile 规则判断；写边界仍受 `allowedPaths` / `forbiddenPaths` / `writeSet` 约束。
+
 ## rank 调度
 
 拓扑排序与按 rank 执行的符号归属（校准版，勿笼统归到 `runner.ts`）：