@tea-agent/loop-agent 0.28.2-beta.1 → 0.28.3

package/dist/worker/scheduler/workspace-adapter.js

@@ -0,0 +1,91 @@
+import { access, symlink, unlink } from "node:fs/promises";
+import path from "node:path";
+import { ensureOwnedWorktree, verifyOwnedWorktree, } from "../../task/worktree.js";
+import { getSchedulerRoot } from "./paths.js";
+export function defaultNightWorktreeRelativePath(scheduleId) {
+    return path.posix.join(".worktrees", "night", scheduleId);
+}
+export function defaultNightBranch(scheduleId) {
+    return `night/${scheduleId}`;
+}
+/**
+ * Create or reuse a schedule-owned worktree under control repo.
+ * Does not copy secrets/.env. Optional node_modules symlink only.
+ */
+export async function prepareNightWorkspace(spec) {
+    const relativeWorktreePath = spec.worktreePath ?? defaultNightWorktreeRelativePath(spec.scheduleId);
+    const branch = spec.branch ?? defaultNightBranch(spec.scheduleId);
+    const expectedBranch = defaultNightBranch(spec.scheduleId);
+    if (branch !== expectedBranch) {
+        throw new Error(`night worktree branch must be ${expectedBranch}, got ${branch}`);
+    }
+    const absolutePath = path.isAbsolute(relativeWorktreePath)
+        ? relativeWorktreePath
+        : path.resolve(spec.controlRepoRoot, relativeWorktreePath);
+    // Ensure parent of worktree root exists (and keep scheduler root alive).
+    void getSchedulerRoot(spec.controlRepoRoot);
+    const ensured = await ensureOwnedWorktree(spec.controlRepoRoot, {
+        worktreePath: absolutePath,
+        branch,
+        baseBranch: spec.baseBranch,
+        baseCommit: spec.baseCommit,
+        scheduleId: spec.scheduleId,
+        ...(spec.ownershipToken ? { ownershipToken: spec.ownershipToken } : {}),
+        ...(spec.now ? { now: spec.now } : {}),
+    });
+    let nodeModulesLinked = false;
+    if (spec.hydrateNodeModules !== false) {
+        nodeModulesLinked = await linkNodeModulesIfPresent(spec.controlRepoRoot, ensured.path);
+    }
+    const relative = path
+        .relative(spec.controlRepoRoot, ensured.path)
+        .split(path.sep)
+        .join("/") || relativeWorktreePath;
+    return {
+        ...ensured,
+        relativeWorktreePath: relative.startsWith("..") ? ensured.path : relative,
+        relativeBranch: branch,
+        nodeModulesLinked,
+    };
+}
+export async function revalidateNightWorkspace(input) {
+    const result = await verifyOwnedWorktree({
+        repoRoot: input.controlRepoRoot,
+        worktreePath: input.worktreePath,
+        scheduleId: input.scheduleId,
+        branch: input.branch,
+        baseCommit: input.baseCommit,
+        ownershipToken: input.ownershipToken,
+    });
+    return { head: result.head };
+}
+async function linkNodeModulesIfPresent(controlRepoRoot, worktreePath) {
+    const host = path.join(controlRepoRoot, "node_modules");
+    const target = path.join(worktreePath, "node_modules");
+    try {
+        await access(host);
+    }
+    catch {
+        return false;
+    }
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        // continue to link
+    }
+    try {
+        await symlink(host, target, "junction");
+        return true;
+    }
+    catch {
+        try {
+            await unlink(target);
+        }
+        catch {
+            // ignore
+        }
+        return false;
+    }
+}

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -570,106 +570,6 @@ function canonicalizeVerificationTargetAliases(value) {
         : record.requirements;
     return { ...record, requirements };
 }
