@tea-agent/loop-agent 0.10.0 → 0.12.0

package/dist/commands/init.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
-import { access, copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { fileURLToPath } from "node:url";
 import { copyDir } from "../shared/copy-dir.js";
 import { loadHarnessManifest } from "../governance/harness.js";
@@ -9,6 +10,7 @@ const MANAGED_BLOCK_END = "<!-- LOOP_AGENT_INIT_END -->";
 const GITIGNORE_BLOCK_START = "# LOOP_AGENT_INIT_START";
 const GITIGNORE_BLOCK_END = "# LOOP_AGENT_INIT_END";
 const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
+const DEFAULT_GOVERNANCE_ROOT = "ai_workspace/loop-agent";
 const CORE_DOC_FILES = [
     "README.md",
     "architecture/runtime-boundaries.md",
@@ -108,7 +110,7 @@ required_paths=(
   "${GOVERNANCE_ROOT_TOKEN}/verification-matrix.md"
   "${GOVERNANCE_ROOT_TOKEN}/architecture/runtime-boundaries.md"
   "${GOVERNANCE_ROOT_TOKEN}/templates"
-  "skills/loop-agent/SKILL.md"
+  ".agents/skills/loop-agent/SKILL.md"
   ".harness/prompts/analyze.md"
   ".harness/prompts/plan.md"
   ".harness/tasks"
@@ -305,7 +307,7 @@ fi
 
 if [[ -d artifacts ]]; then
   artifact_count="$(find artifacts -mindepth 1 -maxdepth 1 ! -name .gitkeep | wc -l | tr -d ' ')"
-  [[ "\${artifact_count}" == "0" ]] || failures+=("root artifacts/ contains \${artifact_count} entries; use docs/reports or .harness run artifacts")
+  [[ "\${artifact_count}" == "0" ]] || failures+=("root artifacts/ contains \${artifact_count} entries; use ${GOVERNANCE_ROOT_TOKEN}/reports or .harness run artifacts")
 fi
 
 if (( \${#failures[@]} > 0 )); then
@@ -367,41 +369,54 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
 cd "\${ROOT_DIR}"
 
-skill_md="skills/loop-agent/SKILL.md"
-if [[ ! -f "\${skill_md}" ]]; then
-  echo "skill entry 检查失败：缺少 \${skill_md}" >&2
-  exit 1
-fi
-
-required_refs=(
-  "references/harness-policy.md"
-  "references/hybrid-dag.md"
-  "references/verification-and-failure-handling.md"
-  "references/command-reference.md"
-)
+check_skill() {
+  local skill_name="$1"
+  shift
+  local skill_dir=".agents/skills/\${skill_name}"
+  local skill_md="\${skill_dir}/SKILL.md"
+  local missing=()
 
-missing=()
-for ref in "\${required_refs[@]}"; do
-  [[ -f "skills/loop-agent/\${ref}" ]] || missing+=("\${ref}")
-done
+  if [[ ! -f "\${skill_md}" ]]; then
+    echo "skill entry 检查失败：缺少 \${skill_md}" >&2
+    exit 1
+  fi
+  grep -Eq "^name:[[:space:]]*\${skill_name}[[:space:]]*$" "\${skill_md}" || missing+=("frontmatter name")
+  grep -Eq '^description:[[:space:]]*[^[:space:]]' "\${skill_md}" || missing+=("frontmatter description")
 
-while IFS= read -r ref; do
-  [[ -z "\${ref}" ]] && continue
-  [[ -f "skills/loop-agent/\${ref}" ]] || missing+=("\${ref}")
-done < <(grep -Eo 'references/[A-Za-z0-9._/-]+\\.md' "\${skill_md}" | sort -u || true)
+  local ref
+  for ref in "$@"; do
+    [[ -f "\${skill_dir}/\${ref}" ]] || missing+=("\${ref}")
+    grep -Fq "\${ref}" "\${skill_md}" || missing+=("SKILL.md -> \${ref}")
+  done
+  if (( \${#missing[@]} > 0 )); then
+    echo "skill entry 检查失败（\${skill_name}）：" >&2
+    printf '  - %s\\n' "\${missing[@]}" >&2
+    exit 1
+  fi
 
-if (( \${#missing[@]} > 0 )); then
-  echo "skill entry 检查失败：引用的 reference 文件不存在：" >&2
-  printf '  - %s\\n' "\${missing[@]}" >&2
-  exit 1
-fi
+  local line_count
+  line_count="$(wc -l < "\${skill_md}" | tr -d ' ')"
+  if [[ "\${line_count}" =~ ^[0-9]+$ && "\${line_count}" -gt 180 ]]; then
+    echo "skill entry 检查失败：\${skill_md} 行数为 \${line_count}，入口应保持精简" >&2
+    exit 1
+  fi
+  echo "skill entry 检查通过：\${skill_name} references ok, lines=\${line_count}"
+}
 
-line_count="$(wc -l < "\${skill_md}" | tr -d ' ')"
-if [[ "\${line_count}" =~ ^[0-9]+$ && "\${line_count}" -gt 220 ]]; then
-  echo "skill entry 检查警告：\${skill_md} 行数为 \${line_count}，建议保持入口精简并把细节放入 references/" >&2
-fi
+check_skill "loop-agent" \\
+  "references/harness-policy.md" \\
+  "references/hybrid-dag.md" \\
+  "references/verification-and-failure-handling.md" \\
+  "references/command-reference.md"
+check_skill "agent-worker" "references/agent-worker-operator.md"
 
-echo "skill entry 检查通过：references ok, lines=\${line_count}"
+description_line="$(grep -E '^description:' .agents/skills/agent-worker/SKILL.md | head -n 1 | tr '[:upper:]' '[:lower:]')"
+for term in "agent-worker" "feature packet" "taskspec" "task pool" "self-host" "candidate" "loop-agent"; do
+  if [[ "\${description_line}" != *"\${term}"* ]]; then
+    echo "skill entry 检查失败（agent-worker）：description 缺少触发/路由词 \${term}" >&2
+    exit 1
+  fi
+done
 `;
 const INIT_CHECK_REPO_SH = `#!/usr/bin/env bash
 set -euo pipefail
@@ -578,7 +593,7 @@ fi
 
 if (( ran == 0 )); then
   echo "未检测到可安全自动运行的项目测试入口。"
-  echo "loop-agent 治理检查仍可运行；请让初始化模型根据目标项目技术栈补充 scripts/ci-tests.sh 与 docs/verification-matrix.md。"
+  echo "loop-agent 治理检查仍可运行；请让初始化模型根据目标项目技术栈补充 scripts/ci-tests.sh 与 ${GOVERNANCE_ROOT_TOKEN}/verification-matrix.md。"
 fi
 
 if (( \${#notes[@]} > 0 )); then
@@ -666,14 +681,14 @@ function buildManagedAgentsBlock(input) {
         "",
         "### 初始化闭环",
         "",
-        "当用户要求在本仓库初始化 loop-agent，或发现 `README.md` / `docs/verification-matrix.md` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。",
+        `当用户要求在本仓库初始化 loop-agent，或发现 \`README.md\` / \`${input.governanceRoot}/verification-matrix.md\` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。`,
         "",
         "标准流程：",
         "",
         "1. 运行 `loop-agent init instructions --repo-root .` 获取完整初始化指引。",
         "2. 运行 `loop-agent init --repo-root . --profile full --merge` 完成确定性脚手架。",
         "3. 立即读取目标项目的 README、manifest/build/config 文件和顶层源码/模块目录，识别项目类型、模块、运行入口和验证命令。",
-        "4. 基于真实项目文件补全或修正根 `README.md`、`docs/verification-matrix.md`，必要时适配 `scripts/ci-tests.sh`。",
+        `4. 基于真实项目文件补全或修正根 \`README.md\`、\`${input.governanceRoot}/verification-matrix.md\`，必要时适配 \`scripts/ci-tests.sh\`。`,
         "5. 运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .` 和 quick verification。",
         "",
         "如果仓库信息不足，写明“尚未从仓库文件中识别到 ...”以及下一步需要的事实；不要留下泛化占位符，也不要只提示用户稍后手填。",
@@ -724,7 +739,7 @@ function buildManagedAgentsBlock(input) {
         "",
         "- `.harness/tasks/` 保存任务状态和 source 材料。",
         "- `.harness/dag-runs/` 与 `.harness/runs/` 保存运行事实；已完成事实只读。",
-        "- `skills/` 保存仓库本地 skill 指令；本地缺失时 runtime 可回退到 npm 包内置 skills。",
+        "- `.agents/skills/` 保存目标项目本地 skill 指令；本地缺失时 runtime 可回退到 npm 包内置 skills。",
         "- 示例内置在工具中；优先使用 `loop-agent examples list` 和 `loop-agent examples show <name>` 查看，不默认提交到目标仓库。",
         "",
         "### 验证",
@@ -747,7 +762,7 @@ function buildManagedAgentsBlock(input) {
         "",
         "### 交接",
         "",
-        "较大的交接应说明改了什么、为什么这样改、验证命令和结果、影响到的 docs/tests/scripts/contracts、剩余风险和下一步。长期结论应进入 docs/progress、docs/reports、docs/exec-plans、docs/decisions、测试、脚本或模板。",
+        `较大的交接应说明改了什么、为什么这样改、验证命令和结果、影响到的 docs/tests/scripts/contracts、剩余风险和下一步。长期结论应进入 \`${input.governanceRoot}/progress\`、\`${input.governanceRoot}/reports\`、\`${input.governanceRoot}/exec-plans\`、\`${input.governanceRoot}/decisions\`、测试、脚本或模板。`,
         MANAGED_BLOCK_END,
     ].join("\n");
 }
@@ -820,11 +835,9 @@ function buildHarness(input) {
     const existingExecutors = isRecord(input.existing.executors)
         ? input.existing.executors
         : {};
-    // Cursor executor is opt-in for package developers; do not project it to target apps.
-    // Keep it only when the target already configured executors.cursor.
-    if (!isRecord(existingExecutors.cursor)) {
-        delete templateExecutors.cursor;
-    }
+    // Cursor executor must never be projected; Pi-only governed runtime.
+    delete templateExecutors.cursor;
+    delete existingExecutors.cursor;
     const mergedExecutors = mergeRecord(templateExecutors, existingExecutors);
     // requiresApiKey is Cursor-facing only; never project it on pi.
     if (isRecord(mergedExecutors.pi) && "requiresApiKey" in mergedExecutors.pi) {
@@ -999,12 +1012,18 @@ function manifestPathToTargetPath(relativePath, governanceRoot) {
     if (governanceRoot !== "docs" && relativePath.startsWith("docs/")) {
         return `${governanceRoot}/${relativePath.slice("docs/".length)}`;
     }
+    if (relativePath.startsWith("skills/")) {
+        return `.agents/${relativePath}`;
+    }
     return relativePath;
 }
 function targetPathToManifestPath(relativePath, governanceRoot) {
     if (governanceRoot !== "docs" && relativePath.startsWith(`${governanceRoot}/`)) {
         return `docs/${relativePath.slice(`${governanceRoot}/`.length)}`;
     }
+    if (relativePath.startsWith(".agents/skills/")) {
+        return relativePath.slice(".agents/".length);
+    }
     return relativePath;
 }
 async function readPackageVersion(assetRoot) {
@@ -1017,15 +1036,62 @@ async function readInitSurfaceManifest(assetRoot) {
     const manifest = JSON.parse(raw);
     const initFullRequired = manifest.initFullRequired ?? [];
     const initSurface = manifest.initSurface ?? {};
-    const entries = initFullRequired.map((relativePath) => ({
-        path: relativePath,
-        mode: initSurface[relativePath] ?? inferInitSurfaceMode(relativePath),
-    }));
+    const seenPaths = new Set();
+    const entries = [];
+    for (const relativePath of initFullRequired) {
+        if (seenPaths.has(relativePath))
+            continue;
+        seenPaths.add(relativePath);
+        entries.push({
+            path: relativePath,
+            mode: initSurface[relativePath] ?? inferInitSurfaceMode(relativePath),
+        });
+    }
+    // Fresh `init --profile full` copies the entire `docs/templates/` and
+    // `skills/` directories via copyDirMerge. Every file actually projected to a
+    // target project must be represented in the desired init surface so that
+    // check-update can detect missing or stale copies during controller upgrades.
+    // The static manifest intentionally only pins explicit modes for the subset
+    // that needs them; the rest are auto-discovered here as "copied" entries.
+    for (const discovered of await discoverCopiedSurfaceFiles(assetRoot)) {
+        if (seenPaths.has(discovered))
+            continue;
+        seenPaths.add(discovered);
+        entries.push({
+            path: discovered,
+            mode: initSurface[discovered] ?? inferInitSurfaceMode(discovered),
+        });
+    }
     if (!entries.some((entry) => entry.path === INIT_SURFACE_STATE_PATH)) {
         entries.push({ path: INIT_SURFACE_STATE_PATH, mode: "state" });
     }
     return { manifest, raw, sha256: sha256Text(raw), entries };
 }
+/**
+ * Returns manifest-path entries for every file that fresh `init --profile full`
+ * copies from the bundled package into a target project: all of `docs/templates/`
+ * and all of `skills/` (the latter is mirrored to `.agents/skills/` at the
+ * target). Paths use the package source convention so manifestPathToTargetPath
+ * can remap them per governance root.
+ */
+async function discoverCopiedSurfaceFiles(assetRoot) {
+    const discovered = [];
+    const roots = [
+        { source: "docs/templates", prefix: "docs/templates/" },
+        { source: "skills", prefix: "skills/" },
+    ];
+    for (const { source, prefix } of roots) {
+        const rootPath = path.join(assetRoot, source);
+        const rootInfo = await stat(rootPath).catch(() => null);
+        if (!rootInfo?.isDirectory())
+            continue;
+        const files = await listRelativeFiles(rootPath);
+        for (const relativePath of files) {
+            discovered.push(`${prefix}${relativePath}`);
+        }
+    }
+    return discovered.sort();
+}
 function inferInitSurfaceMode(relativePath) {
     if (relativePath === INIT_SURFACE_STATE_PATH)
         return "state";
@@ -1195,10 +1261,20 @@ async function buildCurrentSurfaceState(input) {
             };
             continue;
         }
+        let semanticallyMatchesGeneratedJson = false;
+        if (targetRelativePath === "harness.json" && desired.content !== undefined) {
+            try {
+                semanticallyMatchesGeneratedJson = isDeepStrictEqual(JSON.parse(current.toString("utf-8")), JSON.parse(desired.content));
+            }
+            catch {
+                // Invalid JSON remains local-existing-unknown for model merge / doctor.
+            }
+        }
         files[targetRelativePath] = {
             ...base,
             currentSha256,
-            relationship: sourceSha256 && currentSha256 === sourceSha256
+            relationship: semanticallyMatchesGeneratedJson ||
+                (sourceSha256 !== undefined && currentSha256 === sourceSha256)
                 ? entry.mode === "generated"
                     ? "matches-current-generated"
                     : "matches-current-package"
@@ -1221,15 +1297,278 @@ async function writeInitSurfaceState(input) {
     await writeFile(target, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
     return state;
 }
+function isCurrentInitRelationship(relationship) {
+    return (relationship === "matches-current-package" ||
+        relationship === "matches-current-generated" ||
+        relationship === "managed-block-current" ||
+        relationship === "directory-present" ||
+        relationship === "state-file");
+}
+async function fileSha256IfExists(filePath) {
+    const info = await stat(filePath).catch(() => null);
+    if (!info || !info.isFile())
+        return undefined;
+    return sha256Buffer(await readFile(filePath));
+}
+async function isDirectoryEmpty(dirPath) {
+    const info = await stat(dirPath).catch(() => null);
+    if (!info || !info.isDirectory())
+        return false;
+    return (await readdir(dirPath)).length === 0;
+}
+async function listRelativeFiles(rootPath) {
+    const rootInfo = await stat(rootPath).catch(() => null);
+    if (!rootInfo?.isDirectory())
+        return [];
+    const files = [];
+    async function walk(currentPath, relativeDir) {
+        for (const entry of await readdir(currentPath, { withFileTypes: true })) {
+            const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            const absolutePath = path.join(currentPath, entry.name);
+            if (entry.isDirectory())
+                await walk(absolutePath, relativePath);
+            else if (entry.isFile())
+                files.push(relativePath);
+        }
+    }
+    await walk(rootPath, "");
+    return files.sort();
+}
+async function expectedLegacyInitFileSha(input) {
+    if (input.legacyPath.startsWith("docs/")) {
+        const doc = input.legacyPath.slice("docs/".length);
+        const generated = buildGeneratedCoreDoc({
+            doc,
+            projectName: input.projectName,
+            governanceRoot: "docs",
+        });
+        if (generated !== undefined)
+            return sha256Text(generated);
+        const generatedDir = GOVERNANCE_README_DIRS.find((dir) => input.legacyPath === `docs/${dir}/README.md`);
+        if (generatedDir) {
+            return sha256Text(buildGovernanceDirectoryReadme({
+                dir: generatedDir,
+                projectName: input.projectName,
+            }));
+        }
+    }
+    if (!input.legacyPath.startsWith("docs/") && !input.legacyPath.startsWith("skills/")) {
+        return undefined;
+    }
+    return fileSha256IfExists(path.join(input.assetRoot, input.legacyPath));
+}
+function collectSafeRetiredDirectories(paths) {
+    const dirs = new Set();
+    for (const retiredPath of paths) {
+        let dir = path.posix.dirname(retiredPath);
+        while (dir !== "." && dir !== "/") {
+            if (dir === "skills" || dir.startsWith("skills/") || dir === "docs" || dir.startsWith("docs/")) {
+                dirs.add(dir);
+            }
+            dir = path.posix.dirname(dir);
+        }
+        if (retiredPath.startsWith("skills/"))
+            dirs.add("skills");
+    }
+    return [...dirs].sort((left, right) => right.split("/").length - left.split("/").length);
+}
+function needsHarnessModelMigration(harness) {
+    if ("model" in harness || "models" in harness || "modelProfiles" in harness || "modelRouting" in harness) {
+        return true;
+    }
+    if (isRecord(harness.executors)) {
+        if ("cursor" in harness.executors)
+            return true;
+        if (isRecord(harness.executors.pi)) {
+            return ("requiresApiKey" in harness.executors.pi ||
+                "defaultModel" in harness.executors.pi);
+        }
+    }
+    return false;
+}
+function migrateHarnessModelFields(harness) {
+    const next = { ...harness };
+    const legacyModel = typeof next.model === "string"
+        ? next.model
+        : isRecord(next.executors) &&
+            isRecord(next.executors.pi) &&
+            typeof next.executors.pi.defaultModel === "string"
+            ? next.executors.pi.defaultModel
+            : undefined;
+    delete next.model;
+    delete next.models;
+    delete next.modelProfiles;
+    delete next.modelRouting;
+    const executors = isRecord(next.executors) ? { ...next.executors } : {};
+    delete executors.cursor;
+    const pi = isRecord(executors.pi) ? { ...executors.pi } : {};
+    delete pi.requiresApiKey;
+    delete pi.defaultModel;
+    if (legacyModel) {
+        for (const level of ["LOW", "MED", "HIGH"]) {
+            if (typeof pi[level] !== "string")
+                pi[level] = legacyModel;
+        }
+    }
+    executors.pi = pi;
+    next.executors = executors;
+    return next;
+}
+function hasLegacyHarnessGovernancePaths(harness) {
+    for (const sectionName of ["entrypoints", "artifacts"]) {
+        const section = harness[sectionName];
+        if (isRecord(section) &&
+            Object.values(section).some((value) => typeof value === "string" && value.startsWith("docs/"))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function collectRetiredLayoutActions(input) {
+    const blockedTargetPaths = new Set();
+    if (!input.recordedState)
+        return { actions: [], blockedTargetPaths };
+    const actions = [];
+    const retiredOwnedPaths = [];
+    const currentPaths = new Set(Object.keys(input.currentState.files));
+    const recordedPaths = new Set(Object.keys(input.recordedState.files));
+    for (const [oldPath, oldState] of Object.entries(input.recordedState.files)) {
+        const targetPath = normalizeRelativePath(manifestPathToTargetPath(oldPath, input.governanceRoot));
+        if (targetPath === oldPath || !currentPaths.has(targetPath))
+            continue;
+        if (oldState.mode === "directory" || oldState.mode === "state")
+            continue;
+        const oldAbsolute = path.join(input.repoRoot, oldPath);
+        const oldHash = await fileSha256IfExists(oldAbsolute);
+        if (!oldHash)
+            continue;
+        if (!oldState.currentSha256 || oldHash !== oldState.currentSha256) {
+            input.humanDecisions.push({
+                path: oldPath,
+                reason: `legacy init file may have local edits; review before migrating to ${targetPath}`,
+            });
+            // The user owns a modified copy at the legacy path; do not silently
+            // install the package version at the canonical target path.
+            blockedTargetPaths.add(targetPath);
+            continue;
+        }
+        const targetAbsolute = path.join(input.repoRoot, targetPath);
+        const targetHash = await fileSha256IfExists(targetAbsolute);
+        const targetState = input.currentState.files[targetPath];
+        if (!targetHash) {
+            if (targetState?.sourceSha256 !== undefined &&
+                targetState.sourceSha256 !== oldHash) {
+                actions.push({
+                    type: "remove-owned-file",
+                    path: oldPath,
+                    reason: `remove unchanged legacy init file so the current ${targetPath} can be installed`,
+                });
+                retiredOwnedPaths.push(oldPath);
+                continue;
+            }
+            actions.push({
+                type: "migrate-owned-file",
+                path: oldPath,
+                targetPath,
+                reason: `move loop-agent-owned legacy init file to ${targetPath}`,
+            });
+            retiredOwnedPaths.push(oldPath);
+            continue;
+        }
+        const recordedTargetState = input.recordedState.files[targetPath];
+        if (targetHash === oldHash ||
+            (input.recordedState.stateKind === "recorded" &&
+                recordedTargetState?.currentSha256 !== undefined &&
+                recordedTargetState.currentSha256 === targetHash) ||
+            isCurrentInitRelationship(targetState?.relationship)) {
+            actions.push({
+                type: "remove-owned-file",
+                path: oldPath,
+                reason: `remove duplicate loop-agent-owned legacy init file; current path is ${targetPath}`,
+            });
+            retiredOwnedPaths.push(oldPath);
+            continue;
+        }
+        input.humanDecisions.push({
+            path: oldPath,
+            reason: `legacy init file is owned, but target path ${targetPath} already exists with different content`,
+        });
+        blockedTargetPaths.add(targetPath);
+    }
+    for (const legacyRoot of ["docs", "skills"]) {
+        for (const relativePath of await listRelativeFiles(path.join(input.repoRoot, legacyRoot))) {
+            const oldPath = `${legacyRoot}/${relativePath}`;
+            if (recordedPaths.has(oldPath))
+                continue;
+            const targetPath = normalizeRelativePath(manifestPathToTargetPath(oldPath, input.governanceRoot));
+            if (targetPath === oldPath)
+                continue;
+            const expectedSha = await expectedLegacyInitFileSha({
+                assetRoot: input.assetRoot,
+                projectName: input.projectName,
+                legacyPath: oldPath,
+            });
+            if (!expectedSha)
+                continue;
+            const oldHash = await fileSha256IfExists(path.join(input.repoRoot, oldPath));
+            if (!oldHash)
+                continue;
+            const targetHash = await fileSha256IfExists(path.join(input.repoRoot, targetPath));
+            if (targetHash === oldHash) {
+                actions.push({
+                    type: "remove-owned-file",
+                    path: oldPath,
+                    reason: `remove duplicate legacy init file; current path is ${targetPath}`,
+                });
+                retiredOwnedPaths.push(oldPath);
+                continue;
+            }
+            if (oldHash !== expectedSha) {
+                input.humanDecisions.push({
+                    path: oldPath,
+                    reason: `legacy init-shaped file is not recorded and differs from the current bundled/generated asset; review before migrating to ${targetPath}`,
+                });
+                blockedTargetPaths.add(targetPath);
+                continue;
+            }
+            if (!targetHash) {
+                actions.push({
+                    type: "migrate-owned-file",
+                    path: oldPath,
+                    targetPath,
+                    reason: `move package-matching legacy init file to ${targetPath}`,
+                });
+                retiredOwnedPaths.push(oldPath);
+                continue;
+            }
+            input.humanDecisions.push({
+                path: oldPath,
+                reason: `legacy init-shaped file matches the package, but target path ${targetPath} already exists with different content`,
+            });
+            blockedTargetPaths.add(targetPath);
+        }
+    }
+    for (const dir of collectSafeRetiredDirectories(retiredOwnedPaths)) {
+        actions.push({
+            type: "remove-empty-directory",
+            path: dir,
+            reason: "remove directory if it is empty after legacy init files are migrated",
+        });
+    }
+    return { actions, blockedTargetPaths };
+}
 async function resolveInitProjectContext(input) {
     const harness = await readJsonIfExists(path.join(input.repoRoot, "harness.json"));
+    const recordedGovernanceRoot = typeof harness.governanceRoot === "string" ? harness.governanceRoot : undefined;
     return {
         projectName: input.projectName ??
             (typeof harness.project === "string" ? harness.project : undefined) ??
             path.basename(input.repoRoot),
         governanceRoot: input.governanceRoot ??
-            (typeof harness.governanceRoot === "string" ? harness.governanceRoot : undefined) ??
-            "docs",
+            (recordedGovernanceRoot === "docs"
+                ? DEFAULT_GOVERNANCE_ROOT
+                : recordedGovernanceRoot) ??
+            DEFAULT_GOVERNANCE_ROOT,
     };
 }
 function buildManagedReadmeBlock(input) {
@@ -1442,7 +1781,7 @@ function buildTargetDevelopmentPrinciples(input) {
         "1. One task advances one bounded work block.",
         "2. Search existing code, docs, scripts, and tests before designing new behavior.",
         "3. Shell verification is the completion authority.",
-        "4. Runtime state belongs in `.harness/`; durable decisions belong in `docs/`.",
+        `4. Runtime state belongs in \`.harness/\`; durable decisions belong in \`${input.governanceRoot}/\`.`,
         "5. Model writer nodes must be bounded by explicit allowed and forbidden paths.",
         "6. Advisory model output must be followed by deterministic verification.",
         "7. Repeated constraints should become docs, tests, scripts, checks, or templates.",
@@ -1469,7 +1808,7 @@ function buildTargetFeatureWorkflow(input) {
         "3. Contract: state deliverables, non-goals, completion criteria, verification commands, and failure conditions.",
         "4. Implement: make the smallest coherent change and update required docs, scripts, and tests.",
         "5. Verify: run governance checks plus target project verification.",
-        "6. Handoff: record evidence in docs/progress, docs/reports, an exec plan, or an ADR when useful.",
+        `6. Handoff: record evidence in ${input.governanceRoot}/progress, ${input.governanceRoot}/reports, an exec plan, or an ADR when useful.`,
         "",
         "## Agent DAG Path",
         "",
@@ -1486,6 +1825,13 @@ function buildTargetFeatureWorkflow(input) {
         "",
         "Before executing a DAG, review profile routing, governance profile, writer writeSet, allowed paths, forbidden paths, shell verification, and decision gate mode.",
         "",
+        "## Specialized Task Kinds",
+        "",
+        "Set `taskKind` in `.harness/tasks/<task-id>/task.json` to route a task to a dedicated DAG profile instead of the default auto profile:",
+        "",
+        "- `taskKind: \"backend-test\"` selects the dedicated backend test DAG. Its Pi nodes analyze requirements, generate and review backend cases, generate pytest, and retrospect on results; shell gate/execution nodes enforce the review verdict and run the target project's pytest. The backend test templates (`backend-test-dag.json` and the `backend-test-dag.*.prompt.md` files) ship inside the loop-agent package as static references and are projected to target projects under the governance `templates/` directory.",
+        "- Only eligible read-only Pi nodes (planner, scout, reviewer, verifier, closeout with no write-capable tool profile) receive the conservative automatic retry policy. Supervisor, implementer, writer, docs-only, dynamic, shell, static, and decision-gate nodes are not retried automatically. Eligible nodes cannot write repository files; the controller only records immutable attempt evidence under `.harness/dag-runs/<state>/<run-id>/<node-id>/attempt-<n>.json`.",
+        "",
         "## Verification",
         "",
         `Use \`${input.governanceRoot}/verification-matrix.md\` to choose the narrowest command that proves the claim.`,
@@ -1543,8 +1889,8 @@ function buildTargetLoopAgentHarness(input) {
         "- `.harness/dag-runs/` stores DAG run facts.",
         "- `.harness/runs/` stores one-shot executor facts.",
         "- `.harness/task-pool/` stores optional agent-worker Task Pool state, batch artifacts, failure handoffs, and local Observe events; it is runtime state and normally ignored by Git.",
-        "- `docs/` stores durable governance, plans, reports, progress, and decisions.",
-        "- `skills/` stores repo-local skill instructions; the CLI can fall back to bundled skills when needed.",
+        `- \`${input.governanceRoot}/\` stores loop-agent generated governance, plans, reports, progress, and decisions.`,
+        "- `.agents/skills/` stores project repo-local skill instructions; the CLI can fall back to bundled package skills when needed.",
         "",
         "## Default Workflow",
         "",
@@ -1554,9 +1900,9 @@ function buildTargetLoopAgentHarness(input) {
         "",
         "After a run, use `loop-agent dag report --run-id <run-id> --markdown` to read canonical run facts and `loop-agent dag doctor --run-id <run-id> --markdown` to diagnose failed or paused runs. Failed DAG runs should produce a failure handoff via `loop-agent dag closeout-draft --run-id <run-id>` instead of a successful closeout.",
         "",
-        "Use `docs/templates/production-readiness-checklist.md` when claiming Production Readiness v0.1 for low/medium-risk single-repo DAG work.",
+        `Use \`${input.governanceRoot}/templates/production-readiness-checklist.md\` when claiming Production Readiness v0.1 for low/medium-risk single-repo DAG work.`,
         "",
-        "For real product-line Worker samples, use `docs/templates/worker-dogfood-setup.md` and `docs/templates/worker-dogfood-evidence.md`. Explicit failed-task retries must preserve prior evidence and use a new worker run id.",
+        `For real product-line Worker samples, use \`${input.governanceRoot}/templates/worker-dogfood-setup.md\` and \`${input.governanceRoot}/templates/worker-dogfood-evidence.md\`. Explicit failed-task retries must preserve prior evidence and use a new worker run id.`,
         "",
         "## Script Matrix",
         "",
@@ -1572,13 +1918,16 @@ function buildGeneratedCoreDoc(input) {
         case "architecture/runtime-boundaries.md":
             return buildTargetRuntimeBoundaries({ projectName: input.projectName });
         case "development-principles.md":
-            return buildTargetDevelopmentPrinciples({ projectName: input.projectName });
+            return buildTargetDevelopmentPrinciples({
+                projectName: input.projectName,
+                governanceRoot: input.governanceRoot,
+            });
         case "feature-workflow.md":
             return buildTargetFeatureWorkflow({ governanceRoot: input.governanceRoot });
         case "verification-matrix.md":
             return buildTargetVerificationMatrix();
         case "loop-agent-harness.md":
-            return buildTargetLoopAgentHarness({ projectName: input.projectName });
+            return buildTargetLoopAgentHarness({ projectName: input.projectName, governanceRoot: input.governanceRoot });
         default:
             return undefined;
     }
@@ -1599,7 +1948,7 @@ function buildGovernanceDirectoryReadme(input) {
 }
 export function buildInitInstructions(input) {
     const projectName = input.projectName ?? path.basename(path.resolve(input.repoRoot));
-    const governanceRoot = input.governanceRoot ?? "docs";
+    const governanceRoot = input.governanceRoot ?? DEFAULT_GOVERNANCE_ROOT;
     return [
         "# loop-agent Initialization Instructions",
         "",
@@ -1610,7 +1959,7 @@ export function buildInitInstructions(input) {
         `- Project name: default \`${projectName}\`.`,
         `- Governance root: default \`${governanceRoot}\`.`,
         "- Confirm provider/model. Defaults may be used, but the target project may need a different provider/model matrix.",
-        "- Default: merge existing AGENTS.md, harness.json, and docs/ instead of overwriting user content.",
+        "- Default: merge existing AGENTS.md, harness.json, and loop-agent governance docs instead of overwriting user content.",
         "",
         "## Apply Defaults",
         "",
@@ -1624,8 +1973,8 @@ export function buildInitInstructions(input) {
         `- Generate target-project versions of \`${governanceRoot}/README.md\`, \`${governanceRoot}/development-principles.md\`, \`${governanceRoot}/architecture/runtime-boundaries.md\`, \`${governanceRoot}/feature-workflow.md\`, \`${governanceRoot}/verification-matrix.md\`, and \`${governanceRoot}/loop-agent-harness.md\`; copy only generic methodology/template material as-is.`,
         "- After deterministic initialization, inspect README/config/build files (for example package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gradle files, Makefile, .sln/.csproj, or project-specific scripts) and adapt `scripts/ci-tests.sh` plus the verification matrix to the real project.",
         "- Enrich the root `README.md`: keep the deterministic project title and the loop-agent managed block intact, and fill the human-authored sections (项目概览, 技术栈与目录结构, 开发与验证) from the target project's actual files. The root README must serve both as a human-first project entry and as an agent work entry; replace the initialization-model supplement comments when the project files provide the information.",
-        "- Populate `docs/verification-matrix.md` with the target project's actual quick, standard, and full verification commands derived from its real language and toolchain, keeping the governance rows intact.",
-        "- Copy repo-local skills by default so the target repo has auditable skill instructions; full profile also mirrors skills into `.agents/skills/` for external agents.",
+        `- Populate \`${governanceRoot}/verification-matrix.md\` with the target project's actual quick, standard, and full verification commands derived from its real language and toolchain, keeping the governance rows intact.`,
+        "- Project repo-local skills live in `.agents/skills/`. Do not create a root `skills/` directory in the target project; the package's bundled `skills/` remains the built-in fallback.",
         "- Merge a loop-agent managed block into `.gitignore` that ignores harness runtime facts (tasks, dag-runs, runs, live, cache, init-surface.json, .harness/task-pool, legacy .task-pool residue) while keeping prompts and directory placeholders shareable.",
         "- Do not copy examples by default; examples stay bundled in the tool and are available through `loop-agent examples`.",
         "- Add or update a loop-agent managed block in AGENTS.md.",
@@ -1652,8 +2001,8 @@ export function buildInitInstructions(input) {
         "",
         "1. Read the target project's existing README, manifest/build/config files, and top-level source/module directories.",
         "2. Replace the root README's `初始化模型补充` comments when the information can be inferred from files. At minimum, fill project overview, technology stack/directory structure, and development/verification commands.",
-        "3. Update `docs/verification-matrix.md` with the target project's actual quick, standard, and full verification commands.",
-        "4. Confirm the generated docs expose `docs/templates/production-readiness-checklist.md` plus the operator recovery path: `dag report`, `dag doctor --run-id --markdown`, and failed-run `dag closeout-draft` failure handoff.",
+        `3. Update \`${governanceRoot}/verification-matrix.md\` with the target project's actual quick, standard, and full verification commands.`,
+        `4. Confirm the generated docs expose \`${governanceRoot}/templates/production-readiness-checklist.md\` plus the operator recovery path: \`dag report\`, \`dag doctor --run-id --markdown\`, and failed-run \`dag closeout-draft\` failure handoff.`,
         "5. Update `scripts/ci-tests.sh` only when the conservative generated detector is insufficient for the target project.",
         "6. Run `loop-agent init doctor`, `loop-agent inspect`, `loop-agent docs audit`, and the quick verification command.",
         "",
@@ -1672,7 +2021,7 @@ export function buildInitInstructions(input) {
 export async function initializeLoopAgentProject(options) {
     const repoRoot = path.resolve(options.repoRoot);
     const projectName = options.projectName ?? path.basename(repoRoot);
-    const governanceRoot = options.governanceRoot ?? "docs";
+    const governanceRoot = options.governanceRoot ?? DEFAULT_GOVERNANCE_ROOT;
     const profile = options.profile ?? "full";
     const merge = options.merge ?? true;
     const written = [];
@@ -1773,17 +2122,8 @@ export async function initializeLoopAgentProject(options) {
         written,
     });
     if (profile === "full") {
-        await copyDirMerge({
-            assetRoot,
-            repoRoot,
-            sourceRelativePath: "skills",
-            targetRelativePath: "skills",
-            written,
-        });
-        // Mirror bundled skills into the agent-compatible `.agents/skills/` path so
-        // external agents (e.g. OpenCode) that auto-discover `.agents/skills/<name>/SKILL.md`
-        // share the same skill content as loop-agent's primary `skills/` path.
-        // The package still ships only `skills/`; `.agents/skills` is a target projection.
+        // Project repo-local skills live only under `.agents/skills/`.
+        // The package still ships `skills/` as the built-in fallback source.
         await copyDirMerge({
             assetRoot,
             repoRoot,
@@ -1793,7 +2133,6 @@ export async function initializeLoopAgentProject(options) {
         });
     }
     else {
-        skipped.push("skills/");
         skipped.push(".agents/skills/");
     }
     skipped.push("examples/");
@@ -1879,6 +2218,7 @@ export async function checkInitUpdate(input) {
         governanceRoot: input.governanceRoot,
     });
     const recordedState = await readExistingSurfaceState(repoRoot);
+    const assetRoot = await findPackageRoot();
     const surfaceState = recordedState?.stateKind ?? "missing";
     const currentState = await buildCurrentSurfaceState({
         repoRoot,
@@ -1890,6 +2230,24 @@ export async function checkInitUpdate(input) {
     const deterministicActions = [];
     const modelMergeTasks = [];
     const humanDecisions = [];
+    const retiredLayoutResult = await collectRetiredLayoutActions({
+        assetRoot,
+        repoRoot,
+        projectName,
+        governanceRoot,
+        recordedState,
+        currentState,
+        humanDecisions,
+    });
+    const retiredLayoutActions = retiredLayoutResult.actions;
+    const retiredTargetPaths = new Set(retiredLayoutActions
+        .filter((action) => action.type === "migrate-owned-file" && action.targetPath)
+        .map((action) => action.targetPath));
+    // Targets occupied by a user-modified legacy copy must not be silently
+    // (re)installed from the package; preserve them for a human/model merge.
+    for (const blockedPath of retiredLayoutResult.blockedTargetPaths) {
+        retiredTargetPaths.add(blockedPath);
+    }
     if (!recordedState) {
         deterministicActions.push({
             type: "bootstrap-surface",
@@ -1899,6 +2257,8 @@ export async function checkInitUpdate(input) {
     }
     for (const [pathName, state] of Object.entries(currentState.files)) {
         if (state.relationship === "missing-from-target") {
+            if (retiredTargetPaths.has(pathName))
+                continue;
             const action = actionForMissing(pathName, state);
             if (action)
                 deterministicActions.push(action);
@@ -1919,11 +2279,23 @@ export async function checkInitUpdate(input) {
                     reason: "required init directory path exists but is not a directory",
                 });
             }
+            else if (recordedState?.stateKind === "recorded" &&
+                (state.mode === "copied" || state.mode === "generated") &&
+                state.currentSha256 !== undefined &&
+                recordedState.files[pathName]?.currentSha256 === state.currentSha256) {
+                deterministicActions.push({
+                    type: "refresh-owned-file",
+                    path: pathName,
+                    mode: state.mode,
+                    reason: "refresh an unchanged recorded init file to the current generated or bundled content",
+                });
+            }
             else {
                 modelMergeTasks.push(modelMergeTaskFor(pathName, state, allPaths));
             }
         }
     }
+    deterministicActions.unshift(...retiredLayoutActions);
     // Safe harness hygiene: strip obsolete pi.requiresApiKey without full harness rewrite.
     // Cursor requiresApiKey is intentionally kept when present.
     const harnessPath = path.join(repoRoot, "harness.json");
@@ -1939,14 +2311,21 @@ export async function checkInitUpdate(input) {
                     reason: "harness.json is missing or has a stale IDE JSON Schema reference",
                 });
             }
-            if (isRecord(harness) &&
-                isRecord(harness.executors) &&
-                isRecord(harness.executors.pi) &&
-                Object.prototype.hasOwnProperty.call(harness.executors.pi, "requiresApiKey")) {
+            if (recordedState &&
+                isRecord(harness) &&
+                governanceRoot !== "docs" &&
+                (harness.governanceRoot === "docs" || hasLegacyHarnessGovernancePaths(harness))) {
+                deterministicActions.push({
+                    type: "migrate-harness-governance-root",
+                    path: "harness.json",
+                    reason: `replace the legacy default governanceRoot docs with ${governanceRoot}`,
+                });
+            }
+            if (isRecord(harness) && needsHarnessModelMigration(harness)) {
                 deterministicActions.push({
-                    type: "strip-pi-requires-api-key",
+                    type: "migrate-harness-model-fields",
                     path: "harness.json",
-                    reason: "executors.pi.requiresApiKey is unused; strip it while keeping user model config and cursor.requiresApiKey",
+                    reason: "harness.json contains legacy model fields or executor fields that can be safely normalized",
                 });
             }
         }
@@ -2016,16 +2395,79 @@ async function applySafeAction(input) {
         await writeFile(target, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
         return true;
     }
+    if (input.action.type === "migrate-harness-model-fields") {
+        const target = path.join(input.repoRoot, "harness.json");
+        if (!(await exists(target)))
+            return false;
+        const harness = JSON.parse(await readFile(target, "utf-8"));
+        if (!isRecord(harness) || !needsHarnessModelMigration(harness))
+            return false;
+        await writeFile(target, `${JSON.stringify(migrateHarnessModelFields(harness), null, 2)}\n`, "utf-8");
+        return true;
+    }
+    if (input.action.type === "migrate-harness-governance-root") {
+        const target = path.join(input.repoRoot, "harness.json");
+        if (!(await exists(target)))
+            return false;
+        const harness = JSON.parse(await readFile(target, "utf-8"));
+        if (!isRecord(harness) ||
+            (harness.governanceRoot !== "docs" && !hasLegacyHarnessGovernancePaths(harness))) {
+            return false;
+        }
+        const next = {
+            ...harness,
+            governanceRoot: input.governanceRoot,
+        };
+        for (const sectionName of ["entrypoints", "artifacts"]) {
+            const section = harness[sectionName];
+            if (!isRecord(section))
+                continue;
+            next[sectionName] = Object.fromEntries(Object.entries(section).map(([key, value]) => [
+                key,
+                typeof value === "string" && value.startsWith("docs/")
+                    ? `${input.governanceRoot}/${value.slice("docs/".length)}`
+                    : value,
+            ]));
+        }
+        await writeFile(target, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+        return true;
+    }
+    if (input.action.type === "migrate-owned-file") {
+        if (!input.action.targetPath)
+            return false;
+        const source = path.join(input.repoRoot, input.action.path);
+        const target = path.join(input.repoRoot, input.action.targetPath);
+        if (!(await exists(source)) || (await exists(target)))
+            return false;
+        await mkdir(path.dirname(target), { recursive: true });
+        await rename(source, target);
+        return true;
+    }
+    if (input.action.type === "remove-owned-file") {
+        const target = path.join(input.repoRoot, input.action.path);
+        if (!(await exists(target)))
+            return false;
+        await rm(target, { force: true });
+        return true;
+    }
+    if (input.action.type === "remove-empty-directory") {
+        const target = path.join(input.repoRoot, input.action.path);
+        if (!(await isDirectoryEmpty(target)))
+            return false;
+        await rmdir(target);
+        return true;
+    }
     const assetRoot = await findPackageRoot();
     const entry = {
         path: input.action.path,
-        mode: input.action.type === "create-directory"
-            ? "directory"
-            : input.action.type === "copy-missing"
-                ? "copied"
-                : input.action.type === "refresh-managed-block"
-                    ? "managed-block"
-                    : "generated",
+        mode: input.action.mode ??
+            (input.action.type === "create-directory"
+                ? "directory"
+                : input.action.type === "copy-missing"
+                    ? "copied"
+                    : input.action.type === "refresh-managed-block"
+                        ? "managed-block"
+                        : "generated"),
     };
     const target = path.join(input.repoRoot, input.action.path);
     if (input.action.type === "create-directory") {
@@ -2056,6 +2498,10 @@ async function applySafeAction(input) {
         await writeFile(target, next, "utf-8");
         return true;
     }
+    if (input.action.type === "refresh-owned-file") {
+        await writeFile(target, desired.content, "utf-8");
+        return true;
+    }
     if (await exists(target))
         return false;
     await writeFile(target, desired.content, "utf-8");
@@ -2085,7 +2531,14 @@ export async function applyInitUpdate(input) {
                 skipped.push(action);
                 continue;
             }
-            if (action.type !== "strip-pi-requires-api-key" && action.type !== "add-harness-schema-ref") {
+            if (action.type !== "strip-pi-requires-api-key" &&
+                action.type !== "add-harness-schema-ref" &&
+                action.type !== "refresh-owned-file" &&
+                action.type !== "migrate-harness-governance-root" &&
+                action.type !== "migrate-harness-model-fields" &&
+                action.type !== "migrate-owned-file" &&
+                action.type !== "remove-owned-file" &&
+                action.type !== "remove-empty-directory") {
                 const currentState = await buildCurrentSurfaceState({
                     repoRoot,
                     projectName,
@@ -2169,8 +2622,7 @@ export async function runInitDoctor(input) {
     add("AGENTS.md loop-agent block", (await exists(agents)) && (await readFile(agents, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
     const readme = path.join(repoRoot, "README.md");
     add("README loop-agent block", (await exists(readme)) && (await readFile(readme, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
-    add("repo-local skills", await exists(path.join(repoRoot, "skills", "loop-agent", "SKILL.md")), "skills/loop-agent/SKILL.md");
-    add("agent-compatible skills mirror", await exists(path.join(repoRoot, ".agents", "skills", "loop-agent", "SKILL.md")), ".agents/skills/loop-agent/SKILL.md");
+    add("repo-local skills", await exists(path.join(repoRoot, ".agents", "skills", "loop-agent", "SKILL.md")), ".agents/skills/loop-agent/SKILL.md");
     const gitignorePath = path.join(repoRoot, ".gitignore");
     const gitignoreContent = (await exists(gitignorePath)) ? await readFile(gitignorePath, "utf-8") : "";
     add("gitignore loop-agent block", gitignoreContent.includes(GITIGNORE_BLOCK_START) && gitignoreContent.includes(".harness/tasks/*"), ".gitignore managed runtime ignores");
@@ -2192,7 +2644,7 @@ export async function runInitDoctor(input) {
 function parseInitArgs(repoRoot, args) {
     let subcommand;
     let projectName;
-    let governanceRoot = "docs";
+    let governanceRoot;
     let profile = "full";
     let merge = true;
     let provider;
@@ -2315,7 +2767,7 @@ function formatInitResult(result) {
         `written: ${result.written.length}`,
         `skipped: ${result.skipped.length}`,
         "next: loop-agent init doctor --repo-root <target>",
-        "model-executed init: continue automatically by inspecting the target project, adapting README.md, docs/verification-matrix.md, and scripts/ci-tests.sh when needed, then run inspect/docs audit/quick verification.",
+        `model-executed init: continue automatically by inspecting the target project, adapting README.md, ${result.governanceRoot}/verification-matrix.md, and scripts/ci-tests.sh when needed, then run inspect/docs audit/quick verification.`,
     ].join("\n");
 }
 export async function listInitializedFiles(repoRoot) {