@tea-agent/loop-agent 0.16.1-beta.1 → 0.16.1

package/dist/workflows/dag/runner.js

@@ -1,8 +1,10 @@
 import { readdir, readFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import path from "node:path";
+import { isHardBudgetBreached, resolveEffectiveMaxConcurrent, } from "../../application/evaluation/budget.js";
 import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-store.js";
 import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/runtime.js";
+import { assertFrozenBudget, initRunBudgetLedger, preflightBudgetOrBreach, recordFinishedNodeBudget, writeBudgetLedgerArtifacts, } from "./budget-enforcement.js";
 import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
 import { moveToCompletedRunDir, moveToPausedRunDir, prepareActiveRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
 import { createDagNodeExecutor } from "./executor-registry.js";
@@ -120,7 +122,7 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
                 : {}),
         };
     }
-    return {
+    const state = {
         version: 1,
         title: spec.title,
         runId,
@@ -147,6 +149,8 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
             }
             : {}),
     };
+    initRunBudgetLedger(state, spec.budget);
+    return state;
 }
 export function assertFrozenEvaluationBinding(spec, state) {
     const declared = spec.evaluation;
@@ -183,7 +187,7 @@ export async function runDag(spec, opts) {
         controllerVersion: runningIdentity.packageVersion,
     });
     const { ranks } = topoSortToRanks(spec);