-/**
- * Model-written evidence gaps are hypotheses, not authoritative coverage
- * facts. If the plan contains a real verification target that explicitly
- * names a requirement, the executor can prove that the requirement has a
- * verification path even when the model forgot to wire the target into the
- * requirement entry or conservatively marked its gap as blocking.
- *
- * Keep gaps blocking when that proof cannot be derived. This is deliberately
- * narrow: it uses only sourceBinding requirement IDs and structurally present
- * verification targets, and never invents a command, file, or target.
- */
-function deriveFrontendVerificationCoverage(value, canonicalBinding) {
-    const record = asRecord(value);
-    if (!record)
-        return value;
-    const rawTargets = Array.isArray(record.verificationTargets)
-        ? record.verificationTargets
-        : [];
-    const targetIds = new Set(rawTargets
-        .map((item) => asRecord(item))
-        .filter((item) => Boolean(item))
-        .map((item) => asString(item.id))
-        .filter(Boolean));
-    const targetIdsByRequirement = new Map();
-    for (const item of rawTargets) {
-        const target = asRecord(item);
-        if (!target)
-            continue;
-        const targetId = asString(target.id);
-        const commandLabel = asString(target.commandLabel) || asString(target.command);
-        const file = asString(target.file);
-        // A target is usable evidence only when it has an identity, command and
-        // file. The strict schema will validate the final shape afterwards.
-        if (!targetId || !commandLabel || !file)
-            continue;
-        for (const requirementId of asStringArray(target.requirementIds)) {
-            const canonicalId = canonicalizeRequirementId(requirementId);
-            if (!canonicalBinding.requirementIds.includes(canonicalId))
-                continue;
-            const ids = targetIdsByRequirement.get(canonicalId) ?? [];
-            if (!ids.includes(targetId))
-                ids.push(targetId);
-            targetIdsByRequirement.set(canonicalId, ids);
-        }
-    }
-    const provenRequirementIds = new Set(targetIdsByRequirement.keys());
-    const requirements = Array.isArray(record.requirements)
-        ? record.requirements.map((item) => {
-            const requirement = asRecord(item);
-            if (!requirement)
-                return item;
-            const requirementId = canonicalizeRequirementId(asString(requirement.id));
-            const inferredTargetIds = targetIdsByRequirement.get(requirementId) ?? [];
-            const existingTargetIds = asStringArray(requirement.verificationTargetIds)
-                .filter((id) => targetIds.has(id));
-            const verificationTargetIds = [...new Set([
-                    ...existingTargetIds,
-                    ...inferredTargetIds,
-                ])];
-            const evidenceGap = asRecord(requirement.evidenceGap);
-            const hasProof = provenRequirementIds.has(requirementId);
-            return {
-                ...requirement,
-                ...(verificationTargetIds.length > 0 ? { verificationTargetIds } : {}),
-                ...(hasProof
-                    ? (evidenceGap ? { evidenceGap: { ...evidenceGap, blocking: false } } : {})
-                    : {
-                        evidenceGap: {
-                            requirementId,
-                            description: `No executable verification target can be derived for ${requirementId}`,
-                            blocking: true,
-                        },
-                    }),
-            };
-        })
-        : record.requirements;
-    const modelEvidenceGaps = Array.isArray(record.evidenceGaps)
-        ? record.evidenceGaps.map((item) => {
-            const gap = asRecord(item);
-            if (!gap)
-                return item;
-            const requirementId = canonicalizeRequirementId(asString(gap.requirementId));
-            // Model gaps are advisory. Blocking status is reconstructed below
-            // from the source binding and executable verification targets.
-            return { ...gap, blocking: false };
-        })
-        : [];
-    const derivedBlockingGaps = canonicalBinding.requirementIds
-        .filter((requirementId) => !provenRequirementIds.has(requirementId))
-        .map((requirementId) => ({
-        requirementId,
-        description: `No executable verification target can be derived for ${requirementId}`,
-        blocking: true,
-    }));
-    return {
-        ...record,
-        requirements,
-        evidenceGaps: [...modelEvidenceGaps, ...derivedBlockingGaps],
-    };
-}
 function assertFrontendContractPathsSafe(value) {
     const record = asRecord(value);
     if (!record)
@@ -1169,10 +1069,10 @@ export async function materializeFrontendImplementationContract(input) {
     const normalizedContract = coerceFrontendImplementationContractInput(parsed, canonicalBinding);
     // There is exactly one post-security candidate. A fallback candidate would
     // allow malformed raw fields to bypass the boundary checks above.
-    const candidate = deriveFrontendVerificationCoverage({
+    const candidate = {
         ...(asRecord(normalizedContract) ?? parsed),
         sourceBinding: canonicalBinding,
-    }, canonicalBinding);
+    };
     const result = frontendImplementationContractSchema.safeParse(candidate);
     if (!result.success)
         throw new Error(`invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`);

package/docs/architecture/runtime-boundaries.md

@@ -12,6 +12,9 @@ Skill layer
 CLI layer (src/cli/)
   └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
 
+Init-upgrade command layer (src/commands/init-upgrade.ts)
+  └─ controller-owned init-upgrade state machine、frozen identity、target `.harness/init-upgrades/` facts、safe action receipts and bounded merge contracts
+
 Application layer (src/application/，逐步引入)
   └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
 
@@ -54,6 +57,12 @@ Governance (scripts/check-*.sh, src/governance/)
 - **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
 - **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
 
+### Init-upgrade command boundary
+
+- **位置**：`src/commands/init-upgrade.ts`，复用 `src/commands/init.ts` 的 ownership scan / safe action 与 `src/commands/client-recovery.ts` 的 generated recovery builders。
+- **职责**：拥有可恢复升级状态机与目标项目 run facts；version gate、identity drift、active runtime/lock、workspace re-scan、single-file merge boundary、home zero-write fingerprint 和 completion invariant 都由 controller 决定。
+- **禁止**：OpenCode/Pi plugin、主会话 skill 或 notifier 拥有升级状态机；命令不得修改业务源码、用户 home 或以宽泛路径授权模型。主会话仅可按 controller 返回的具体 `allowedPaths` 合并 init surface，随后必须 `--continue`。
+
 ### Application layer
 
 - **位置**：`src/application/**`（按计划逐步引入）

package/docs/init-surface.manifest.json

@@ -56,6 +56,7 @@
     "skills/agent-worker/references/agent-worker-operator.md",
     "skills/loop-agent/SKILL.md",
     "skills/loop-agent/references/command-reference.md",
+    "skills/loop-agent/references/hybrid-dag.md",
     "skills/loop-agent/references/source-and-plan-practice.md",
     "skills/loop-agent/references/docs-converge.md",
     "skills/ai-engineering-context/SKILL.md",
@@ -135,6 +136,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md",
     ".agents/skills/loop-agent/SKILL.md",
     ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/loop-agent/references/hybrid-dag.md",
     ".agents/skills/loop-agent/references/source-and-plan-practice.md",
     ".agents/skills/loop-agent/references/docs-converge.md",
     ".agents/skills/ai-engineering-context/SKILL.md",
@@ -168,7 +170,8 @@
     "docs/templates/backend-test-case-manifest.schema.json",
     ".opencode/plugins/loop-agent-transient-retry.js",
     ".opencode/plugins/loop-agent-context-overflow-compact.js",
-    ".pi/extensions/loop-agent-context-overflow.js"
+    ".pi/extensions/loop-agent-context-overflow.js",
+    ".pi/settings.json"
   ],
   "initSurface": {
     "README.md": "managed-block",
@@ -218,6 +221,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md": "copied",
     ".agents/skills/loop-agent/SKILL.md": "copied",
     ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/loop-agent/references/hybrid-dag.md": "copied",
     ".agents/skills/loop-agent/references/source-and-plan-practice.md": "copied",
     ".agents/skills/loop-agent/references/docs-converge.md": "copied",
     ".agents/skills/ai-engineering-context/SKILL.md": "copied",
@@ -251,7 +255,8 @@
     "docs/templates/backend-test-case-manifest.schema.json": "copied",
     ".opencode/plugins/loop-agent-transient-retry.js": "generated",
     ".opencode/plugins/loop-agent-context-overflow-compact.js": "generated",
-    ".pi/extensions/loop-agent-context-overflow.js": "generated"
+    ".pi/extensions/loop-agent-context-overflow.js": "generated",
+    ".pi/settings.json": "generated"
   },
   "packageExcluded": [
     "docs/progress/20*.md",
@@ -273,6 +278,7 @@
     "package.json",
     "src/commands/init.ts",
     "src/commands/client-recovery.ts",
+    "src/commands/init-upgrade.ts",
     "src/cli.ts",
     "src/cli/update/init-surface-notifier.ts",
     "src/cli/update/policy.ts",
@@ -297,6 +303,7 @@
         "patterns": [
           "src/commands/init.ts",
           "src/commands/client-recovery.ts",
+          "src/commands/init-upgrade.ts",
           "src/cli.ts",
           "src/cli/update/init-surface-notifier.ts",
           "src/cli/update/policy.ts",

package/docs/templates/harness.schema.json

@@ -111,6 +111,113 @@
         }
       }
     },