-    const maxConcurrent = Math.max(1, opts.maxConcurrent ?? 4);
+    const { maxConcurrent } = resolveEffectiveMaxConcurrent(Math.max(1, opts.maxConcurrent ?? 4), spec.budget);
     let runId = opts.runId;
     if (runId) {
         for (const warning of validateDagRunIdFormat(runId).warnings) {
@@ -268,6 +272,7 @@ export async function resumeDagRun(opts) {
         throw new Error(`dag run ${opts.runId} is already terminal (status=${state.status})`);
     }
     assertFrozenEvaluationBinding(spec, state);
+    assertFrozenBudget(spec.budget, state.budget, state.runId);
     // Runtime contract + controller identity must be re-verified before executing
     // any remaining node on resume; drift fails closed.
     const runningIdentity = resolveRunningControllerIdentity();
@@ -311,7 +316,7 @@ export async function resumeDagRun(opts) {
     catch (error) {
         throw new Error(`skill snapshot validation failed on resume: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const maxConcurrent = Math.max(1, opts.maxConcurrent ?? 4);
+    const { maxConcurrent } = resolveEffectiveMaxConcurrent(Math.max(1, opts.maxConcurrent ?? 4), spec.budget);
     state.status = "running";
     const resumedAt = new Date().toISOString();
     state.runner = {
@@ -410,23 +415,43 @@ async function executeDagCheckpoint(input) {
                     tasksById,
                     meta: { runDir, runId: state.runId, spec },
                 }),
-                executeScheduledNode: (nodeId, executeNode, onPause) => executeDagNode({
-                    nodeId,
-                    tasksById,
-                    state,
-                    spec,
-                    cwd,
-                    runDir,
-                    executeNode,
-                    executeDynamicNode,
-                    observer: input.observer,
-                    persistState,
-                    onPause,
-                }),
+                executeScheduledNode: async (nodeId, executeNode, onPause) => {
+                    if (isHardBudgetBreached(state.budgetLedger))
+                        return;
+                    const preBreach = preflightBudgetOrBreach(state);
+                    if (preBreach && isHardBudgetBreached(state.budgetLedger)) {
+                        await writeBudgetLedgerArtifacts(runDir, state.budgetLedger);
+                        await persistState();
+                        return;
+                    }
+                    await executeDagNode({
+                        nodeId,
+                        tasksById,
+                        state,
+                        spec,
+                        cwd,
+                        runDir,
+                        executeNode,
+                        executeDynamicNode,
+                        observer: input.observer,
+                        persistState,
+                        onPause,
+                    });
+                    const node = state.nodes[nodeId];
+                    if (node &&
+                        (node.status === "FINISHED" || node.status === "ERROR")) {
+                        recordFinishedNodeBudget(state, node);
+                        await writeBudgetLedgerArtifacts(runDir, state.budgetLedger);
+                        await persistState();
+                    }
+                },
             });
             if (pausedByNodeId) {
                 break;
             }
+            if (isHardBudgetBreached(state.budgetLedger)) {
+                break;
+            }
             const convergenceDecision = await runConvergencePassController({
                 spec,
                 state,
@@ -446,6 +471,7 @@ async function executeDagCheckpoint(input) {
         }
         state.finishedAt = new Date().toISOString();
         const runDirBeforeTransfer = runDir;
+        await writeBudgetLedgerArtifacts(runDir, state.budgetLedger);
         if (pausedByNodeId) {
             state.status = "paused";
             await persistState();
@@ -466,6 +492,7 @@ async function executeDagCheckpoint(input) {
         if (state.convergence) {
             relocateConvergenceArtifactPaths(state.convergence, runDirBeforeTransfer, runDir);
         }
+        await writeBudgetLedgerArtifacts(runDir, state.budgetLedger);
         await persistState({ allowCompletedFactsWrite: true });
         return {
             title: spec.title,

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

@@ -3,9 +3,9 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import { writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { resolveContextPolicy } from "./context-policy.js";
 import { buildDagNodePromptEnvelope } from "./prompt.js";
-import { DEFAULT_SKILL_INSTRUCTION_MAX_CHARS, DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS, resolveDagSkillInstructions, } from "./skill-instructions.js";
-import { resolveDagNodeSkills } from "./skills.js";
+import { resolveDagSkillInstructions, } from "./skill-instructions.js";
 export const SKILL_SNAPSHOT_SCHEMA_VERSION = 1;
 export const SKILL_SNAPSHOT_RESOLVER_VERSION = 1;
 export const SKILL_SNAPSHOT_REL_PATH = ".runtime/skill-snapshot.json";
@@ -117,11 +117,13 @@ function profileId(input) {
 export function buildDagSkillSnapshotProfileRequest(spec, task) {
     if (task.executor !== "pi")
         return undefined;
+    const policy = resolveContextPolicy(spec);
+    const budget = policy.resolveSkillInstructionBudget(task);
     const request = {
-        skills: [...resolveDagNodeSkills(spec, task)],
-        includeLearnedPatterns: task.role === "implementer",
-        perSkillMaxChars: DEFAULT_SKILL_INSTRUCTION_MAX_CHARS,
-        totalMaxChars: DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS,
+        skills: [...policy.resolveSkills(spec, task)],
+        includeLearnedPatterns: budget.includeLearnedPatterns,
+        perSkillMaxChars: budget.perSkillMaxChars,
+        totalMaxChars: budget.totalMaxChars,
     };
     return { id: profileId(request), ...request };
 }
@@ -511,7 +513,8 @@ function stripPromptText(instruction) {
     return metadata;
 }
 export function buildNodePromptFromSnapshot(input) {
-    const skillNames = resolveDagNodeSkills(input.spec, input.task);
+    const policy = resolveContextPolicy(input.spec);
+    const skillNames = policy.resolveSkills(input.spec, input.task);
     const resolvedSkillInstructions = resolveNodeSkillsFromSnapshot(input.snapshot, input.spec, input.task);
     return {
         prompt: buildDagNodePromptEnvelope({
@@ -520,6 +523,7 @@ export function buildNodePromptFromSnapshot(input) {
             upstream: input.upstream,
             resolvedSkills: skillNames,
             resolvedSkillInstructions,
+            maxUpstreamChars: policy.resolveMaxUpstreamChars(input.task),
         }),
         resolvedSkills: resolvedSkillInstructions.map(stripPromptText),
     };

package/dist/workflows/dag/types.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { campaignBudgetSchema, } from "../../application/evaluation/budget.js";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
 import { dagRetryPolicySchema } from "./retry-policy.js";
 export const dagComplexitySchema = z.enum(["HIGH", "MED", "LOW"]);
@@ -105,12 +106,18 @@ export const dagWritePolicySchema = z.enum([
     "exclusive",
     "none",
 ]);
+export const contextPolicyIdSchema = z.enum([
+    "baseline-v1",
+    "role-specialized-v1",
+]);
 export const dagDefaultsSchema = z
     .object({
     executor: dagNodeExecutorSchema.optional(),
     model: z.string().optional(),
     piBackend: z.enum(["sdk-first", "cli-only"]).optional(),
     contextProfile: z.string().optional(),
+    /** Eval Lab ContextPolicy seam; default baseline-v1 when omitted. */
+    contextPolicyId: contextPolicyIdSchema.optional(),
     skills: z.array(z.string()).optional(),
     writePolicy: dagWritePolicySchema.optional(),
 })
@@ -267,7 +274,6 @@ export const dagTaskSchema = z.object({
     shell: dagShellConfigSchema.optional(),
     static: dagStaticConfigSchema.optional(),
     outputContract: z.string().optional(),
-    firstProtocolLine: z.string().min(1).optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),
@@ -301,6 +307,8 @@ export const dagEvaluationBindingSchema = z
     taskRef: z.string().min(1).optional(),
 })
     .strict();
+/** Eval Lab Campaign Budget (W3.4); enforced by runner ledger when mode=hard. */
+export const dagBudgetSchema = campaignBudgetSchema;
 export const dagSourceBindingSchema = z.object({
     schemaVersion: z.literal(1),
     taskId: z.string().min(1),
@@ -321,6 +329,8 @@ export const dagSpecSchema = z
     title: z.string().min(1),
     runtimeContract: dagRuntimeContractSchema.optional(),
     evaluation: dagEvaluationBindingSchema.optional(),
+    /** Optional hard/record-only budget; requires version 3. */
+    budget: dagBudgetSchema.optional(),
     sourceBinding: dagSourceBindingSchema.optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
@@ -341,6 +351,13 @@ export const dagSpecSchema = z
             path: ["evaluation"],
         });
     }
+    if (spec.budget && spec.version !== 3) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "budget requires DagSpec version 3",
+            path: ["budget"],
+        });
+    }
     if (spec.runtimeContract && spec.version !== 3) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,

package/dist/workflows/dag/validate.js

@@ -229,7 +229,10 @@ function validateRepairArtifactGateConfig(task, spec, issues) {
         candidate.role === "reviewer" &&
         !candidate.decisionGate?.enabled &&
         candidate.writePolicy === "read-only" &&
-        (candidate.outputContract?.includes("VERDICT:") ?? false));
+        (candidate.outputContract?.includes("VERDICT:") ?? false) &&
+        // Format recovery / write-set format-repair nodes also emit VERDICT but
+        // are not the primary content review after hard verification.
+        !/(?:-format-repair-pi|-verdict-recovery-pi)$/.test(candidate.id));
     if (reviewCandidates.length !== 1) {
         issues.push({
             type: "invalid-repair-artifact-gate-config",
@@ -343,6 +346,17 @@ function validateTaskWritePolicy(task, spec, issues) {
         return;
     }
     for (const entry of writeSet) {
+        const normalizedEntry = entry.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+        if (writePolicy === "exclusive" &&
+            (normalizedEntry === "**" ||
+                normalizedEntry === "./**" ||
+                normalizedEntry === "*")) {
+            issues.push({
+                type: "write-set-unbounded",
+                message: `task ${task.id} writeSet entry "${entry}" is unbounded; exclusive writers must use concrete paths or limited globs`,
+            });
+            continue;
+        }
         if (forbiddenPaths.length > 0 &&
             writeSetEntryHitsForbidden(entry, forbiddenPaths)) {
             issues.push({

package/docs/README.md

@@ -13,6 +13,8 @@
 - `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` — 架构文档目录索引与阅读路径
 - `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
@@ -84,7 +86,7 @@
 - `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/branch-merge-report.md` — 跨分支合并的模式选择、功能保留、冲突解析、source drift、init/update 与 package surface 审计模板
 - `templates/adr.md` — 架构决策记录（ADR）
 
 ## 维护

package/docs/architecture/runtime-boundaries.md

@@ -85,14 +85,15 @@ Governance (scripts/check-*.sh, src/governance/)
 - **职责**：TaskSpec 校验与物化、Task Pool batch/retry/morning report under `.harness/task-pool/`、失败路由，以及只读 Observe 事件/快照/UI；实际 DAG 执行通过 `LoopAgentClient` 启动已发布的 `loop-agent` 子进程。自 0.8.0 起该目录是唯一受支持的 Task Pool runtime root，旧路径不读取、不迁移、不合并、不重映射。
 - **controller identity**：写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前解析并冻结 schemaVersion 1 identity，包括 package name/version、绝对 entry/real entry、直接可执行 launch spec、binary SHA-256 和覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint。expected version/fingerprint 不匹配时 fail-fast；后续 spawn 不重新查询 PATH。
 - **证据传播**：canonical Worker record、Task Pool run、batch/Feature、QA/final evidence 可选携带同一 identity；只有所有相关层都省略 identity 时才按 legacy evidence 接受，部分缺失或锚点不一致会拒绝。
-- **允许依赖**：TaskSpec、Task Pool、observability、Node filesystem/path 与明确的 shared/task contract；它不是第二套 executor 或 DAG kernel。
+- **Worker-aware recovery**：`agent-worker task reconcile --action abandon` 由 Worker 持有 Worker run ↔ DAG run association，再调用 DAG-kernel reconcile（`src/workflows/dag/reconcile-run.ts`）并把 Task Pool 投影为 `Failed` + recovery evidence。低层 `loop-agent dag reconcile-run` 只维护 DAG lifecycle，不搜索/修改 Task Pool。应急入口 `pool mark-failed` 同属 Worker，禁止覆盖 `Done`。
+- **允许依赖**：TaskSpec、Task Pool、observability、Node filesystem/path、明确的 shared/task contract，以及只读/共享的 `src/workflows/dag/**` reconcile/lifecycle helpers；它不是第二套 executor 或 DAG kernel。
 - **禁止**：in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`。
 
 ### Infrastructure / Store
 
 - **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
 - **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。DAG run 自有的 `.runtime/skill-snapshot.json` 随 lifecycle 目录整体迁移，state 只保存相对 ref 和 hash，不保存 active/paused/completed 绝对路径。
-- **DAG recovery mutation**：`dag reconcile-run` 是显式 operator 边界；默认仅检查，只有给出 action + reason 且 runner 已证明停止时才能保存原始快照、写 terminal reconciliation facts 并迁移 lifecycle。Observe、status 和 doctor 始终只读。
+- **DAG recovery mutation**：`dag reconcile-run` 是显式 operator 边界；默认仅检查，只有给出 action + reason 且 runner 已证明停止时才能保存原始快照、写 terminal reconciliation facts 并迁移 lifecycle。Observe、status 和 doctor 始终只读。Task Pool 侧的 abandon/Failed 投影由 `agent-worker task reconcile` 持有，不得让 DAG kernel 反向依赖 Worker。
 - **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
 
 ### Governance

package/docs/init-surface.manifest.json

@@ -11,6 +11,7 @@
     "docs/harness-methodology-tdd.md",
     "docs/harness-methodology-verification.md",
     "docs/harness-methodology-debugging.md",
+    "docs/local-development-environment.md",
     "docs/init-surface.manifest.json",
     "docs/architecture/runtime-boundaries.md",
     "docs/architecture/README.md",
@@ -39,6 +40,7 @@
     "docs/templates/product-line/test-plan.md",
     "docs/templates/product-line/task-graph.yaml",
     "docs/templates/product-line/task.yaml",
+    "docs/templates/product-line/feature.yaml",
     "docs/templates/product-line/closeout.yaml",
     "docs/templates/product-line/links.md",
     "scripts/kb-bootstrap-init-skeleton.sh",
@@ -106,6 +108,7 @@
     "docs/templates/product-line/test-plan.md",
     "docs/templates/product-line/task-graph.yaml",
     "docs/templates/product-line/task.yaml",
+    "docs/templates/product-line/feature.yaml",
     "docs/templates/product-line/closeout.yaml",
     "docs/templates/product-line/links.md",
     "scripts/check-skill-entry.sh",
@@ -175,6 +178,7 @@
     "docs/templates/product-line/test-plan.md": "copied",
     "docs/templates/product-line/task-graph.yaml": "copied",
     "docs/templates/product-line/task.yaml": "copied",
+    "docs/templates/product-line/feature.yaml": "copied",
     "docs/templates/product-line/closeout.yaml": "copied",
     "docs/templates/product-line/links.md": "copied",
     "scripts/check-skill-entry.sh": "generated",

package/docs/local-development-environment.md

@@ -0,0 +1,52 @@
+# 本地开发环境排障
+
+本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](verification-matrix.md) 为准。
+
+## Cursor Cloud
+
+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/...'
+```
+
+在 Cursor Cloud 中执行安装或验证前，先切换到已配置的 Node.js 22：
+
+```bash
+nvm use 22
+node --version
+npm ci
+```
+
+当前 VM 预装版本为 v22.22.2；应以 `node --version` 的实际输出为准，不依赖交互式 shell 的默认 PATH。
+
+### Git 提交签名导致测试超时
+
+Cursor Cloud 的全局 Git 配置可能通过 `cursor-git-ssh-keygen` 为每次提交签名（`gpg.format=ssh`、`commit.gpgsign=true`）。该 helper 可能阻塞 7–30 秒，使会在临时仓库中频繁提交的测试（尤其 `test/worker/delivery/**`、`test/worker/feature/**`）触发 15/30 秒超时。
+
+运行 `npm test` 或其他 Git 密集型测试前，可仅对子进程关闭提交签名：
+
+```bash
+export GIT_CONFIG_COUNT=1
+export GIT_CONFIG_KEY_0=commit.gpgsign
+export GIT_CONFIG_VALUE_0=false
+npm test
+```
+
+也可以只在当前目标仓库设置：
+
+```bash
+git config commit.gpgsign false
+```
+
+该设置只用于本地开发和测试稳定性，不应写入仓库代码、模板或发布包配置。
+
+## 维护规则
+
+- 仅把可复现、会反复影响开发或验证的环境问题写入本文。
+- 通用且跨环境成立的要求应写入开发原则或验证矩阵，不应堆在本页。
+- 问题消失或基础镜像修复后，应删除过期说明，避免把临时环境状态长期固化为项目规则。

package/docs/templates/agent-dag.schema.json

@@ -366,11 +366,6 @@
           "type": "string",
           "minLength": 1
         },
-        "firstProtocolLine": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Optional protocol prefix whose first matching Pi assistant-output line is promoted to the canonical first line. Missing matches are not synthesized."
-        },
         "allowedPaths": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 },

package/docs/templates/agent-dag.supervised-implementation.json

@@ -542,11 +542,30 @@
       "subtask_prompt_markdown": "./agent-dag-review-verdict.prompt.md"
     },
     {
-      "id": "review-gate-shell",
+      "id": "review-verdict-recovery-pi",
       "depends_on": [
         "review-pi"
       ],
       "complexity": "LOW",
+      "executor": "pi",
+      "role": "reviewer",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown whose first non-empty line is exactly VERDICT: pass or VERDICT: request-revision, followed by the original review findings without substantive changes. No file writes.",
+      "subtask_prompt": "Normalize the output format of review-pi; this is the single read-only format-recovery attempt for the review verdict protocol. Preserve an existing valid VERDICT exactly. Do not invent VERDICT: pass from natural-language approval. If ambiguous, emit VERDICT: request-revision. Do not re-review code or edit files."
+    },
+    {
+      "id": "review-gate-shell",
+      "depends_on": [
+        "review-verdict-recovery-pi"
+      ],
+      "complexity": "LOW",
       "executor": "shell",
       "role": "verifier",
       "writePolicy": "read-only",
@@ -557,11 +576,11 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Deterministic review verdict gate: exit 0 only when review-pi first non-empty assistant output line is pass.",
-      "subtask_prompt": "Deterministic gate: block decision gate unless review-pi emitted VERDICT: pass.",
+      "outputContract": "Deterministic review verdict gate: exit 0 only when review-verdict-recovery-pi first non-empty assistant output line is pass.",
+      "subtask_prompt": "Deterministic gate: block decision gate unless review-verdict-recovery-pi emitted VERDICT: pass.",
       "shell": {
         "verdictGate": {
-          "fromNodeId": "review-pi",
+          "fromNodeId": "review-verdict-recovery-pi",
           "accept": [
             "VERDICT: pass"
           ],

package/docs/templates/branch-merge-report.md

@@ -6,6 +6,8 @@ Target before merge: `<full SHA>`
 Source: `<source-ref>@<full SHA>`
 Merge base: `<full SHA>`
 Merge commit: `<full SHA or follow-up commit reference>`
+Merge mode: `quick | standard | deep`
+Mode rationale: `<why this mode is sufficient>`
 
 ## Naming Convention
 
@@ -18,6 +20,12 @@ Use `YYYY-MM-DD-origin-<source>-into-<target>-<source-short-sha>.md` under `docs
 - Predicted conflicts: `<count and files>`.
 - Baseline verification: `<commands and results>`.
 
+## Final Source Drift Check
+
+- Final fetch: `<command and timestamp>`.
+- Final source tip: `<full SHA>`.
+- Source advanced during work: `<no | yes, with re-audit details>`.
+
 ## Incoming Capabilities
 
 | Capability | Key files / contracts | Expected user or runtime result | Verification |
@@ -80,6 +88,12 @@ Record overlapping or high-risk files that Git merged without conflict. These ar
 
 Add focused tests and real init/update/browser/CLI smokes required by the merged capabilities.
 
+## Mode Completion Check
+
+- Required gates for selected mode: `<list>`.
+- Passed gates: `<list>`.
+- Any mode upgrade during execution: `<no | from quick/standard to standard/deep, with reason>`.
+
 ## Residual Risk
 
 - `<unverified external environment, performance, migration, or compatibility risk>`

package/docs/templates/evaluation/campaign-budget-v1.json

@@ -0,0 +1,12 @@
+{
+	"schemaVersion": 1,
+	"mode": "hard",
+	"limits": {
+		"maxTokens": 2000000,
+		"maxWallTimeMs": 86400000,
+		"maxExecutorCalls": 500,
+		"maxRepairPasses": 50,
+		"maxConcurrency": 2,
+		"maxContextChars": 120000
+	}
+}

package/docs/templates/evaluation/campaign-dogfood-v0.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "campaignId": "camp-dogfood-context-policy-ab",
+  "createdAt": "2026-07-19T00:00:00.000Z",
+  "status": "prepared",
+  "policyVersion": "promotion-policy-v1",
+  "incumbentCandidateId": "REPLACE_INCUMBENT_CANDIDATE_ID",
+  "challengerCandidateIds": ["REPLACE_CHALLENGER_CANDIDATE_ID"],
+  "corpusId": "corpus-dogfood-v0",
+  "corpusHash": "REPLACE_AFTER_CORPUS_REGISTER",
+  "privateVerifierId": "pv-dogfood-v0",
+  "privateVerifierManifestHash": "REPLACE_AFTER_PRIVATE_VERIFIER_REGISTER",
+  "budget": {
+    "schemaVersion": 1,
+    "mode": "hard",
+    "limits": {
+      "maxExecutorCalls": 500,
+      "maxWallTimeMs": 86400000,
+      "maxRepairPasses": 50,
+      "maxConcurrency": 2
+    }
+  },
+  "notes": "M4 dogfood: single-variable Context Policy A/B. Replace candidate/corpus/privateVerifier hashes after register. held_out cells are promotion_gate_only."
+}

package/docs/templates/evaluation/campaign-evidence-v1.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "campaignId": "campaign-dogfood-v0",
+  "challengerCandidateId": "cand-challenger-example",
+  "cells": [
+    {
+      "candidateId": "cand-baseline-example",
+      "taskRef": "synthetic/private-1",
+      "seed": 1,
+      "split": "private",
+      "verifyPassed": false
+    },
+    {
+      "candidateId": "cand-challenger-example",
+      "taskRef": "synthetic/private-1",
+      "seed": 1,
+      "split": "private",
+      "verifyPassed": true
+    },
+    {
+      "candidateId": "cand-baseline-example",
+      "taskRef": "synthetic/heldout-1",
+      "seed": 1,
+      "split": "held_out",
+      "verifyPassed": true
+    },
+    {
+      "candidateId": "cand-challenger-example",
+      "taskRef": "synthetic/heldout-1",
+      "seed": 1,
+      "split": "held_out",
+      "verifyPassed": true
+    }
+  ],
+  "diffs": [],
+  "verifyCommands": {
+    "incumbent": ["npm test", "npm run typecheck"],
+    "challenger": ["npm test", "npm run typecheck"]
+  },
+  "budgetStatus": {
+    "incumbent": "ok",
+    "challenger": "ok"
+  }
+}

package/docs/templates/evaluation/context-policy-baseline-v1.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "policyId": "baseline-v1",
+  "description": "Current DAG context assembly: shared upstream char budget, role skill defaults, learned patterns only for implementer.",
+  "knobs": {
+    "maxUpstreamCharsByRole": {
+      "default": 2000
+    },
+    "includeLearnedPatternsRoles": ["implementer"],
+    "perSkillMaxCharsByRole": {
+      "default": 3000
+    },
+    "totalMaxCharsByRole": {
+      "default": 12000
+    }
+  }
+}

package/docs/templates/evaluation/context-policy-role-specialized-v1.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "policyId": "role-specialized-v1",
+  "description": "Role-specialized upstream and skill-instruction budgets; skill names still resolve via baseline merge order.",
+  "knobs": {
+    "maxUpstreamCharsByRole": {
+      "default": 2000,
+      "scout": 1200,
+      "reviewer": 1200,
+      "implementer": 3000,
+      "verifier": 1600,
+      "closeout": 1600,
+      "planner": 2000,
+      "supervisor": 2000
+    },
+    "includeLearnedPatternsRoles": ["implementer", "closeout"],
+    "perSkillMaxCharsByRole": {
+      "default": 3000,
+      "scout": 2500,
+      "implementer": 3500
+    },
+    "totalMaxCharsByRole": {
+      "default": 12000,
+      "scout": 10000,
+      "implementer": 14000
+    }
+  }
+}