+    "workerPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "agent-worker 侧声明式策略（含 Night Scheduler）。运行时以 Zod harnessManifestSchema 为准。",
+      "properties": {
+        "nightScheduler": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "本地夜间 once 调度默认策略；每个 schedule 会冻结 effective snapshot。",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "是否启用 Night Scheduler 能力面。",
+              "default": false
+            },
+            "timezone": {
+              "type": "string",
+              "minLength": 1,
+              "description": "展示与 allowedHours 解释使用的 IANA 时区。",
+              "default": "Asia/Shanghai"
+            },
+            "allowedHours": {
+              "type": "array",
+              "description": "允许派发的本地时间窗，格式 HH:MM-HH:MM，可跨午夜。",
+              "items": {
+                "type": "string",
+                "pattern": "^\\d{2}:\\d{2}-\\d{2}:\\d{2}$"
+              },
+              "default": ["00:00-08:00"]
+            },
+            "maxConcurrency": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "全局同时 running 的 schedule 上限（按有效 execution lease 计数）。",
+              "default": 1
+            },
+            "maxAutoAttempts": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "独立 Worker execution attempt 上限；MVP 为 1。",
+              "default": 1
+            },
+            "misfirePolicy": {
+              "enum": ["run-immediately", "wait-next-window", "human-required"],
+              "description": "机器休眠或 tick 延迟后的 misfire 策略。",
+              "default": "wait-next-window"
+            },
+            "keepFailedWorktree": {
+              "type": "boolean",
+              "description": "失败后是否默认保留 worktree 供人工 inspect。",
+              "default": true
+            },
+            "mergePolicy": {
+              "enum": ["manual-on-success", "auto-on-success"],
+              "description": "成功后的 merge 策略；MVP 仅 manual-on-success。",
+              "default": "manual-on-success"
+            },
+            "autoFollowUp": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "ADR 0010：失败后是否自动 draft Follow-up（永不 auto-approve）。默认 off。",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "为 true 时，terminal failed night execution 可调用 draftFollowUpDecision。",
+                  "default": false
+                },
+                "mode": {
+                  "enum": ["draft-only"],
+                  "description": "MVP 仅 draft-only；自动 Ready/approve 需另 ADR。",
+                  "default": "draft-only"
+                }
+              }
+            },
+            "traceability": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "可 push commit 的工作项可追溯策略（任务卡片）。",
+              "properties": {
+                "required": {
+                  "type": "boolean",
+                  "description": "创建 schedule 时是否强制任务卡片。",
+                  "default": false
+                },
+                "label": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "Task Card"
+                },
+                "pattern": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "workItemRef 正则；默认通用公司卡片格式。",
+                  "default": "^[A-Z][A-Z0-9]+-[A-Z0-9]+#[0-9]+$"
+                },
+                "commitMessageTemplate": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "必须包含 {workItemRef} 占位符。",
+                  "default": "{summary}\n\n{workItemRef}"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "entrypoints": {
       "type": "object",
       "description": "具名的仓库相对文件路径，用作人类和 agent 的入口。",

package/docs/templates/init-managed-agents.md

@@ -42,24 +42,34 @@
 | 用户表达 | 入口 | 执行动作 |
 | --- | --- | --- |
 | loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 初始化 | 完成确定性初始化闭环 |
-| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |
-| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；surface 缺失、人工决策、活跃 DAG/Worker 或 Worker 状态无法确认时零写入 |
-| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | 先 check-update，再只执行确定性安全动作 |
+| loop-agent初始化更新 / loop-agent 初始化更新 / 更新 loop-agent 初始化内容 / 升级 loop-agent 初始化 | 初始化升级闭环 | 直接运行 `init upgrade`；自动安全更新、返回单文件语义合并任务并 `--continue` 至稳定终态，禁止停在只读检查或 `needs-model-merge` |
+| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 / 只检查，不要修改 | 更新校验 | 严格只读报告，不创建 upgrade run、不写入 |
+| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 初始化升级闭环 | 直接运行 `init upgrade`，而非拼接低层 safe-update 命令 |
+| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 初始化升级闭环 | 直接运行 `init upgrade`，由 controller 处理安全更新与验证 |
 | loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 通用需求实现 | 先提供 PRD 与 `allowedPaths` / `forbiddenPaths` / verify，再 `task advance` → 审查 writeSet gate → `task advance --approve-gate`；主会话不得直接修改业务实现 |
 
-**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe` 或模型合并。
+**初始化升级闭环（写入型）**：主会话收到上述写入型表达时自动调用统一入口，并在 controller 返回的具体单文件 `allowedPaths` 内完成必要语义合并后使用 `--continue`。不得停在 `check-update`、`needs-safe-update`、`needs-model-merge` 或 `verification-pending`。默认安装/合并项目 `.opencode/plugins/`、`.pi/extensions/` 与 `.pi/settings.json`；Pi 必须 trust 项目才能加载，默认严禁写 `~/.pi/agent/settings.json`。
 
 ```bash
-loop-agent init check-update --repo-root . --markdown
+loop-agent init upgrade --repo-root . --json
+loop-agent init upgrade --repo-root . --run-id <run-id> --continue --json
+loop-agent init upgrade --repo-root . --run-id <run-id> --report --markdown
 ```
 
-**升级对齐**：`loop-agent init reconcile --repo-root .`；surface 缺失、human decisions、活跃 DAG/Worker 或 Worker 状态无法确认时必须零写入。
+**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe`、模型合并或创建 upgrade run。
+
+```bash
+loop-agent init check-update --repo-root . --markdown
+```
 
-**安全更新**：先 check-update；surface 缺失时仅先建立 inferred baseline，再执行确定性 safe actions。不得自动处理 model merge tasks。
+**低层兼容命令（仅诊断/恢复，不是自然语言写入入口）**：`init reconcile`、`init update --bootstrap-surface` 与 `init update --apply-safe` 保留给 controller 诊断、旧自动化和人工排障。主会话收到任何写入型“初始化更新 / 初始化对齐 / 安全更新”表达时，必须唯一进入 `init upgrade`，不得改为直接调用这些低层命令，也不得在它们返回 `needs-model-merge` 后停止。surface 缺失、human decisions、活跃 DAG/Worker 或 Worker 状态无法确认时仍必须零写入。
 
 ```bash
+# 只读诊断
 loop-agent init check-update --repo-root . --markdown
-loop-agent init update --repo-root . --bootstrap-surface  # 仅 surface 缺失时
+# 低层兼容恢复；不得替代写入型自然语言的统一 init upgrade 入口
+loop-agent init reconcile --repo-root .
+loop-agent init update --repo-root . --bootstrap-surface
 loop-agent init update --repo-root . --apply-safe
 ```
 

package/harness.json

@@ -26,6 +26,28 @@
       ]
     }
   },
+  "workerPolicy": {
+    "nightScheduler": {
+      "enabled": true,
+      "timezone": "Asia/Shanghai",
+      "allowedHours": ["00:00-08:00"],
+      "maxConcurrency": 1,
+      "maxAutoAttempts": 1,
+      "misfirePolicy": "wait-next-window",
+      "keepFailedWorktree": true,
+      "mergePolicy": "manual-on-success",
+      "autoFollowUp": {
+        "enabled": false,
+        "mode": "draft-only"
+      },
+      "traceability": {
+        "required": true,
+        "label": "Task Card",
+        "pattern": "^[A-Z][A-Z0-9]+-[A-Z0-9]+#[0-9]+$",
+        "commitMessageTemplate": "{summary}\n\n{workItemRef}"
+      }
+    }
+  },
   "entrypoints": {
     "readme": "README.md",
     "agents": "AGENTS.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.28.2-beta.1",
+  "version": "0.28.3",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loop-agent
 description: >-
-  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG / task advance lifecycle, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, task advance, task status, dag validate, dag execute, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新. 强路由：loop-agent 帮我完成需求, 帮我实现, 帮我修复, 帮我开发, 使用 loop-agent 完成, 按 loop-agent 流程处理, 通用需求实现；这些表达确定性地进入 task advance / Agent DAG CLI，主会话编排而不直接写业务实现.
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG / task advance lifecycle, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, task advance, task status, dag validate, dag execute, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新, loop-agent初始化更新, loop-agent 初始化更新, 更新 loop-agent 初始化内容, 升级后对齐. 强路由：loop-agent 帮我完成需求, 帮我实现, 帮我修复, 帮我开发, 使用 loop-agent 完成, 按 loop-agent 流程处理, 通用需求实现；这些表达确定性地进入 task advance / Agent DAG CLI，主会话编排而不直接写业务实现.
 references:
   - path: references/harness-policy.md
     required: true
@@ -13,61 +13,53 @@ references:
 
 # loop-agent Workflow
 
-Entry: routing and hard rules. Required details come from frontmatter references；`command-reference.md` stays optional below.
+入口只保留路由与硬约束；细节由 frontmatter required references 注入，`command-reference.md` 保持可选。
 
 ## 默认立场
 
-- 主入口是 **Agent DAG**（经 `loop-agent` / 可选 `agent-worker` CLI）。
-- 宿主仅作 **Compatibility / Operator Assist**：主会话编排 CLI、审 writeSet、读 status/doctor/report、处理 human gate、验证与 handoff；不写业务代码。
-- **严禁**主会话绕过 CLI 用宿主 Edit/Write 改业务实现，或 CLI 失败后「救火改文件」。
-- DAG `pi` executor 默认 read-only；`toolProfile: "write"` 时为 bounded writer；sidecar 须 per call 收窄。
-- Shell verification 是事实源；长期结论写回 `ai_workspace/loop-agent/`、`docs/decisions/` 或 `skills/`。
+- 主入口是 **Agent DAG**；主会话只编排 CLI、审 writeSet、处理 gate、验证与 handoff，不写业务实现。
+- 禁止绕过 CLI 用宿主 Edit/Write「救火」；失败走 doctor/reconcile/human gate/重跑。
+- `pi` 默认 read-only；仅 `toolProfile: "write"` 是 bounded writer。Shell verification 是事实源。
 
-## 唯一推荐执行路径
+## 初始化升级路由
 
-```bash
-# 标准 mutation：task advance（create/import/prepare/generate/validate → writeSet gate）
-loop-agent task advance <task-id> "Title" \
-  --prd <prd.md> \
-  --allowed-path "<glob>" \
-  --forbidden-path ".harness/**" \
-  --verify "typecheck:npm run typecheck" \
-  --json
+- 写入型「**loop-agent初始化更新**」「loop-agent 初始化更新」「更新 loop-agent 初始化内容」「升级后对齐」统一运行 `loop-agent init upgrade --repo-root . --json`；处理 controller 返回的单文件 `allowedPaths`，以同一 run `--continue` 推进至终态，不停在中间状态。
+- 「检查初始化更新」「初始化更新校验」「只检查，不要修改」仅运行 `loop-agent init check-update --repo-root . --markdown`，不得创建 run 或写入。
+- facts 位于 `.harness/init-upgrades/<run-id>/`；禁止业务源码和宽泛 glob。默认管理项目 `.opencode/plugins/`、`.pi/extensions/`、`.pi/settings.json`；Pi trust 后加载，默认不读写 `~/.pi/agent/settings.json`。
 
-# 审查 JSON 中的 gate.writeSet / gate.digest 后批准并长跑
-loop-agent task advance <task-id> \
-  --approve-gate "write-set-review:<digest>" \
-  --json
+## 标准路径
 
-# 可选只读（无 refresh 副作用）
+```bash
+loop-agent task advance <task-id> "Title" --prd <prd.md> \
+  --allowed-path "<glob>" --forbidden-path ".harness/**" \
+  --verify "typecheck:npm run typecheck" --json
+loop-agent task advance <task-id> \
+  --approve-gate "write-set-review:<digest>" --json
 loop-agent task status <task-id> --json
 ```
 
-非微小跨会话任务仍可先 `plan create`（见 references/source-and-plan-practice.md）。主会话只审 gate/writeSet 与验证证据，不拼低层 prepare/run-task/run-dag/promote/closeout 命令串。
+非微小跨会话任务可先 `plan create`。主会话只审 gate/writeSet 与验证证据，不拼低层 prepare/run-task/run-dag/promote/closeout 命令串。
 
-## 进阶主题路由
+## 主题路由
 
 | 主题 | Reference |
 | --- | --- |
 | Harness policy、Loop、SePO-lite | `references/harness-policy.md` |
-| Agent DAG topology、writeSet、recovery | `references/hybrid-dag.md` |
+| DAG topology、writeSet、recovery | `references/hybrid-dag.md` |
 | Operator commands、`agent-worker` | `references/command-reference.md` |
-| 独立验证、failure handling、closeout | `references/verification-and-failure-handling.md` |
+| 验证、failure、closeout | `references/verification-and-failure-handling.md` |
 
 ## Hard Rules
 
 1. Use vertical tracer bullets across real integration layers；each needs independent acceptance and verification.
-2. Autonomy ≠ governance profile: declare AFK/HITL in human gate; choose `--profile` by risk.
-3. Source materials mandatory: `source/需求.md`、`source/执行约束.md`、优先 `source/references/*` originals。
-4. Structured task config only: `referenceDocs` uses `{ path, name? }[]`, never a string array；`verifyCommands` uses `{ label, command, timeoutMs? }[]`, never a string array。
-5. Agent DAG is the implementation workflow；review three-way checks references + derived source + implementation。
-6. 主会话不绕过 CLI 直接写业务代码；失败只走 doctor/reconcile/human gate/重跑。
-7. DAG `pi` executor read-only unless `toolProfile: "write"`；completed run facts read-only；不得从 read-only DAG/sidecar 写 root `artifacts/`。
-8. No hidden state in chat only；verify before completion.
-9. Client recovery：`init --client-recovery=auto|project|user|off` 投影 transient-retry + overflow-compact + Pi overflow extension；只有 `user` 写 Pi settings；overflow 与 transient 职责分离；check/update 遵守 ownership。
+2. Autonomy ≠ governance profile；AFK/HITL 属 human gate，`--profile` 按风险选择。
+3. 必须读取 `source/需求.md`、`source/执行约束.md`，优先原始 `source/references/*`。
+4. `referenceDocs` uses `{ path, name? }[]`, never a string array；`verifyCommands` uses `{ label, command, timeoutMs? }[]`, never a string array。
+5. Agent DAG 才是实现流；review 三向核对 references、derived source、implementation。
+6. read-only DAG/sidecar 不得写 root `artifacts/`；completed run facts 只读。
+7. 关键状态不得只留在聊天；完成前必须验证。
+8. Client recovery 的 `auto|project|user|off` 遵守 ownership；仅 `user` 写用户 Pi settings，overflow 与 transient 分工。
 
 ## References
 
-Required（按需 inline）：`references/harness-policy.md`、`references/hybrid-dag.md`、`references/verification-and-failure-handling.md`
-
-Optional 索引见 `references/README.md`；常用：`command-reference.md`、`long-running-loop.md`、`orchestrator-and-interventions.md`、`docs-converge.md`。
+Required：`references/harness-policy.md`、`references/hybrid-dag.md`、`references/verification-and-failure-handling.md`。Optional 见 `references/README.md`；常用 `references/command-reference.md`、`references/source-and-plan-practice.md`、`references/long-running-loop.md`、`references/orchestrator-and-interventions.md`、`references/docs-converge.md`。