@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/commands/init.js

@@ -0,0 +1,3630 @@
+import { createHash } from "node:crypto";
+import { access, copyFile, mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { fileURLToPath } from "node:url";
+import { isInitRuntimeActive, } from "../shared/runtime-activity.js";
+import { loadHarnessManifest } from "../governance/harness.js";
+import { OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH, OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH, PI_CONTEXT_OVERFLOW_EXTENSION_PATH, PI_PROJECT_SETTINGS_PATH, applyPiRetryMerge, applyProjectPiSettingsMerge, buildOpenCodeContextOverflowCompactPluginSource, buildProjectPiSettingsSource, buildOpenCodeTransientRetryPluginSource, buildPiContextOverflowExtensionSource, inspectProjectPiSettings, parseClientRecoveryMode, runClientRecovery, } from "./client-recovery.js";
+const MANAGED_BLOCK_START = "<!-- LOOP_AGENT_INIT_START -->";
+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 = [
+    { source: "README.md", target: "README.md" },
+    {
+        source: "architecture/runtime-boundaries.md",
+        target: "architecture/runtime-boundaries.md",
+    },
+    {
+        source: "governance/development-principles.md",
+        target: "development-principles.md",
+    },
+    { source: "governance/feature-workflow.md", target: "feature-workflow.md" },
+    {
+        source: "governance/verification-matrix.md",
+        target: "verification-matrix.md",
+    },
+    { source: "runtime/loop-agent-harness.md", target: "loop-agent-harness.md" },
+    {
+        source: "governance/harness-methodology-tdd.md",
+        target: "harness-methodology-tdd.md",
+    },
+    {
+        source: "governance/harness-methodology-verification.md",
+        target: "harness-methodology-verification.md",
+    },
+    {
+        source: "governance/harness-methodology-debugging.md",
+        target: "harness-methodology-debugging.md",
+    },
+    { source: "templates/README.md", target: "templates/README.md" },
+];
+function coreDocSourceForTarget(target) {
+    return (CORE_DOC_FILES.find((entry) => entry.target === target)?.source ?? target);
+}
+const GOVERNANCE_README_DIRS = [
+    "decisions",
+    "design",
+    "exec-plans",
+    "exec-plans/active",
+    "exec-plans/completed",
+    "progress",
+    "reports",
+];
+const DAG_HARD_GATE_TRIGGER = "For changes that affect the project's public contract, execution surface, delivery pipeline, automation/governance, data model, security or permission model, cross-module behavior, or user-visible workflows, this is a hard pre-edit gate: create the task, write both source files, generate the DAG, and review the DAG/writeSet before editing implementation files.";
+const COMPAT_PROMPTS = {
+    "analyze.md": [
+        "# Role: Task Analyst",
+        "",
+        "Read the repository entrypoints, task source materials, and relevant docs.",
+        "Return an analysis report covering objective, current state, affected files, constraints, risks, and open questions.",
+        "Do not modify files.",
+        "",
+    ].join("\n"),
+    "spec.md": [
+        "# Role: Specification Writer",
+        "",
+        "Turn the task source and analysis into a bounded implementation contract.",
+        "State scope, non-goals, acceptance criteria, allowed paths, forbidden paths, and verification commands.",
+        "Do not modify files outside task-owned artifacts.",
+        "",
+    ].join("\n"),
+    "plan.md": [
+        "# Role: Implementation Planner",
+        "",
+        "Create a minimal, ordered, verifiable implementation plan from the task source and analysis.",
+        "Keep the plan aligned with allowed paths, forbidden paths, hard constraints, rollback points, and verification.",
+        "Do not modify implementation files.",
+        "",
+    ].join("\n"),
+    "implement.md": [
+        "# Role: Bounded Implementer",
+        "",
+        "Implement the approved plan with the smallest focused change.",
+        "Stay within allowed paths and writeSet. Preserve unrelated user changes. Do not use placeholder implementations.",
+        "",
+    ].join("\n"),
+    "verify.md": [
+        "# Role: Verifier",
+        "",
+        "Run or specify deterministic verification for the completed change.",
+        "Report exact commands, pass/fail results, residual risk, and whether acceptance criteria are covered.",
+        "",
+    ].join("\n"),
+    "retrospective.md": [
+        "# Role: Retrospective Writer",
+        "",
+        "Summarize what changed, why, verification evidence, risks, and follow-up work.",
+        "Promote durable lessons to docs, reports, progress, tests, scripts, or templates when appropriate.",
+        "",
+    ].join("\n"),
+    "feature-study-analyze.md": [
+        "# Role: Feature Study Analyst",
+        "",
+        "Analyze configured reference repos/docs read-only. Identify architecture, state, data flow, and transferable patterns.",
+        "Do not edit reference repositories.",
+        "",
+    ].join("\n"),
+    "feature-study-plan.md": [
+        "# Role: Feature Study Planner",
+        "",
+        "Produce a lightweight implementation plan from the feature-study analysis.",
+        "Prefer simple recoverable files and verifiable increments over heavyweight storage or broad rewrites.",
+        "",
+    ].join("\n"),
+};
+const GOVERNANCE_ROOT_TOKEN = "__LOOP_AGENT_GOVERNANCE_ROOT__";
+const PROJECT_NAME_TOKEN = "__LOOP_AGENT_PROJECT_NAME__";
+/** Package-shipped render source for AGENTS.md managed block; not projected to target repos. */
+const MANAGED_AGENTS_TEMPLATE_PATH = "docs/templates/init-managed-agents.md";
+/** Files under package assets that init must not copy into target projects. */
+const PACKAGE_ONLY_SURFACE_FILES = new Set([MANAGED_AGENTS_TEMPLATE_PATH]);
+let managedAgentsTemplateCache;
+const INIT_CHECK_ENGINEERING_STRUCTURE_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+required_paths=(
+  "README.md"
+  "harness.json"
+  "AGENTS.md"
+  "${GOVERNANCE_ROOT_TOKEN}/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/development-principles.md"
+  "${GOVERNANCE_ROOT_TOKEN}/feature-workflow.md"
+  "${GOVERNANCE_ROOT_TOKEN}/verification-matrix.md"
+  "${GOVERNANCE_ROOT_TOKEN}/architecture/runtime-boundaries.md"
+  "${GOVERNANCE_ROOT_TOKEN}/templates"
+  ".agents/skills/loop-agent/SKILL.md"
+  ".harness/prompts/analyze.md"
+  ".harness/prompts/plan.md"
+  ".harness/tasks"
+  ".harness/dag-runs/active"
+  ".harness/dag-runs/completed"
+  ".harness/dag-runs/paused"
+  ".harness/runs/active"
+  ".harness/runs/completed"
+  ".harness/runs/failed"
+  "scripts/check-engineering-structure.sh"
+  "scripts/check-doc-index.sh"
+  "scripts/check-doc-links.sh"
+  "scripts/check-active-plan-status.sh"
+  "scripts/check-exec-plan-index-sync.sh"
+  "scripts/check-harness-runtime-clean.sh"
+  "scripts/check-architecture-boundaries.sh"
+  "scripts/check-skill-entry.sh"
+  "scripts/check-repo.sh"
+  "scripts/ci-governance.sh"
+  "scripts/ci-tests.sh"
+  "scripts/ci.sh"
+)
+
+missing=()
+for item in "\${required_paths[@]}"; do
+  if [[ ! -e "\${item}" ]]; then
+    missing+=("\${item}")
+  fi
+done
+
+if (( \${#missing[@]} > 0 )); then
+  echo "loop-agent 初始化检查失败，缺少必要路径："
+  for item in "\${missing[@]}"; do
+    echo "  - \${item}"
+  done
+  exit 1
+fi
+
+echo "loop-agent 工程结构检查通过"
+`;
+const INIT_CHECK_DOC_INDEX_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+required_docs=(
+  "${GOVERNANCE_ROOT_TOKEN}/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/development-principles.md"
+  "${GOVERNANCE_ROOT_TOKEN}/feature-workflow.md"
+  "${GOVERNANCE_ROOT_TOKEN}/verification-matrix.md"
+  "${GOVERNANCE_ROOT_TOKEN}/architecture/runtime-boundaries.md"
+  "${GOVERNANCE_ROOT_TOKEN}/loop-agent-harness.md"
+  "${GOVERNANCE_ROOT_TOKEN}/harness-methodology-tdd.md"
+  "${GOVERNANCE_ROOT_TOKEN}/harness-methodology-verification.md"
+  "${GOVERNANCE_ROOT_TOKEN}/harness-methodology-debugging.md"
+  "${GOVERNANCE_ROOT_TOKEN}/templates"
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/active/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/completed/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/progress/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/reports/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/decisions/README.md"
+)
+
+missing=()
+for item in "\${required_docs[@]}"; do
+  if [[ ! -e "\${item}" ]]; then
+    missing+=("\${item}")
+  fi
+done
+
+if (( \${#missing[@]} > 0 )); then
+  echo "docs 索引检查失败，缺少必要文档或目录：" >&2
+  for item in "\${missing[@]}"; do
+    echo "  - \${item}" >&2
+  done
+  exit 1
+fi
+
+echo "docs 索引检查通过"
+`;
+const INIT_CHECK_DOC_LINKS_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+if [[ ! -d "${GOVERNANCE_ROOT_TOKEN}" ]]; then
+  echo "docs 链接检查失败：缺少 ${GOVERNANCE_ROOT_TOKEN}/" >&2
+  exit 1
+fi
+
+missing=()
+while IFS= read -r -d '' file; do
+  while IFS= read -r link; do
+    [[ -z "\${link}" ]] && continue
+    [[ "\${link}" == http://* || "\${link}" == https://* || "\${link}" == mailto:* || "\${link}" == "#"* ]] && continue
+    [[ "\${link}" == *"://"* ]] && continue
+    target="\${link%%#*}"
+    [[ -z "\${target}" ]] && continue
+    [[ "\${target}" == /* ]] && continue
+    base="$(dirname "\${file}")"
+    if [[ ! -e "\${base}/\${target}" ]]; then
+      missing+=("\${file}: \${link}")
+    fi
+  done < <(grep -Eo '\\[[^]]+\\]\\([^)]+\\)' "\${file}" | sed -E 's/^.*\\(([^)]+)\\)$/\\1/' || true)
+done < <(find "${GOVERNANCE_ROOT_TOKEN}" -type f -name '*.md' -print0)
+
+if (( \${#missing[@]} > 0 )); then
+  echo "docs 链接检查失败：" >&2
+  for item in "\${missing[@]}"; do
+    echo "  - \${item}" >&2
+  done
+  exit 1
+fi
+
+echo "docs 链接检查通过"
+`;
+const INIT_CHECK_ACTIVE_PLAN_STATUS_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+active_dir="${GOVERNANCE_ROOT_TOKEN}/exec-plans/active"
+[[ -d "\${active_dir}" ]] || { echo "active plan 检查失败：缺少 \${active_dir}" >&2; exit 1; }
+
+bad=()
+while IFS= read -r -d '' file; do
+  name="$(basename "\${file}")"
+  [[ "\${name}" == "README.md" ]] && continue
+  if grep -Eiq 'status:[[:space:]]*(completed|done|closed)|状态[:：][[:space:]]*(已完成|完成|关闭)' "\${file}"; then
+    bad+=("\${file}")
+  fi
+done < <(find "\${active_dir}" -maxdepth 1 -type f -name '*.md' -print0)
+
+if (( \${#bad[@]} > 0 )); then
+  echo "active plan 状态检查失败：已完成计划不应留在 active 目录：" >&2
+  for item in "\${bad[@]}"; do
+    echo "  - \${item}" >&2
+  done
+  exit 1
+fi
+
+echo "active plan 状态检查通过"
+`;
+const INIT_CHECK_EXEC_PLAN_INDEX_SYNC_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+required=(
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/active/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/completed/README.md"
+)
+
+for item in "\${required[@]}"; do
+  if [[ ! -f "\${item}" ]]; then
+    echo "exec-plan 索引同步检查失败：缺少 \${item}" >&2
+    exit 1
+  fi
+done
+
+echo "exec-plan 索引同步检查通过"
+`;
+const INIT_CHECK_HARNESS_RUNTIME_CLEAN_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+failures=()
+
+count_entries() {
+  local dir="$1"
+  if [[ ! -d "\${dir}" ]]; then
+    echo 0
+    return
+  fi
+  find "\${dir}" -mindepth 1 -maxdepth 1 ! -name .gitkeep | wc -l | tr -d ' '
+}
+
+if [[ "\${HARNESS_ALLOW_ACTIVE_DAG_RUNS:-}" != "1" ]]; then
+  active_dag_count="$(count_entries ".harness/dag-runs/active")"
+  [[ "\${active_dag_count}" == "0" ]] || failures+=(".harness/dag-runs/active contains \${active_dag_count} entries")
+fi
+
+if [[ "\${HARNESS_ALLOW_ACTIVE_TOOL_RUNS:-\${HARNESS_ALLOW_ACTIVE_ONE_SHOT_RUNS:-}}" != "1" ]]; then
+  active_run_count="$(count_entries ".harness/runs/active")"
+  [[ "\${active_run_count}" == "0" ]] || failures+=(".harness/runs/active contains \${active_run_count} entries")
+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 ${GOVERNANCE_ROOT_TOKEN}/reports or .harness run artifacts")
+fi
+
+if (( \${#failures[@]} > 0 )); then
+  echo "[HARNESS RUNTIME DIRTY]" >&2
+  for item in "\${failures[@]}"; do
+    echo "  - \${item}" >&2
+  done
+  exit 1
+fi
+
+echo "harness runtime clean check passed"
+`;
+const INIT_CHECK_ARCHITECTURE_BOUNDARIES_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+boundary_doc="${GOVERNANCE_ROOT_TOKEN}/architecture/runtime-boundaries.md"
+if [[ ! -f "\${boundary_doc}" ]]; then
+  echo "architecture boundary 检查失败：缺少 \${boundary_doc}" >&2
+  exit 1
+fi
+
+violations=()
+
+check_ts_import_boundary() {
+  local from_dir="$1"
+  local forbidden_dir="$2"
+  local label="$3"
+  [[ -d "\${from_dir}" && -d "\${forbidden_dir}" ]] || return 0
+  while IFS= read -r -d '' file; do
+    if grep -Eq "from ['\\"][^'\\"]*\${forbidden_dir}/|import\\(['\\"][^'\\"]*\${forbidden_dir}/|require\\(['\\"][^'\\"]*\${forbidden_dir}/" "\${file}"; then
+      violations+=("\${label}: \${file} imports \${forbidden_dir}")
+    fi
+  done < <(find "\${from_dir}" -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' -o -name '*.cjs' \\) -print0)
+}
+
+# These checks are intentionally optional and stack-agnostic. They activate only
+# when a target repository has recognizable source directories.
+check_ts_import_boundary "src/workflows" "src/commands" "workflow-runtime"
+check_ts_import_boundary "src/executors" "src/commands" "executors"
+check_ts_import_boundary "src/domain" "src/infrastructure" "domain"
+
+if (( \${#violations[@]} > 0 )); then
+  echo "architecture boundary 检查失败：" >&2
+  for item in "\${violations[@]}"; do
+    echo "  - \${item}" >&2
+  done
+  echo "请更新 \${boundary_doc} 中的层边界，或修正反向依赖。" >&2
+  exit 1
+fi
+
+echo "architecture boundary 检查通过"
+`;
+const INIT_CHECK_SKILL_ENTRY_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+check_skill() {
+  local skill_name="$1"
+  shift
+  local skill_dir=".agents/skills/\${skill_name}"
+  local skill_md="\${skill_dir}/SKILL.md"
+  local missing=()
+
+  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")
+
+  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
+
+  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}"
+}
+
+check_skill "loop-agent" \\
+  "references/harness-policy.md" \\
+  "references/hybrid-dag.md" \\
+  "references/verification-and-failure-handling.md" \\
+  "references/command-reference.md" \\
+  "references/source-and-plan-practice.md"
+check_skill "agent-worker" "references/agent-worker-operator.md"
+
+# loop-agent description is a YAML folded block (>-); grep ^description: only
+# captures the indicator line. Validate the general-demand trigger terms
+# against the whole skill file so host auto-discovery phrasing cannot drift.
+loop_agent_skill=".agents/skills/loop-agent/SKILL.md"
+loop_agent_text="$(tr '[:upper:]' '[:lower:]' < "\${loop_agent_skill}")"
+for term in "loop-agent 帮我完成" "帮我实现" "帮我修复" "帮我开发" "agent dag" "task advance" "task status" "dag validate" "dag execute"; do
+  if [[ "\${loop_agent_text}" != *"\${term}"* ]]; then
+    echo "skill entry 检查失败（loop-agent）：description 缺少触发/路由词 \${term}" >&2
+    exit 1
+  fi
+done
+
+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
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+checks=(
+  "scripts/check-engineering-structure.sh"
+  "scripts/check-doc-index.sh"
+  "scripts/check-doc-links.sh"
+  "scripts/check-active-plan-status.sh"
+  "scripts/check-exec-plan-index-sync.sh"
+  "scripts/check-harness-runtime-clean.sh"
+  "scripts/check-architecture-boundaries.sh"
+  "scripts/check-skill-entry.sh"
+  "scripts/check-product-line-docs.sh"
+)
+
+for check in "\${checks[@]}"; do
+  echo "==> bash \${check}"
+  bash "\${check}"
+  echo
+done
+
+echo "仓库治理检查全部通过"
+`;
+const INIT_CHECK_PRODUCT_LINE_DOCS_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+if ! command -v agent-worker >/dev/null 2>&1; then
+  echo "product-line docs check skipped: agent-worker is not installed"
+  exit 0
+fi
+
+feature_dirs=()
+for root in features product/features dogfood/features; do
+  [[ -d "\${root}" ]] || continue
+  while IFS= read -r feature_dir; do
+    if [[ ! -f "\${feature_dir}/acceptance.yaml" ]]; then
+      echo "product-line docs check failed: incomplete feature packet missing acceptance.yaml: \${feature_dir}" >&2
+      exit 1
+    fi
+    feature_dirs+=("\${feature_dir}")
+  done < <(find "\${root}" -mindepth 1 -maxdepth 1 -type d | sort)
+done
+
+if [[ \${#feature_dirs[@]} -eq 0 ]]; then
+  echo "product-line docs check skipped: no feature packets found"
+  exit 0
+fi
+
+for feature_dir in "\${feature_dirs[@]}"; do
+  echo "==> validate product-line feature: \${feature_dir}"
+  agent-worker task validate-feature "\${feature_dir}"
+done
+
+echo "product-line docs checks passed: \${#feature_dirs[@]} feature packet(s)"
+`;
+const INIT_CI_GOVERNANCE_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+bash scripts/check-repo.sh
+`;
+const INIT_CI_TESTS_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+ran=0
+notes=()
+
+run_cmd() {
+  echo "==> $*"
+  "$@"
+  ran=1
+}
+
+run_bash() {
+  echo "==> $*"
+  bash -lc "$*"
+  ran=1
+}
+
+has_make_target() {
+  local target="$1"
+  [[ -f Makefile || -f makefile ]] || return 1
+  grep -Eq "^[[:alnum:]_.-]*\${target}[[:alnum:]_.-]*:" Makefile makefile 2>/dev/null
+}
+
+has_npm_script() {
+  local script="$1"
+  [[ -f package.json ]] || return 1
+  command -v node >/dev/null 2>&1 || return 1
+  node -e "const fs=require('fs'); const p=JSON.parse(fs.readFileSync('package.json','utf8')); process.exit(p.scripts && p.scripts[process.argv[1]] ? 0 : 1)" "\${script}" >/dev/null 2>&1
+}
+
+dag_lint_assessment_allows_skip() {
+  [[ -n "\${HARNESS_DAG_RUN_DIR:-}" ]] || return 1
+  command -v node >/dev/null 2>&1 || return 1
+  node - "\${HARNESS_DAG_RUN_DIR}" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const runDir = path.resolve(process.argv[2]);
+const assessmentPath = path.join(runDir, "contracts", "frontend-lint-assessment.json");
+const fail = () => process.exit(1);
+const sha256 = (value) => crypto.createHash("sha256").update(value).digest("hex");
+const readContained = (relative) => {
+  if (typeof relative !== "string" || path.isAbsolute(relative)) fail();
+  const absolute = path.resolve(runDir, relative);
+  if (absolute !== runDir && !absolute.startsWith(runDir + path.sep)) fail();
+  return fs.readFileSync(absolute);
+};
+let assessment;
+try {
+  assessment = JSON.parse(fs.readFileSync(assessmentPath, "utf8"));
+} catch {
+  fail();
+}
+if (
+  assessment.schemaVersion !== 1 ||
+  assessment.schemaId !== "frontend-lint-assessment-v1" ||
+  !["passed", "baseline-debt"].includes(assessment.status) ||
+  !assessment.commandIdentity ||
+  !Array.isArray(assessment.commandIdentity.commands) ||
+  assessment.commandIdentity.commands.length === 0 ||
+  !Array.isArray(assessment.writerChangedFiles) ||
+  !Array.isArray(assessment.blockingDiagnostics) ||
+  assessment.blockingDiagnostics.length !== 0 ||
+  !Array.isArray(assessment.blockingReasons) ||
+  assessment.blockingReasons.length !== 0
+) fail();
+const commandHash = sha256(JSON.stringify(assessment.commandIdentity.commands));
+if (commandHash !== assessment.commandIdentity.sha256) fail();
+if (!assessment.commandIdentity.commands.every((command) =>
+  /(?:^|[\\s'"])npm(?:['"])?\\s+(?:['"])?run(?:['"])?\\s+(?:['"])?lint(?:['"])?(?:\\s|$)/.test(command)
+)) fail();
+if (
+  (assessment.status === "passed" && assessment.currentExitCode !== 0) ||
+  (assessment.status === "baseline-debt" && assessment.currentExitCode === 0)
+) fail();
+if (!assessment.baselineRef || assessment.baselineRef.nodeId !== "frontend-lint-baseline-shell") fail();
+const baselineRaw = readContained(assessment.baselineRef.path);
+if (sha256(baselineRaw) !== assessment.baselineRef.sha256) fail();
+let baseline;
+try {
+  baseline = JSON.parse(baselineRaw);
+} catch {
+  fail();
+}
+if (
+  baseline.schemaVersion !== 1 ||
+  baseline.schemaId !== "frontend-lint-baseline-v1" ||
+  baseline.status !== "available" ||
+  baseline.commandIdentity?.sha256 !== assessment.commandIdentity.sha256
+) fail();
+if (assessment.status === "baseline-debt") {
+  if (
+    !Array.isArray(assessment.currentDiagnostics) ||
+    assessment.currentDiagnostics.length === 0 ||
+    assessment.currentDiagnostics.length !== assessment.toleratedDiagnosticCount ||
+    !Array.isArray(baseline.diagnostics)
+  ) fail();
+  const key = (item) => JSON.stringify([
+    item.file, item.line, item.column, item.severity, item.message, item.ruleId ?? null,
+  ]);
+  const baselineCounts = new Map();
+  for (const item of baseline.diagnostics) {
+    const value = key(item);
+    baselineCounts.set(value, (baselineCounts.get(value) || 0) + 1);
+  }
+  const changed = new Set(assessment.writerChangedFiles);
+  for (const item of assessment.currentDiagnostics) {
+    if (changed.has(item.file)) fail();
+    const value = key(item);
+    const count = baselineCounts.get(value) || 0;
+    if (count === 0) fail();
+    baselineCounts.set(value, count - 1);
+  }
+}
+if (!Array.isArray(assessment.rawEvidenceRefs) || assessment.rawEvidenceRefs.length === 0) fail();
+for (const ref of assessment.rawEvidenceRefs) {
+  if (sha256(readContained(ref.path)) !== ref.sha256) fail();
+}
+process.exit(0);
+NODE
+}
+
+if [[ -f package.json ]]; then
+  if command -v npm >/dev/null 2>&1; then
+    for script in lint typecheck test build; do
+      if has_npm_script "\${script}"; then
+        if [[ "\${script}" == "lint" ]] && dag_lint_assessment_allows_skip; then
+          echo "==> lint handled by frontend DAG assessment (status: passed or baseline-debt)"
+          ran=1
+          continue
+        fi
+        run_cmd npm run "\${script}"
+      fi
+    done
+  else
+    notes+=("package.json exists but npm is not available")
+  fi
+fi
+
+if has_make_target verify; then
+  run_cmd make verify
+elif has_make_target test; then
+  run_cmd make test
+fi
+
+if [[ -f go.mod ]]; then
+  if command -v go >/dev/null 2>&1; then
+    run_cmd go test ./...
+  else
+    notes+=("go.mod exists but go is not available")
+  fi
+fi
+
+if [[ -f Cargo.toml ]]; then
+  if command -v cargo >/dev/null 2>&1; then
+    run_cmd cargo test
+  else
+    notes+=("Cargo.toml exists but cargo is not available")
+  fi
+fi
+
+if [[ -f pyproject.toml || -f pytest.ini || -f tox.ini ]]; then
+  if command -v pytest >/dev/null 2>&1; then
+    run_cmd pytest
+  elif command -v tox >/dev/null 2>&1 && [[ -f tox.ini ]]; then
+    run_cmd tox
+  else
+    notes+=("Python project metadata found but pytest/tox is not available")
+  fi
+fi
+
+if [[ -f pom.xml ]]; then
+  if command -v mvn >/dev/null 2>&1; then
+    run_cmd mvn test
+  else
+    notes+=("pom.xml exists but mvn is not available")
+  fi
+fi
+
+if [[ -f build.gradle || -f build.gradle.kts || -f settings.gradle || -f settings.gradle.kts ]]; then
+  if [[ -x ./gradlew ]]; then
+    run_cmd ./gradlew test
+  elif command -v gradle >/dev/null 2>&1; then
+    run_cmd gradle test
+  else
+    notes+=("Gradle project metadata found but gradle/gradlew is not available")
+  fi
+fi
+
+if compgen -G "*.sln" >/dev/null || compgen -G "*.csproj" >/dev/null; then
+  if command -v dotnet >/dev/null 2>&1; then
+    run_cmd dotnet test
+  else
+    notes+=(".NET project metadata found but dotnet is not available")
+  fi
+fi
+
+if (( ran == 0 )); then
+  echo "未检测到可安全自动运行的项目测试入口。"
+  echo "loop-agent 治理检查仍可运行；请让初始化模型根据目标项目技术栈补充 scripts/ci-tests.sh 与 ${GOVERNANCE_ROOT_TOKEN}/verification-matrix.md。"
+fi
+
+if (( \${#notes[@]} > 0 )); then
+  echo "项目验证探测备注："
+  for note in "\${notes[@]}"; do
+    echo "  - \${note}"
+  done
+fi
+`;
+const INIT_CI_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+bash scripts/ci-governance.sh
+bash scripts/ci-tests.sh
+`;
+const INIT_SCRIPT_FILES = {
+    "scripts/check-engineering-structure.sh": INIT_CHECK_ENGINEERING_STRUCTURE_SH,
+    "scripts/check-doc-index.sh": INIT_CHECK_DOC_INDEX_SH,
+    "scripts/check-doc-links.sh": INIT_CHECK_DOC_LINKS_SH,
+    "scripts/check-active-plan-status.sh": INIT_CHECK_ACTIVE_PLAN_STATUS_SH,
+    "scripts/check-exec-plan-index-sync.sh": INIT_CHECK_EXEC_PLAN_INDEX_SYNC_SH,
+    "scripts/check-harness-runtime-clean.sh": INIT_CHECK_HARNESS_RUNTIME_CLEAN_SH,
+    "scripts/check-architecture-boundaries.sh": INIT_CHECK_ARCHITECTURE_BOUNDARIES_SH,
+    "scripts/check-skill-entry.sh": INIT_CHECK_SKILL_ENTRY_SH,
+    "scripts/check-product-line-docs.sh": INIT_CHECK_PRODUCT_LINE_DOCS_SH,
+    "scripts/check-repo.sh": INIT_CHECK_REPO_SH,
+    "scripts/ci-governance.sh": INIT_CI_GOVERNANCE_SH,
+    "scripts/ci-tests.sh": INIT_CI_TESTS_SH,
+    "scripts/ci.sh": INIT_CI_SH,
+};
+function buildInitScriptFiles(governanceRoot) {
+    return Object.fromEntries(Object.entries(INIT_SCRIPT_FILES).map(([relativePath, content]) => [
+        relativePath,
+        content.replaceAll(GOVERNANCE_ROOT_TOKEN, governanceRoot),
+    ]));
+}
+function repoRelative(targetRoot, filePath) {
+    return path.relative(targetRoot, filePath).split(path.sep).join("/");
+}
+async function exists(filePath) {
+    return Boolean(await stat(filePath).catch(() => null));
+}
+async function findPackageRoot() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (await exists(path.join(current, "package.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.resolve(".");
+        current = parent;
+    }
+}
+async function readJsonIfExists(filePath) {
+    if (!(await exists(filePath)))
+        return {};
+    return JSON.parse(await readFile(filePath, "utf-8"));
+}
+function mergeRecord(base, patch) {
+    return {
+        ...(typeof base === "object" && base !== null && !Array.isArray(base)
+            ? base
+            : {}),
+        ...patch,
+    };
+}
+async function loadManagedAgentsTemplate(assetRoot) {
+    if (managedAgentsTemplateCache !== undefined)
+        return managedAgentsTemplateCache;
+    const templatePath = path.join(assetRoot, MANAGED_AGENTS_TEMPLATE_PATH);
+    const raw = await readFile(templatePath, "utf-8");
+    // Prefer a START marker on its own line so header notes mentioning the token are ignored.
+    const lines = raw.split(/\r?\n/);
+    const startLine = lines.findIndex((line) => line.trim() === MANAGED_BLOCK_START);
+    const endLine = startLine >= 0
+        ? lines.findIndex((line, index) => index > startLine && line.trim() === MANAGED_BLOCK_END)
+        : -1;
+    if (startLine < 0 || endLine < 0) {
+        throw new Error(`managed agents template missing LOOP_AGENT_INIT markers: ${MANAGED_AGENTS_TEMPLATE_PATH}`);
+    }
+    managedAgentsTemplateCache = lines.slice(startLine, endLine + 1).join("\n");
+    return managedAgentsTemplateCache;
+}
+async function buildManagedAgentsBlock(input) {
+    const template = await loadManagedAgentsTemplate(input.assetRoot);
+    return template
+        .replaceAll(PROJECT_NAME_TOKEN, input.projectName)
+        .replaceAll(GOVERNANCE_ROOT_TOKEN, input.governanceRoot);
+}
+function mergeManagedBlock(existing, block) {
+    const start = existing.indexOf(MANAGED_BLOCK_START);
+    const end = existing.indexOf(MANAGED_BLOCK_END);
+    if (start >= 0 && end > start) {
+        return (`${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + MANAGED_BLOCK_END.length).trimStart()}`.trimEnd() +
+            "\n");
+    }
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+function mergeGitignoreManagedBlock(existing, block) {
+    const start = existing.indexOf(GITIGNORE_BLOCK_START);
+    const end = existing.indexOf(GITIGNORE_BLOCK_END);
+    if (start >= 0 && end > start) {
+        return (`${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + GITIGNORE_BLOCK_END.length).trimStart()}`.trimEnd() +
+            "\n");
+    }
+    if (!existing.trim())
+        return `${block}\n`;
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+/**
+ * Shared ignore rules for loop-agent runtime facts. The four directories are
+ * local, rebuildable runtime surface: every developer runs loop-agent init
+ * after cloning, so nothing inside them is team-shareable by default.
+ * `scripts/` and `ai_workspace/loop-agent/` stay on the shared commit surface.
+ */
+export function buildManagedGitignoreBlock() {
+    return [
+        GITIGNORE_BLOCK_START,
+        "# loop-agent runtime: local, rebuildable facts; do not ignore scripts/ or ai_workspace/loop-agent/",
+        ".harness/",
+        ".agents/",
+        ".task-pool/",
+        ".worktrees/",
+        GITIGNORE_BLOCK_END,
+    ].join("\n");
+}
+function extractGitignoreManagedBlock(content) {
+    const start = content.indexOf(GITIGNORE_BLOCK_START);
+    const end = content.indexOf(GITIGNORE_BLOCK_END);
+    if (start < 0 || end <= start)
+        return undefined;
+    return content.slice(start, end + GITIGNORE_BLOCK_END.length);
+}
+function buildHarness(input) {
+    const templateExecutors = isRecord(input.template.executors)
+        ? { ...input.template.executors }
+        : {};
+    const existingExecutors = isRecord(input.existing.executors)
+        ? input.existing.executors
+        : {};
+    // 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) {
+        const pi = { ...mergedExecutors.pi };
+        delete pi.requiresApiKey;
+        mergedExecutors.pi = pi;
+    }
+    // Init always writes a Pi tier matrix. `defaultModel` remains runtime
+    // compatibility for old projects only and is never fresh-init output.
+    if (input.model) {
+        const piExisting = isRecord(mergedExecutors.pi) ? mergedExecutors.pi : {};
+        mergedExecutors.pi = {
+            ...piExisting,
+            LOW: input.model,
+            MED: input.model,
+            HIGH: input.model,
+        };
+    }
+    if (isRecord(mergedExecutors.pi)) {
+        const pi = { ...mergedExecutors.pi };
+        if (hasCompletePiTierMatrix(pi))
+            delete pi.defaultModel;
+        mergedExecutors.pi = pi;
+    }
+    const harness = {
+        ...input.existing,
+        $schema: expectedHarnessSchemaRef(input.governanceRoot),
+        version: 1,
+        project: input.projectName,
+        adapter: "loop-agent",
+        governanceRoot: input.governanceRoot,
+        features: mergeRecord(input.template.features, input.existing.features),
+        workflowPolicy: mergeRecord(input.template.workflowPolicy, input.existing.workflowPolicy),
+        entrypoints: mergeRecord(input.existing.entrypoints, {
+            readme: "README.md",
+            agents: "AGENTS.md",
+            governanceIndex: `${input.governanceRoot}/README.md`,
+            principles: `${input.governanceRoot}/development-principles.md`,
+            workflow: `${input.governanceRoot}/feature-workflow.md`,
+            verificationMatrix: `${input.governanceRoot}/verification-matrix.md`,
+            loopAgentHarness: `${input.governanceRoot}/loop-agent-harness.md`,
+        }),
+        artifacts: mergeRecord(input.existing.artifacts, {
+            templatesDir: `${input.governanceRoot}/templates`,
+            execPlansDir: `${input.governanceRoot}/exec-plans`,
+            progressDir: `${input.governanceRoot}/progress`,
+            reportsDir: `${input.governanceRoot}/reports`,
+            decisionsDir: `${input.governanceRoot}/decisions`,
+            taskPoolDir: ".harness/task-pool",
+        }),
+        scripts: mergeRecord(input.existing.scripts, {
+            checkEngineeringStructure: "scripts/check-engineering-structure.sh",
+            checkDocIndex: "scripts/check-doc-index.sh",
+            checkDocLinks: "scripts/check-doc-links.sh",
+            checkActivePlanStatus: "scripts/check-active-plan-status.sh",
+            checkExecPlanIndexSync: "scripts/check-exec-plan-index-sync.sh",
+            checkHarnessRuntimeClean: "scripts/check-harness-runtime-clean.sh",
+            checkArchitectureBoundaries: "scripts/check-architecture-boundaries.sh",
+            checkSkillEntry: "scripts/check-skill-entry.sh",
+            checkRepo: "scripts/check-repo.sh",
+            ciGovernance: "scripts/ci-governance.sh",
+            ciTests: "scripts/ci-tests.sh",
+            ci: "scripts/ci.sh",
+            quickVerify: "bash scripts/check-repo.sh",
+            standardVerify: "bash scripts/ci-governance.sh",
+            fullVerify: "bash scripts/ci.sh",
+        }),
+        executors: mergedExecutors,
+    };
+    // Fresh init owns only the current DAG-facing surface. Legacy step routing is
+    // diagnosed by check-update rather than copied into a new harness projection.
+    for (const legacyField of [
+        "model",
+        "models",
+        "modelProfiles",
+        "modelRouting",
+        "verify",
+        "sequentialWorkflowRole",
+    ]) {
+        delete harness[legacyField];
+    }
+    return harness;
+}
+async function writeTextIfMissing(input) {
+    const target = path.join(input.repoRoot, input.relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (await exists(target)) {
+        input.skipped.push(input.relativePath);
+        return;
+    }
+    await writeFile(target, input.content, "utf-8");
+    input.written.push(input.relativePath);
+}
+async function writeText(input) {
+    const target = path.join(input.repoRoot, input.relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (!input.merge && (await exists(target))) {
+        input.skipped.push(input.relativePath);
+        return;
+    }
+    await writeFile(target, input.content, "utf-8");
+    input.written.push(input.relativePath);
+}
+async function copyFileIfMissing(input) {
+    const source = path.join(input.assetRoot, input.sourceRelativePath);
+    const target = path.join(input.repoRoot, input.targetRelativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    if ((await exists(target)) && !input.merge) {
+        input.skipped.push(input.targetRelativePath);
+        return;
+    }
+    if (await exists(target)) {
+        input.skipped.push(input.targetRelativePath);
+        return;
+    }
+    await copyFile(source, target);
+    input.written.push(input.targetRelativePath);
+}
+async function copyDirMerge(input) {
+    const source = path.join(input.assetRoot, input.sourceRelativePath);
+    const target = path.join(input.repoRoot, input.targetRelativePath);
+    const sourcePrefix = `${input.sourceRelativePath.replaceAll(path.sep, "/").replace(/\/$/, "")}/`;
+    await copyDirSkippingPackageOnly({
+        source,
+        target,
+        packageRelativePrefix: sourcePrefix,
+    });
+    input.written.push(input.targetRelativePath.endsWith("/")
+        ? input.targetRelativePath
+        : `${input.targetRelativePath}/`);
+}
+/** Like copyDir, but skips package-only assets that must not land in target projects. */
+async function copyDirSkippingPackageOnly(input) {
+    await mkdir(input.target, { recursive: true });
+    const entries = await readdir(input.source, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(input.source, entry.name);
+        const destPath = path.join(input.target, entry.name);
+        const packageRelative = `${input.packageRelativePrefix}${entry.name}`;
+        if (entry.isDirectory()) {
+            await copyDirSkippingPackageOnly({
+                source: srcPath,
+                target: destPath,
+                packageRelativePrefix: `${packageRelative}/`,
+            });
+            continue;
+        }
+        if (PACKAGE_ONLY_SURFACE_FILES.has(packageRelative))
+            continue;
+        if (entry.isFile() || entry.isSymbolicLink()) {
+            await copyFile(srcPath, destPath);
+        }
+    }
+}
+async function ensureHarnessDirs(repoRoot, written) {
+    const dirs = [
+        ".harness/prompts",
+        ".harness/tasks",
+        ".harness/dag-runs/active",
+        ".harness/dag-runs/completed",
+        ".harness/dag-runs/paused",
+        ".harness/runs/active",
+        ".harness/runs/completed",
+        ".harness/runs/failed",
+        ".harness/cache",
+        ".harness/live",
+    ];
+    for (const dir of dirs) {
+        await mkdir(path.join(repoRoot, dir), { recursive: true });
+        written.push(dir);
+    }
+    // No .gitkeep placeholders: .harness/ is fully ignored by the managed
+    // gitignore block, and runtime dirs are recreated on demand by init/doctor.
+}
+async function writeCompatPrompts(input) {
+    for (const [name, content] of Object.entries(COMPAT_PROMPTS)) {
+        await writeText({
+            repoRoot: input.repoRoot,
+            relativePath: path.join(".harness", "prompts", name),
+            content,
+            merge: input.merge,
+            written: input.written,
+            skipped: input.skipped,
+        });
+    }
+}
+function sha256Text(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function sha256Buffer(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A complete matrix has three effective values, not just three present keys. */
+function hasCompletePiTierMatrix(pi) {
+    return ["LOW", "MED", "HIGH"].every((tier) => {
+        const value = pi[tier];
+        if (typeof value === "string")
+            return value.length > 0 && value !== "default";
+        if (!isRecord(value))
+            return false;
+        const keys = Object.keys(value);
+        if (!keys.every((key) => key === "model" || key === "thinking"))
+            return false;
+        if (typeof value.model !== "string" || value.model.length === 0)
+            return false;
+        if (value.model === "default")
+            return false;
+        return value.thinking === undefined || typeof value.thinking === "string";
+    });
+}
+/** Resolve init CLI input to one unambiguous Pi `provider/model` reference. */
+export function normalizeInitModelReference(input) {
+    const provider = input.provider?.trim();
+    const model = input.model?.trim();
+    if (input.provider !== undefined && !provider) {
+        throw new Error("init --provider must be a non-empty provider id");
+    }
+    if (input.model !== undefined && !model) {
+        throw new Error("init --model must be a non-empty model reference");
+    }
+    if (provider && !model) {
+        throw new Error("init --provider requires --model");
+    }
+    if (!model)
+        return undefined;
+    const slash = model.indexOf("/");
+    if (slash < 0) {
+        if (!provider) {
+            throw new Error("init --model must be a provider/model reference or be paired with --provider");
+        }
+        if (/\s|\//.test(provider) || /\s/.test(model)) {
+            throw new Error("init provider/model values must not contain whitespace");
+        }
+        return `${provider}/${model}`;
+    }
+    const modelProvider = model.slice(0, slash);
+    const modelId = model.slice(slash + 1);
+    if (!modelProvider || !modelId || /\s/.test(modelProvider) || /\s/.test(modelId)) {
+        throw new Error("init --model must use a non-empty provider/model reference");
+    }
+    if (provider && provider !== modelProvider) {
+        throw new Error("init --provider conflicts with the provider qualified in --model");
+    }
+    return model;
+}
+function normalizeRelativePath(relativePath) {
+    return relativePath.split(path.sep).join("/");
+}
+function expectedHarnessSchemaRef(governanceRoot) {
+    return `./${governanceRoot}/templates/harness.schema.json`;
+}
+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) {
+    const packageJson = JSON.parse(await readFile(path.join(assetRoot, "package.json"), "utf-8"));
+    return typeof packageJson.version === "string"
+        ? packageJson.version
+        : "0.0.0";
+}
+async function readInitSurfaceManifest(assetRoot) {
+    const manifestPath = path.join(assetRoot, "docs", "init-surface.manifest.json");
+    const raw = await readFile(manifestPath, "utf-8");
+    const manifest = JSON.parse(raw);
+    const initFullRequired = manifest.initFullRequired ?? [];
+    const initSurface = manifest.initSurface ?? {};
+    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) {
+            const manifestPath = `${prefix}${relativePath}`;
+            if (PACKAGE_ONLY_SURFACE_FILES.has(manifestPath))
+                continue;
+            discovered.push(manifestPath);
+        }
+    }
+    return discovered.sort();
+}
+function inferInitSurfaceMode(relativePath) {
+    if (relativePath === INIT_SURFACE_STATE_PATH)
+        return "state";
+    if (relativePath === ".harness/tasks" ||
+        relativePath === ".harness/dag-runs/active" ||
+        relativePath.endsWith("/")) {
+        return "directory";
+    }
+    if (relativePath === "README.md" ||
+        relativePath === "AGENTS.md" ||
+        relativePath === ".gitignore") {
+        return "managed-block";
+    }
+    if (relativePath === "harness.json" ||
+        relativePath === OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH ||
+        relativePath === OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH ||
+        relativePath === PI_CONTEXT_OVERFLOW_EXTENSION_PATH ||
+        relativePath === PI_PROJECT_SETTINGS_PATH ||
+        relativePath.startsWith("scripts/") ||
+        relativePath.startsWith(".harness/prompts/") ||
+        relativePath.startsWith("docs/README.md") ||
+        relativePath.startsWith("docs/development-principles.md") ||
+        relativePath.startsWith("docs/feature-workflow.md") ||
+        relativePath.startsWith("docs/verification-matrix.md") ||
+        relativePath.startsWith("docs/loop-agent-harness.md") ||
+        relativePath.startsWith("docs/architecture/runtime-boundaries.md")) {
+        return "generated";
+    }
+    return "copied";
+}
+async function buildDesiredSurfaceContent(input) {
+    const manifestPath = targetPathToManifestPath(input.entry.path, input.governanceRoot);
+    if (input.entry.mode === "directory" || input.entry.mode === "state")
+        return {};
+    if (manifestPath === "README.md") {
+        return {
+            content: buildManagedReadmeBlock({
+                projectName: input.projectName,
+                governanceRoot: input.governanceRoot,
+            }),
+        };
+    }
+    if (manifestPath === "AGENTS.md") {
+        return {
+            content: await buildManagedAgentsBlock({
+                assetRoot: input.assetRoot,
+                projectName: input.projectName,
+                governanceRoot: input.governanceRoot,
+            }),
+        };
+    }
+    if (manifestPath === ".gitignore") {
+        return { content: buildManagedGitignoreBlock() };
+    }
+    if (manifestPath === "harness.json") {
+        const template = await readJsonIfExists(path.join(input.assetRoot, "harness.json"));
+        return {
+            content: `${JSON.stringify(buildHarness({
+                existing: {},
+                template,
+                projectName: input.projectName,
+                governanceRoot: input.governanceRoot,
+            }), null, 2)}\n`,
+        };
+    }
+    if (manifestPath === OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH) {
+        return { content: buildOpenCodeTransientRetryPluginSource() };
+    }
+    if (manifestPath === OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH) {
+        return { content: buildOpenCodeContextOverflowCompactPluginSource() };
+    }
+    if (manifestPath === PI_CONTEXT_OVERFLOW_EXTENSION_PATH) {
+        return { content: buildPiContextOverflowExtensionSource() };
+    }
+    if (manifestPath === PI_PROJECT_SETTINGS_PATH) {
+        return { content: buildProjectPiSettingsSource() };
+    }
+    if (manifestPath.startsWith("scripts/")) {
+        const scripts = buildInitScriptFiles(input.governanceRoot);
+        return { content: scripts[manifestPath] };
+    }
+    if (manifestPath.startsWith(".harness/prompts/")) {
+        const name = path.basename(manifestPath);
+        return { content: COMPAT_PROMPTS[name] };
+    }
+    // `.agents/skills/...` is a target-only mirror of the bundled `skills/...`
+    // directory; the package ships `skills/`, never `.agents/skills/`.
+    if (manifestPath.startsWith(".agents/skills/")) {
+        const sourceManifestPath = manifestPath.slice(".agents/".length);
+        const mirrorSourcePath = path.join(input.assetRoot, sourceManifestPath);
+        if (await exists(mirrorSourcePath)) {
+            return {
+                content: await readFile(mirrorSourcePath, "utf-8"),
+                sourcePath: mirrorSourcePath,
+            };
+        }
+        return {};
+    }
+    if (manifestPath.startsWith("docs/")) {
+        const doc = manifestPath.slice("docs/".length);
+        const generated = buildGeneratedCoreDoc({
+            doc,
+            projectName: input.projectName,
+            governanceRoot: input.governanceRoot,
+        });
+        if (generated !== undefined)
+            return { content: generated };
+        const mappedSourcePath = path.join(input.assetRoot, "docs", coreDocSourceForTarget(doc));
+        if (await exists(mappedSourcePath)) {
+            return {
+                content: await readFile(mappedSourcePath, "utf-8"),
+                sourcePath: mappedSourcePath,
+            };
+        }
+    }
+    const sourcePath = path.join(input.assetRoot, manifestPath);
+    if (await exists(sourcePath))
+        return { content: await readFile(sourcePath, "utf-8"), sourcePath };
+    return {};
+}
+function extractManagedBlock(content) {
+    const start = content.indexOf(MANAGED_BLOCK_START);
+    const end = content.indexOf(MANAGED_BLOCK_END);
+    if (start < 0 || end <= start)
+        return undefined;
+    return content.slice(start, end + MANAGED_BLOCK_END.length);
+}
+async function readExistingSurfaceState(repoRoot) {
+    const filePath = path.join(repoRoot, INIT_SURFACE_STATE_PATH);
+    if (!(await exists(filePath)))
+        return undefined;
+    const parsed = JSON.parse(await readFile(filePath, "utf-8"));
+    if (!isRecord(parsed) || parsed.schemaVersion !== 1)
+        return undefined;
+    return parsed;
+}
+/** The IDE schema reference remains a structural update signal. */
+const HARNESS_STRUCTURAL_VALUE_KEYS = new Set(["$schema"]);
+const PI_MODEL_ROUTING_KEYS = new Set(["LOW", "MED", "HIGH", "defaultModel"]);
+function isPiModelRoutingPath(path) {
+    return path.length === 2 && path[0] === "executors" && path[1] === "pi";
+}
+/**
+ * Attribute-set iteration comparison for harness.json: object key shapes must
+ * agree at every level, except that the Pi model-routing fields are opaque
+ * project-owned configuration. Scalars and array contents may otherwise differ
+ * freely unless the key is structurally sensitive.
+ */
+function harnessJsonShapeMatches(current, desired, path = []) {
+    if (isRecord(current) || isRecord(desired)) {
+        if (!isRecord(current) || !isRecord(desired))
+            return false;
+        const filterKeys = (value) => Object.keys(value)
+            .filter((key) => !isPiModelRoutingPath(path) || !PI_MODEL_ROUTING_KEYS.has(key))
+            .sort();
+        const currentKeys = filterKeys(current);
+        const desiredKeys = filterKeys(desired);
+        if (currentKeys.length !== desiredKeys.length)
+            return false;
+        for (let index = 0; index < currentKeys.length; index += 1) {
+            const key = currentKeys[index];
+            if (key !== desiredKeys[index])
+                return false;
+            if (HARNESS_STRUCTURAL_VALUE_KEYS.has(key)) {
+                if (!isDeepStrictEqual(current[key], desired[key]))
+                    return false;
+                continue;
+            }
+            if (!harnessJsonShapeMatches(current[key], desired[key], [...path, key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return true;
+}
+/**
+ * Stable package/source anchor for generated desired content: sha256 of the
+ * desired content re-rendered through buildDesiredSurfaceContent with fixed
+ * sentinel identity values (PROJECT_NAME_TOKEN / GOVERNANCE_ROOT_TOKEN). The
+ * anchor is therefore deterministic and invariant to the real project name and
+ * governance root: a project rename or governance-root change never invalidates
+ * a previously accepted semantic merge, while package/template content changes
+ * still do. Rendering with sentinels (instead of reverse split/join replacement
+ * on already-rendered bytes) avoids false drift when a real project name is a
+ * common substring such as `init` or `docs`.
+ */
+async function stableDesiredSourceAnchor(input) {
+    const manifestPath = targetPathToManifestPath(input.entry.path, input.governanceRoot);
+    const sentinel = await buildDesiredSurfaceContent({
+        assetRoot: input.assetRoot,
+        repoRoot: input.repoRoot,
+        projectName: PROJECT_NAME_TOKEN,
+        governanceRoot: GOVERNANCE_ROOT_TOKEN,
+        entry: { ...input.entry, path: manifestPath },
+    });
+    return sentinel.content === undefined
+        ? undefined
+        : sha256Text(sentinel.content);
+}
+/**
+ * Lightweight read-only preflight for the post-upgrade init surface notifier.
+ *
+ * Returns the recorded controller version and state kind only when a valid
+ * `.harness/init-surface.json` exists. Missing or corrupt state, the source
+ * repo, and uninitialized directories all resolve to `undefined`, so the
+ * notifier can cheaply skip without running a full surface diff.
+ */
+export async function readRecordedSurfaceControllerVersion(repoRoot) {
+    let state;
+    try {
+        state = await readExistingSurfaceState(repoRoot);
+    }
+    catch {
+        return undefined;
+    }
+    if (!state || typeof state.controllerVersion !== "string")
+        return undefined;
+    return {
+        controllerVersion: state.controllerVersion,
+        stateKind: state.stateKind,
+    };
+}
+async function buildCurrentSurfaceState(input) {
+    const assetRoot = await findPackageRoot();
+    const controllerVersion = await readPackageVersion(assetRoot);
+    const manifest = await readInitSurfaceManifest(assetRoot);
+    const files = {};
+    for (const manifestEntry of manifest.entries) {
+        const targetRelativePath = normalizeRelativePath(manifestPathToTargetPath(manifestEntry.path, input.governanceRoot));
+        const entry = {
+            ...manifestEntry,
+            path: targetRelativePath,
+        };
+        const targetPath = path.join(input.repoRoot, targetRelativePath);
+        const targetStat = await stat(targetPath).catch(() => null);
+        const desired = await buildDesiredSurfaceContent({
+            assetRoot,
+            repoRoot: input.repoRoot,
+            projectName: input.projectName,
+            governanceRoot: input.governanceRoot,
+            entry: manifestEntry,
+        });
+        const sourceSha256 = desired.content === undefined ? undefined : sha256Text(desired.content);
+        const sourceAnchorSha256 = entry.mode !== "generated" || desired.content === undefined
+            ? undefined
+            : await stableDesiredSourceAnchor({
+                assetRoot,
+                repoRoot: input.repoRoot,
+                projectName: input.projectName,
+                governanceRoot: input.governanceRoot,
+                entry,
+            });
+        const base = {
+            status: targetStat ? "present" : "missing",
+            relationship: "missing-from-target",
+            sourceSha256,
+            sourceAnchorSha256,
+            sourcePath: desired.sourcePath
+                ? repoRelative(assetRoot, desired.sourcePath)
+                : undefined,
+            mode: entry.mode,
+        };
+        if (entry.mode === "state") {
+            files[targetRelativePath] = {
+                ...base,
+                status: "present",
+                relationship: "state-file",
+            };
+            continue;
+        }
+        if (!targetStat) {
+            files[targetRelativePath] = base;
+            continue;
+        }
+        if (entry.mode === "directory") {
+            files[targetRelativePath] = {
+                ...base,
+                relationship: targetStat.isDirectory()
+                    ? "directory-present"
+                    : "local-existing-unknown",
+            };
+            continue;
+        }
+        const current = await readFile(targetPath);
+        const currentSha256 = sha256Buffer(current);
+        if (entry.mode === "managed-block") {
+            const text = current.toString("utf-8");
+            const currentBlock = entry.path === ".gitignore" || targetRelativePath === ".gitignore"
+                ? extractGitignoreManagedBlock(text)
+                : extractManagedBlock(text);
+            files[targetRelativePath] = {
+                ...base,
+                currentSha256,
+                relationship: currentBlock &&
+                    sourceSha256 &&
+                    sha256Text(currentBlock) === sourceSha256
+                    ? "managed-block-current"
+                    : "managed-block-present",
+            };
+            continue;
+        }
+        let semanticallyMatchesGeneratedJson = false;
+        if (targetRelativePath === "harness.json" &&
+            desired.content !== undefined) {
+            try {
+                semanticallyMatchesGeneratedJson = harnessJsonShapeMatches(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: semanticallyMatchesGeneratedJson ||
+                (sourceSha256 !== undefined && currentSha256 === sourceSha256)
+                ? entry.mode === "generated"
+                    ? "matches-current-generated"
+                    : "matches-current-package"
+                : "local-existing-unknown",
+        };
+    }
+    return {
+        schemaVersion: 1,
+        controllerVersion,
+        stateKind: input.stateKind,
+        generatedAt: input.generatedAt ?? new Date().toISOString(),
+        manifestSha256: manifest.sha256,
+        files,
+    };
+}
+async function writeInitSurfaceState(input) {
+    const state = await buildCurrentSurfaceState(input);
+    if (input.stateKind === "recorded" && input.preserveOwnershipFrom) {
+        for (const [pathName, file] of Object.entries(state.files)) {
+            if (file.relationship !== "local-existing-unknown")
+                continue;
+            const priorFile = input.preserveOwnershipFrom.files[pathName];
+            const priorHash = priorFile?.currentSha256;
+            if (priorHash !== undefined) {
+                file.currentSha256 = priorHash;
+            }
+            else {
+                delete file.currentSha256;
+            }
+            if (priorFile?.acceptedMerge) {
+                file.acceptedMerge = { ...priorFile.acceptedMerge };
+            }
+        }
+    }
+    if (input.acceptCurrentHarnessAsMerge) {
+        const harness = state.files["harness.json"];
+        if (harness?.relationship === "local-existing-unknown" &&
+            harness.currentSha256 !== undefined &&
+            harness.sourceSha256 !== undefined) {
+            harness.acceptedMerge = {
+                currentSha256: harness.currentSha256,
+                desiredSha256: harness.sourceSha256,
+                ...(harness.sourceAnchorSha256 !== undefined
+                    ? { sourceAnchorSha256: harness.sourceAnchorSha256 }
+                    : {}),
+            };
+        }
+    }
+    const target = path.join(input.repoRoot, INIT_SURFACE_STATE_PATH);
+    await mkdir(path.dirname(target), { recursive: true });
+    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;
+    }
+    if (input.legacyPath.startsWith("docs/")) {
+        const doc = input.legacyPath.slice("docs/".length);
+        return fileSha256IfExists(path.join(input.assetRoot, "docs", coreDocSourceForTarget(doc)));
+    }
+    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);
+}
+const PI_MODEL_TIERS = ["LOW", "MED", "HIGH"];
+const LEGACY_MODEL_FIELDS = [
+    "model",
+    "models",
+    "modelProfiles",
+    "modelRouting",
+    "provider",
+    "verify",
+    "sequentialWorkflowRole",
+];
+function isQualifiedModelReference(value) {
+    if (typeof value !== "string" || value.trim() !== value)
+        return false;
+    const slash = value.indexOf("/");
+    return (slash > 0 &&
+        slash < value.length - 1 &&
+        !/\s/.test(value.slice(0, slash)) &&
+        !/\s/.test(value.slice(slash + 1)));
+}
+/**
+ * Only a single, qualified old default can be expanded automatically. All
+ * routing/profile/tier ambiguity remains in the target for a bounded merge.
+ */
+function assessHarnessModelMigration(harness) {
+    const hasLegacyFields = LEGACY_MODEL_FIELDS.some((field) => field in harness);
+    const executors = harness.executors;
+    if (executors !== undefined && !isRecord(executors)) {
+        return hasLegacyFields
+            ? { kind: "ambiguous", reason: "executors is not an object" }
+            : { kind: "none" };
+    }
+    const executorRecord = executors ?? {};
+    if ("cursor" in executorRecord) {
+        return {
+            kind: "ambiguous",
+            reason: "executors.cursor has user-owned runtime semantics",
+        };
+    }
+    if ("pi" in executorRecord && !isRecord(executorRecord.pi)) {
+        return {
+            kind: "ambiguous",
+            reason: "executors.pi is not an object",
+        };
+    }
+    const pi = isRecord(executorRecord.pi) ? executorRecord.pi : {};
+    const hasDefaultModel = "defaultModel" in pi;
+    const hasTier = PI_MODEL_TIERS.some((tier) => tier in pi);
+    if (["requiresApiKey", "provider", "model"].some((field) => field in pi) ||
+        Object.keys(pi).some((field) => !["description", "enabled", "defaultModel", ...PI_MODEL_TIERS].includes(field))) {
+        return {
+            kind: "ambiguous",
+            reason: "executors.pi contains unknown or deprecated model semantics",
+        };
+    }
+    if (hasLegacyFields) {
+        return {
+            kind: "ambiguous",
+            reason: "legacy top-level model or workflow fields cannot be proven equivalent",
+        };
+    }
+    if (!hasDefaultModel)
+        return { kind: "none" };
+    if (hasTier) {
+        return {
+            kind: "ambiguous",
+            reason: "existing LOW/MED/HIGH tier configuration cannot be replaced by defaultModel automatically",
+        };
+    }
+    if (pi.defaultModel === "default")
+        return { kind: "none" };
+    if (!isQualifiedModelReference(pi.defaultModel)) {
+        return {
+            kind: "ambiguous",
+            reason: "defaultModel is not a complete provider/model reference",
+        };
+    }
+    return { kind: "safe", model: pi.defaultModel, removeDefaultModel: true };
+}
+function needsHarnessModelMigration(harness) {
+    return assessHarnessModelMigration(harness).kind === "safe";
+}
+function migrateHarnessModelFields(harness) {
+    const assessment = assessHarnessModelMigration(harness);
+    if (assessment.kind !== "safe") {
+        throw new Error("ambiguous harness model migration must be merged manually");
+    }
+    const next = { ...harness };
+    for (const field of LEGACY_MODEL_FIELDS)
+        delete next[field];
+    const executors = isRecord(next.executors) ? { ...next.executors } : {};
+    const pi = isRecord(executors.pi) ? { ...executors.pi } : {};
+    if (assessment.model) {
+        for (const tier of PI_MODEL_TIERS)
+            pi[tier] = assessment.model;
+    }
+    if (assessment.removeDefaultModel)
+        delete pi.defaultModel;
+    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 ??
+            (recordedGovernanceRoot === "docs"
+                ? DEFAULT_GOVERNANCE_ROOT
+                : recordedGovernanceRoot) ??
+            DEFAULT_GOVERNANCE_ROOT,
+    };
+}
+function buildManagedReadmeBlock(input) {
+    return [
+        MANAGED_BLOCK_START,
+        "## loop-agent 治理",
+        "",
+        `本仓库已初始化为 \`${input.projectName}\` 的 loop-agent harness 项目。loop-agent 负责 Agent DAG 生成、校验、执行与收口，并保留运行态事实。下面的内容是 deterministic CLI 生成的保守入口；目标项目的具体语义（技术栈、模块、运行命令、验证命令）应由初始化模型根据实际文件补全。`,
+        "",
+        "### 项目入口",
+        "",
+        "- `README.md`（本文件）：人类首次进入项目和 agent 开工的首入口，应同时覆盖项目概览与开发/验证入口。",
+        "- `harness.json`：loop-agent entrypoints、验证命令与 adapter 设置。",
+        "- `AGENTS.md`：agent 在本仓库的工作协议。",
+        `- \`${input.governanceRoot}/README.md\` - 治理文档索引（含原则、工作流、验证矩阵与方法论）`,
+        "",
+        "### 开发与验证入口",
+        "",
+        "开发、测试和门禁命令（按目标项目实际技术栈补全；下面是 loop-agent 治理脚本）：",
+        "",
+        "```bash",
+        "bash scripts/check-repo.sh",
+        "bash scripts/ci-governance.sh",
+        "bash scripts/ci-tests.sh",
+        "bash scripts/ci.sh",
+        "loop-agent inspect",
+        "loop-agent doctor",
+        "loop-agent docs audit",
+        "```",
+        "",
+        "`scripts/ci-tests.sh` 必须反映目标项目真实语言和工具链。初始化生成版本会保守探测常见入口；当已知项目专属命令时，应按目标项目实际情况适配，并在 verification-matrix.md 中同步登记。",
+        "",
+        "### loop-agent 工作流入口",
+        "",
+        "默认使用 Agent DAG 作为实现工作流：",
+        "",
+        "```bash",
+        'loop-agent task advance <task-id> "任务标题" \\',
+        "  --prd <prd.md> \\",
+        '  --allowed-path "<glob>" \\',
+        '  --verify "<label>:<command>" \\',
+        "  --json",
+        "# 审查 writeSet gate digest 后：",
+        'loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json',
+        "loop-agent task status <task-id> --json",
+        "```",
+        "",
+        `详细工作流见 \`${input.governanceRoot}/feature-workflow.md\`；验证矩阵见 \`${input.governanceRoot}/verification-matrix.md\`。任务 source 仍必需（\`source/需求.md\` / \`source/执行约束.md\`），默认由 \`task advance --prd\` 从详细 PRD 确定性派生，而不是主会话手写或 LLM 写 md。高级任意 DagSpec 才用 \`dag validate|execute|report\`，不进入标准 happy path。`,
+        "",
+        "执行后使用 `loop-agent dag report --run-id <run-id> --markdown` 和 `loop-agent dag doctor --run-id <run-id> --markdown` 读取事实与诊断失败。失败 run 不做成功式 closeout；使用 `loop-agent dag closeout-draft --run-id <run-id>` 生成 failure handoff。",
+        "",
+        "### 文档导航",
+        "",
+        `- \`${input.governanceRoot}/README.md\` - 治理文档索引（含原则、工作流、验证矩阵与方法论）`,
+        `- \`${input.governanceRoot}/development-principles.md\` - 仓库开发原则`,
+        `- \`${input.governanceRoot}/architecture/runtime-boundaries.md\` - runtime 层边界与依赖方向`,
+        `- \`${input.governanceRoot}/feature-workflow.md\` - 有边界的功能工作流`,
+        `- \`${input.governanceRoot}/verification-matrix.md\` - 治理与项目专属验证命令`,
+        `- \`${input.governanceRoot}/loop-agent-harness.md\` - 目标项目如何使用 loop-agent`,
+        "- `AGENTS.md` - agent 工作协议",
+        "- `harness.json` - loop-agent 入口与验证命令配置",
+        "",
+        "Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或兼容 Bash。实际文件操作使用平台原生路径；`/` 仅用于稳定仓库引用、Markdown/JSON 证据引用和 glob 约定。",
+        MANAGED_BLOCK_END,
+    ].join("\n");
+}
+function buildTargetReadme(input) {
+    return [
+        `# ${input.projectName}`,
+        "",
+        "> 本文件是项目入口。上面一行保留项目名称；下方 loop-agent managed block 由 deterministic CLI 生成。本文件正文人类可维护，用于描述项目概览、技术栈、目录结构、运行/验证命令等。初始化模型应根据目标项目实际文件补全本节正文。",
+        "",
+        "## 项目概览",
+        "",
+        "<!-- 初始化模型补充：项目是什么、解决什么问题、当前阶段。 -->",
+        "",
+        "## 技术栈与目录结构",
+        "",
+        "<!-- 初始化模型补充：语言、框架、构建工具、关键依赖与目录约定。 -->",
+        "",
+        "## 开发与验证",
+        "",
+        "<!-- 初始化模型补充：本地开发、测试、构建、门禁命令。 -->",
+        "",
+        buildManagedReadmeBlock(input),
+        "",
+    ].join("\n");
+}
+function buildTargetDocsReadme(input) {
+    return [
+        "# 文档索引 / Documentation Index",
+        "",
+        `本目录是 \`${input.projectName}\` 的 loop-agent 治理根目录，用于沉淀目标项目的持久工程上下文：决策、契约、计划、验证、报告与交接资料，与具体语言、框架或业务领域无关。`,
+        "",
+        `This directory is the loop-agent governance root for \`${input.projectName}\`. It records durable engineering context for the target project, independent of language, framework, or business domain.`,
+        "",
+        "## 核心文档 / Core Documents",
+        "",
+        "- `development-principles.md` - 仓库开发原则 / repository development principles",
+        "- `architecture/runtime-boundaries.md` - runtime 层边界与依赖方向 / runtime layer boundaries and dependency direction",
+        "- `feature-workflow.md` - 有边界的功能工作流 / bounded feature workflow",
+        "- `verification-matrix.md` - 治理与项目专属验证命令 / governance and project-specific verification commands",
+        "- `loop-agent-harness.md` - 目标项目如何使用 loop-agent / how this target project uses loop-agent",
+        "",
+        "## 方法论 / Methodology",
+        "",
+        "- `harness-methodology-tdd.md` - 行为变更与缺陷修复的 TDD 纪律 / TDD discipline for behavior changes and bug fixes",
+        "- `harness-methodology-verification.md` - 完成声明前的验证纪律 / verification discipline before completion claims",
+        "- `harness-methodology-debugging.md` - 修复前的系统性调试工作流 / systematic debugging workflow before fixes",
+        "",
+        "## 制品目录 / Artifacts",
+        "",
+        "- `design/README.md` - 设计笔记与实现契约 / design notes and implementation contracts",
+        "- `exec-plans/active/README.md` - 活跃执行计划 / active execution plans",
+        "- `exec-plans/completed/README.md` - 已完成执行计划 / completed execution plans",
+        "- `progress/README.md` - 进度交接日志 / progress handoff logs",
+        "- `reports/README.md` - 验证与审计报告 / verification and audit reports",
+        "- `decisions/README.md` - 架构决策 / architecture decisions",
+        "- `templates/README.md` - 模板入口与类别说明 / template entrypoint and category guide",
+        "- `templates/` - 可复用的计划、报告与 DAG 模板 / reusable planning, reporting, and DAG templates",
+        "- `templates/production-readiness-checklist.md` - 低/中风险单仓库 DAG 任务的 production readiness 检查清单 / production readiness checklist for low/medium-risk single-repo DAG work",
+        "- `templates/worker-dogfood-setup.md` - 发布控制器下的真实 Worker sample setup / real Worker sample setup with a published controller",
+        "- `templates/worker-dogfood-evidence.md` - Worker sample、Observe、morning report 与 QA coverage evidence / Worker evidence template",
+        "",
+        "## 验证 / Verification",
+        "",
+        "```bash",
+        "bash scripts/check-repo.sh",
+        "bash scripts/ci-tests.sh",
+        "bash scripts/ci.sh",
+        "```",
+        "",
+        "`ci-tests.sh` 刻意保持语言中立：它会探测常见的项目验证入口，初始化模型应在已知目标项目专属命令时按实际情况适配本文件。 / `ci-tests.sh` is intentionally language-neutral. It detects common project verification entrypoints and should be adapted by the initialization model when the target project has custom commands.",
+        "",
+    ].join("\n");
+}
+function buildTargetRuntimeBoundaries(input) {
+    return [
+        "# Runtime Boundaries",
+        "",
+        `本文定义 \`${input.projectName}\` 的 runtime 层边界、允许的依赖方向和治理检查入口。初始化版本是语言中立（language-neutral）模板；初始化模型应根据目标项目真实目录和技术栈补充具体层名、模块边界和例外。`,
+        "",
+        "## 默认分层",
+        "",
+        "```text",
+        "Interface / Entry layer",
+        "  └─ CLI、HTTP API、UI 页面、job 入口或其他用户/系统入口",
+        "",
+        "Application / Use-case layer",
+        "  └─ 一次用户意图或业务动作的编排接口",
+        "",
+        "Domain / Workflow layer",
+        "  └─ 核心业务规则、状态机、工作流或领域模型",
+        "",
+        "Executors / Integrations layer",
+        "  └─ 外部工具、SDK、数据库、消息队列、浏览器、模型或 shell 适配",
+        "",
+        "Worker adapter layer (optional)",
+        "  └─ 产品线 TaskSpec / Task Pool / local Observe 适配；通过已发布 loop-agent CLI 执行，不在进程内耦合 target command 或 application 层",
+        "",
+        "Infrastructure / Store layer",
+        "  └─ 文件系统、数据库、缓存、运行事实、原子写入和生命周期副作用",
+        "",
+        "Governance layer",
+        "  └─ scripts/check-*.sh、CI、文档审计、边界检查和验证矩阵",
+        "```",
+        "",
+        "## 依赖方向",
+        "",
+        "- Entry layer 可以依赖 Application / Use-case layer。",
+        "- Application / Use-case layer 可以依赖 Domain / Workflow、Infrastructure 和 Integrations。",
+        "- Domain / Workflow layer 不应依赖 Entry layer 的格式化、argv、HTTP/UI 细节。",
+        "- Executors / Integrations 不应依赖 Entry layer 的输出格式。",
+        "- Worker adapter 应把 `.harness/task-pool/` 作为独立运行事实区；它通过 CLI/subprocess contract 调用 loop-agent，不能复制或直接耦合 target command/application 实现。",
+        "- Infrastructure / Store 应集中副作用，不把 raw path mutation 或持久化细节扩散给上层。",
+        "",
+        "## 目标项目适配",
+        "",
+        "初始化后请根据真实项目结构补充：",
+        "",
+        "- 入口目录和入口文件。",
+        "- 核心业务/domain/workflow 模块。",
+        "- infrastructure/store/integration 模块。",
+        "- 允许的例外、迁移计划和对应验证命令。",
+        "",
+        "## Governance hooks",
+        "",
+        "```bash",
+        "bash scripts/check-architecture-boundaries.sh",
+        "bash scripts/check-repo.sh",
+        "```",
+        "",
+        "`scripts/check-architecture-boundaries.sh` 是保守模板：只有当目标项目存在可识别目录时才启用对应 import 检查。不要为了通过脚本删除真实边界问题；应更新本文或修正依赖方向。",
+        "",
+    ].join("\n");
+}
+function buildTargetDevelopmentPrinciples(input) {
+    return [
+        "# Development Principles",
+        "",
+        `\`${input.projectName}\` uses loop-agent governed development. These principles apply regardless of language, framework, or deployment model.`,
+        "",
+        "## Operating Stance",
+        "",
+        "- The repository is the record system. Decisions, contracts, plans, tests, reports, and handoffs belong in tracked files.",
+        "- Work advances in small, reversible, verifiable increments.",
+        "- Baseline verification comes before new work when the current state is uncertain.",
+        "- Completion is defined by fresh evidence, not by intent or confidence.",
+        "- Preserve unrelated user changes.",
+        "",
+        "## Principles",
+        "",
+        "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 \`${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.",
+        "8. Do not keep hidden process state only in chat.",
+        "9. Do not add placeholders as completed implementation.",
+        "10. Prefer existing local project patterns before adding new abstractions.",
+        "",
+        "## Task Slicing: Vertical Tracer Bullets First",
+        "",
+        "Principle 1 covers **granularity** (one bounded block). This section covers **shape**: each slice should cross the real integration layers the work needs and leave an independently verifiable narrow loop.",
+        "",
+        "- Every slice needs its own acceptance criteria, verification commands, and failure conditions.",
+        '- Prefer vertical tracer bullets over horizontal layering. Paths like "schema → API → UI → tests" are *possible* examples only; do not assume every project has those layers.',
+        "- Horizontal anti-patterns: finish all of one layer before the next; or write every test first, then implement everything.",
+        "- For behavior changes, use one failing test → minimal implementation → green → next behavior. Do not batch all RED then all GREEN.",
+        "- Split large features into multiple independently runnable tasks/DAGs instead of one oversized writer across every layer.",
+        "",
+        "### Autonomy vs Governance (independent layers)",
+        "",
+        "| Dimension | Meaning | How to decide |",
+        "|---|---|---|",
+        "| Autonomy | Whether the slice needs synchronous human judgment, external access, or non-automatable decisions | Declare AFK/HITL in Contract, open questions, or human gate signals |",
+        "| Governance | How strong review, repair, write-set, and verification gates must be | Default `--profile auto`; route to `minimal` / `standard` / `reviewed` / `supervised` by risk and delivery signals |",
+        "",
+        "- AFK does not mean `minimal` is required; ordinary automatable work may land on `standard` or `reviewed`.",
+        "- HITL does not mean choosing `supervised` alone yields a correct human decision; require a concrete pause reason / decision gate.",
+        "- Use `minimal` only for a single narrow writer, deterministic post shell verification, and no escalation signals.",
+        "- High-risk, public-contract, init/runtime/CI/governance surface, or real human judgment gates should escalate via `auto`, or explicitly choose `reviewed` / `supervised`.",
+        "",
+        "## Target Project Adaptation",
+        "",
+        "The initialized scripts provide language-neutral governance. The initialization model should adapt project-specific verification commands after reading the target project's actual files and toolchain.",
+        "",
+        "Repo-local skills live under `.agents/skills/` (mirrored from the package `skills/` fallback).",
+        "",
+    ].join("\n");
+}
+function buildTargetFeatureWorkflow(input) {
+    return [
+        "# Feature Workflow",
+        "",
+        "This document describes how work should move through this target repository using loop-agent.",
+        "",
+        "## Session Protocol",
+        "",
+        "1. Orient: read `README.md`, `harness.json`, `AGENTS.md`, and this docs index.",
+        "2. Select: choose one bounded work block.",
+        "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 ${input.governanceRoot}/progress, ${input.governanceRoot}/reports, an exec plan, or an ADR when useful.`,
+        "",
+        "## Agent DAG Path",
+        "",
+        "```bash",
+        'loop-agent task advance <task-id> "Task title" \\',
+        "  --prd <prd.md> \\",
+        '  --allowed-path "<glob>" \\',
+        '  --verify "<label>:<command>" \\',
+        "  --json",
+        "# Review writeSet gate digest, then:",
+        'loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json',
+        "loop-agent task status <task-id> --json",
+        "```",
+        "",
+        DAG_HARD_GATE_TRIGGER,
+        "",
+        "Before executing a DAG, review profile routing, governance profile, writer writeSet, allowed paths, forbidden paths, shell verification, and decision gate mode.",
+        "Generated DAGs bind authoritative task-source paths, SHA-256 hashes, and explicit REQ/BR/AC identifiers. Frontend plans with explicit identifiers pass a deterministic coverage gate before final design review and implementation.",
+        "After an interrupted run, repair the task source and regenerate the complete DAG. Do not construct an impl-only recovery DAG from an upstream summary; strict governance rejects a v3 orphan writer without sourceBinding or a read-only planner ancestor.",
+        "",
+        "## Specialized Task Kinds",
+        "",
+        "- standard tasks first use the structured task type in `source/需求.md`, then combine `allowedPaths` with strong React/Next/Vue project evidence for deterministic routing.",
+        "- A frontend project defaults eligible implementation work to the frontend DAG without requirement keyword matching. Explicit backend, mixed, frontend-negated, and documentation/test-only scopes keep the template selected by the normal governance profile.",
+        "- `frontend-mock-assess-pi` reads Mock/API/schema evidence and selects `native|browser-intercept|request-adapter|not-needed|blocked` before frontend planning; its deterministic gate rejects blocked or malformed output, while the existing frontend implementer remains the only writer.",
+        "- Mock-backed verification never proves real API integration. When the backend was not exercised, closeout must retain the gap and name `<task-id>-real-api-integration-verify`; that follow-up is explicitly created/run after backend readiness, never automatic.",
+        "- Automatic frontend classification selects the frontend implementation workflow and persists taskKind; explicit profiles, workflowPolicy, and supervised quality gates record governance strength without switching the business workflow back to a generic DAG.",
+        "- A backend implementation does not select the backend test DAG. `backend-test` remains an explicit test-engineering workflow.",
+        "- Explicit specialized `taskKind` values remain compatible and take precedence over task-source classification.",
+        "",
+        "Set an explicit specialized `taskKind` in `.harness/tasks/<task-id>/task.json` only when the dedicated workflow itself is part of the task contract:",
+        "",
+        '- `taskKind: "frontend-implementation"` explicitly selects the frontend DAG for compatibility or intentional override. Optional `frontendMock` config sets `policy: auto|required|disabled`, an existing `serviceRoot`, and generation-time-frozen `verifyCommands`; an unsafe or incomplete explicit required contract produces an assessment-only DAG with no writer, while a complete required contract adds Mock-specific verification only when trusted commands exist. Auto API tasks without a native service may use an existing browser interception harness or reversible request adapter, then continue through static and behavior verification.',
+        '- `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.',
+        '- `taskKind: "knowledge-sync"` selects the Feature-scoped test-knowledge write-back DAG (collect → draft → validate → apply → pointer). Bind `featureId` in `task.json` (or hardConstraints / requirement text). It writes only under `features/<featureId>/…` after final verification evidence exists.',
+        '- `taskKind: "knowledge-graph-bootstrap"` selects the business knowledge-graph bootstrap DAG (preflight → inventory → propose → validate → review → gate → promote → materialize). AI writes only `knowledge/bootstrap/staging/**`; promote is merge-new-only.',
+        '- `taskKind: "frontend-test"` selects the FE-test RAG DAG. It writes a traceable frontend RAG package and Markdown case manifest, then executes manifest cases serially with `playwright-cli` in isolated test environments and retains per-case evidence. It never generates pytest or Playwright source code. `frontendTest.maxCasesPerBatch` defaults to 50 (maximum 100); optional `maxTokensPerCase` and `maxTotalTokens` stop only later cases after a completed case\'s token usage is recorded, marking them `blocked: token-budget-exhausted`. Need-login cases open LOGIN_URL then goto TARGET_URL; otherwise open or goto TARGET_URL. The generic playwright-cli skill is unchanged.',
+        "- 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`.",
+        "",
+        "Use the package-backed public knowledge CLI for graph operations. Do not require target projects to run package-only kb runtime scripts:",
+        "",
+        "```bash",
+        "loop-agent knowledge graph-init --product-name <name>",
+        "# edit knowledge/bootstrap/scope.yaml, then:",
+        "loop-agent task advance <task-id> --task-kind knowledge-graph-bootstrap --json",
+        "loop-agent knowledge query --mode by_feature --feature F-2026-004 --json",
+        "loop-agent knowledge query --mode by_id --id SVC-order --json",
+        'loop-agent knowledge query --mode search --text "keyword" --json',
+        "loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service <service>",
+        "# review the prepared scope/staging; for a manual reviewed promotion:",
+        "loop-agent knowledge graph-promote",
+        "loop-agent knowledge graph-materialize",
+        "```",
+        "",
+        'Daily Feature test-knowledge write-back still uses `taskKind: "knowledge-sync"` with a bound `featureId`, separate from graph bootstrap/incremental entry points.',
+        "",
+        "## Verification",
+        "",
+        `Use \`${input.governanceRoot}/verification-matrix.md\` to choose the narrowest command that proves the claim.`,
+        "",
+    ].join("\n");
+}
+function buildTargetVerificationMatrix() {
+    return [
+        "# Verification Matrix",
+        "",
+        "Use the narrowest command that proves the claim. This matrix is language-neutral: governance checks are generated by loop-agent, while project-specific checks should reflect the target project's actual toolchain.",
+        "",
+        "| Claim | Minimum verification | Stronger verification |",
+        "|---|---|---|",
+        "| loop-agent governance is valid | `bash scripts/check-repo.sh` | `bash scripts/ci-governance.sh` |",
+        "| target project tests are valid | `bash scripts/ci-tests.sh` | project-specific full test/build command |",
+        "| full local delivery is valid | `bash scripts/ci.sh` | add deployment/package-specific checks when relevant |",
+        "| docs/governance changed | `bash scripts/check-repo.sh` | `loop-agent docs audit` plus `bash scripts/ci-governance.sh` |",
+        "| model writer changed files | `git status --short` + relevant verification | `bash scripts/ci.sh` |",
+        "",
+        "## Generated Commands",
+        "",
+        "```bash",
+        "bash scripts/check-engineering-structure.sh",
+        "bash scripts/check-doc-index.sh",
+        "bash scripts/check-doc-links.sh",
+        "bash scripts/check-active-plan-status.sh",
+        "bash scripts/check-exec-plan-index-sync.sh",
+        "bash scripts/check-harness-runtime-clean.sh",
+        "bash scripts/check-architecture-boundaries.sh",
+        "bash scripts/check-skill-entry.sh",
+        "bash scripts/check-repo.sh",
+        "bash scripts/ci-governance.sh",
+        "bash scripts/ci-tests.sh",
+        "bash scripts/ci.sh",
+        "```",
+        "",
+        "## Project-Specific Verification",
+        "",
+        "`scripts/ci-tests.sh` detects common entrypoints such as package.json, Makefile, go.mod, Cargo.toml, Python test metadata, Maven, Gradle, and .NET projects. If no safe command is detected, it exits successfully with a clear message so the initialization model can adapt this file to the target project.",
+        "",
+        "After initialization, update this matrix with the target project's actual quick, standard, and full verification commands.",
+        "",
+    ].join("\n");
+}
+function buildTargetLoopAgentHarness(input) {
+    return [
+        "# loop-agent Harness",
+        "",
+        `This target project, \`${input.projectName}\`, is initialized to use loop-agent for governed task execution.`,
+        "",
+        "## Runtime Layout",
+        "",
+        "- `.harness/tasks/` stores task state and source materials.",
+        "- `.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.",
+        `- \`${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",
+        "",
+        "Use `loop-agent task advance` / `loop-agent task status` for non-trivial implementation work; advanced arbitrary DagSpec uses `loop-agent dag execute`.",
+        "",
+        "## Pi Model Matrix",
+        "",
+        "New DAG work reads only `harness.json.executors.pi.LOW`, `MED`, and `HIGH`. Each tier must be a model string or `{ model, thinking? }`; use explicit `provider/model` references when choosing a provider. Fresh init does not write `defaultModel`, `models`, `modelProfiles`, or `modelRouting`. `defaultModel` remains a runtime fallback only for compatible older projects.",
+        "",
+        "```json",
+        '{ "executors": { "pi": { "LOW": "provider/low", "MED": "provider/medium", "HIGH": "provider/high" } } }',
+        "```",
+        "",
+        "## Adaptive Liveness",
+        "",
+        "- Healthy Pi nodes are no longer stopped by a fixed 30-minute deadline. The default 4h absolute max is a final safety bound and cannot be extended by synthetic heartbeats.",
+        "- Runner heartbeat proves only the runner lease. Provider, tool, or output activity records meaningful progress; prolonged inactivity can surface as `quiet`, `suspected-stall`, `probing`, or `needs-attention` in `dag status`, `dag doctor`, and Observe.",
+        "- A silent transport is aborted in a controlled way. `termination-unconfirmed` means the old attempt may still exist, so loop-agent fails closed and does not start an automatic retry; inspect the run before any operator recovery.",
+        "- `agent-worker` does not set an outer `task advance` / `dag execute` wall-clock by default. An explicit `worker.timeout_ms` remains a hard timeout.",
+        "",
+        "## Operator Recovery",
+        "",
+        "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 \`${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 \`${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",
+        "",
+        "`scripts/check-repo.sh` verifies loop-agent governance. `scripts/ci-tests.sh` handles target project verification through conservative language/toolchain detection and should be adapted after reading the project.",
+        "Copy or project only stack-agnostic governance scripts. For project-specific verification, packaging, release, or maintenance commands, generate the target-project version from templates plus the target repository's actual files instead of copying loop-agent's own TypeScript-specific scripts.",
+        "",
+    ].join("\n");
+}
+function buildGeneratedCoreDoc(input) {
+    switch (input.doc) {
+        case "README.md":
+            return buildTargetDocsReadme({ projectName: input.projectName });
+        case "architecture/runtime-boundaries.md":
+            return buildTargetRuntimeBoundaries({ projectName: input.projectName });
+        case "development-principles.md":
+            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,
+                governanceRoot: input.governanceRoot,
+            });
+        default:
+            return undefined;
+    }
+}
+function buildGovernanceDirectoryReadme(input) {
+    const title = input.dir
+        .split("/")
+        .map((part) => part.replace(/-/g, " "))
+        .join(" / ");
+    if (input.dir === "decisions" || input.dir.endsWith("/decisions")) {
+        return [
+            `# ${title}`,
+            "",
+            `This directory stores ${input.projectName} architecture decision records (ADRs).`,
+            "",
+            "## When to write an ADR",
+            "",
+            "Write an ADR only when **all three** are true:",
+            "",
+            "1. **Hard to reverse** — changing the decision later has meaningful cost.",
+            "2. **Surprising without context** — a future reader will ask why this path was chosen.",
+            "3. **Real trade-off** — genuine alternatives existed and one was chosen for specific reasons.",
+            "",
+            "If any condition is missing, skip the ADR. Temporary scheduling, obvious implementation choices, and facts with no alternatives do not belong here.",
+            "",
+            "Use the ADR template under this governance root's `templates/adr.md` (or the package template when projecting). Update this README index when adding a new ADR.",
+            "",
+            "初始化只创建目录契约，不复制 loop-agent 源仓库的历史决策正文。目标项目中的具体 ADR 应由后续任务按真实取舍生成。",
+            "",
+        ].join("\n");
+    }
+    return [
+        `# ${title}`,
+        "",
+        `This directory stores ${input.projectName} governance artifacts generated during real work.`,
+        "",
+        "初始化只创建目录契约，不复制 loop-agent 源仓库的历史任务正文或历史索引。目标项目中的具体 plan、progress、report、decision 应由后续任务按真实执行事实生成。",
+        "",
+    ].join("\n");
+}
+export function buildInitInstructions(input) {
+    const projectName = input.projectName ?? path.basename(path.resolve(input.repoRoot));
+    const governanceRoot = input.governanceRoot ?? DEFAULT_GOVERNANCE_ROOT;
+    return [
+        "# loop-agent Initialization Instructions",
+        "",
+        `Initialize the target repository as a loop-agent harness project: \`${input.repoRoot}\`.`,
+        "",
+        "## Confirm With User",
+        "",
+        `- Project name: default \`${projectName}\`.`,
+        `- Governance root: default \`${governanceRoot}\`.`,
+        "- Confirm the Pi LOW/MED/HIGH matrix. Explicit input must be `--model provider/model` or a paired `--provider provider --model model`; do not guess a provider for a bare model.",
+        "- Default: merge existing AGENTS.md, harness.json, and loop-agent governance docs instead of overwriting user content.",
+        "",
+        "## Initialization Upgrade Routing",
+        "",
+        "When the user says `loop-agent初始化更新`, `loop-agent 初始化更新`, `更新 loop-agent 初始化内容`, or an equivalent write request, run `loop-agent init upgrade --repo-root . --json` as the single controller-owned entry. Complete returned single-file allowedPaths merge tasks and call `--continue` until a stable terminal result; do not stop at check-update, needs-safe-update, needs-model-merge, or verification-pending.",
+        "Explicit `检查初始化更新`, `初始化更新校验`, or `只检查，不要修改` stays strictly read-only: run only `loop-agent init check-update --repo-root . --markdown` and do not create an upgrade run.",
+        "Upgrade manages project `.opencode/plugins/`, `.pi/extensions/`, and `.pi/settings.json` by nested merge. Pi must trust the project before loading these settings; do not read or write `~/.pi/agent/settings.json` by default.",
+        "The upgrade also writes a read-only gitignore migration assessment (`.harness/init-upgrades/<run-id>/gitignore-migration.json`): tracked `.harness/**` and `.agents/**` get index-only `git rm -r --cached --ignore-unmatch` guidance (working-tree files are kept). Pause for human review when `.agents` content is tracked or when staged changes / git query failures block safe guidance; never run git rm yourself.",
+        "",
+        "## Apply Defaults",
+        "",
+        '- Use the current loop-agent harness.json as the default template, but write target project name plus `adapter: "loop-agent"` and a Pi-only `executors.pi.LOW/MED/HIGH` matrix. Do not write `defaultModel` when all three tiers exist, and never project `model`, `models`, `modelProfiles`, `modelRouting`, `verify`, or `sequentialWorkflowRole`.',
+        `- ${DAG_HARD_GATE_TRIGGER}`,
+        "- Generate the target project's loop-agent script matrix from templates: structure check, docs index/link checks, active plan status, exec-plan index sync, harness runtime cleanliness, architecture boundaries, skill entry integrity, governance CI, project-test CI, and full CI.",
+        "- Copy or project only stack-agnostic governance scripts. For project-specific verification, packaging, release, or maintenance commands, generate the target-project version from templates plus the target repository's actual files instead of copying loop-agent's own TypeScript-specific scripts.",
+        "- Do not assume the target project is TypeScript, Node.js, frontend, backend, or any other specific stack.",
+        "- `scripts/ci-tests.sh` must be language-neutral: detect common project verification entrypoints conservatively, run only commands that exist, and clearly report when project-specific verification needs model/user adaptation.",
+        "- Default verification entries: quick `bash scripts/check-repo.sh`, standard `bash scripts/ci-governance.sh`, full `bash scripts/ci.sh`.",
+        `- 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 \`${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 exactly the four local, rebuildable runtime directories (`.harness/`, `.agents/`, `.task-pool/`, `.worktrees/`) while keeping `scripts/` and `ai_workspace/loop-agent/` on the shared commit surface; keep all user rules outside the block untouched.",
+        "- 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.",
+        "- The generated AGENTS.md must include documentation convergence and structured DAG write-boundary rules so target projects keep the same working discipline as this repository.",
+        "- The generated target docs must surface the production readiness checklist and the operator recovery path: `dag report`, `dag doctor --run-id --markdown`, and failed-run `dag closeout-draft` failure handoff.",
+        "- Create `.harness/` runtime directories but do not create historical run facts.",
+        "",
+        "## Automatic Workflow For Model-Executed Init",
+        "",
+        "When a model/agent is asked to initialize a target project, treat initialization as one automated workflow. Do not run deterministic init and then wait for another user turn to fill project-specific content.",
+        "",
+        "1. Resolve only the inputs that are genuinely unsafe to assume: provider/model, non-default governance root, overwrite policy, credentials, cost, or deployment side effects.",
+        "2. Run deterministic init with merge defaults.",
+        "3. Continue immediately into project inspection and adaptation.",
+        "4. Finish by running the init health checks and quick verification.",
+        "",
+        "If provider/model is not specified and the existing tier matrix is usable, proceed with it and record the assumption in the handoff. Ask the user only when the choice affects credentials, cost, availability, or an explicitly requested model backend. An ambiguous old model configuration must stay in a bounded harness.json model merge/human decision; never silently reinterpret it.",
+        "",
+        "## Required Model Adaptation",
+        "",
+        "Do not stop after the deterministic `loop-agent init` command. When these instructions are executed by an agent/model, the initialization is not complete until the target project has been inspected and the generated scaffolding has been adapted.",
+        "",
+        "Required post-init steps:",
+        "",
+        "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 \`${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.",
+        "",
+        "Completion rule: if target files provide enough evidence, the final README should not leave generic `初始化模型补充` comments in the sections that can be filled. If a section truly cannot be inferred, write a short explicit note such as `尚未从仓库文件中识别到 ...` instead of asking the user to fill it later.",
+        "",
+        "## Suggested Command",
+        "",
+        "```bash",
+        `loop-agent init --repo-root ${input.repoRoot} --profile full --merge`,
+        "loop-agent init doctor --repo-root <target>",
+        "loop-agent inspect --repo-root <target>",
+        "loop-agent docs audit --repo-root <target>",
+        "```",
+    ].join("\n");
+}
+export async function initializeLoopAgentProject(options) {
+    const repoRoot = path.resolve(options.repoRoot);
+    const projectName = options.projectName ?? path.basename(repoRoot);
+    const governanceRoot = options.governanceRoot ?? DEFAULT_GOVERNANCE_ROOT;
+    const profile = options.profile ?? "full";
+    const merge = options.merge ?? true;
+    const model = normalizeInitModelReference(options);
+    const written = [];
+    const skipped = [];
+    const assetRoot = await findPackageRoot();
+    const template = await readJsonIfExists(path.join(assetRoot, "harness.json"));
+    let existingHarness = await readJsonIfExists(path.join(repoRoot, "harness.json"));
+    if (Object.keys(existingHarness).length > 0) {
+        const migration = assessHarnessModelMigration(existingHarness);
+        if (migration.kind === "ambiguous") {
+            throw new Error(`init refuses to overwrite ambiguous legacy model configuration: ${migration.reason}; run init check-update and complete the harness.json model merge`);
+        }
+        if (migration.kind === "safe") {
+            existingHarness = migrateHarnessModelFields(existingHarness);
+        }
+    }
+    await mkdir(repoRoot, { recursive: true });
+    const readmePath = path.join(repoRoot, "README.md");
+    const existingReadme = (await exists(readmePath))
+        ? await readFile(readmePath, "utf-8")
+        : undefined;
+    const readmeContent = existingReadme
+        ? mergeManagedBlock(existingReadme, buildManagedReadmeBlock({ projectName, governanceRoot }))
+        : buildTargetReadme({ projectName, governanceRoot });
+    await writeText({
+        repoRoot,
+        relativePath: "README.md",
+        content: readmeContent,
+        merge: true,
+        written,
+        skipped,
+    });
+    const harness = buildHarness({
+        existing: existingHarness,
+        template,
+        projectName,
+        governanceRoot,
+        model,
+    });
+    await writeText({
+        repoRoot,
+        relativePath: "harness.json",
+        content: `${JSON.stringify(harness, null, 2)}\n`,
+        merge: true,
+        written,
+        skipped,
+    });
+    const agentsPath = path.join(repoRoot, "AGENTS.md");
+    const existingAgents = (await exists(agentsPath))
+        ? await readFile(agentsPath, "utf-8")
+        : `# AGENTS.md\n`;
+    await writeText({
+        repoRoot,
+        relativePath: "AGENTS.md",
+        content: mergeManagedBlock(existingAgents, await buildManagedAgentsBlock({
+            assetRoot,
+            projectName,
+            governanceRoot,
+        })),
+        merge: true,
+        written,
+        skipped,
+    });
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const existingGitignore = (await exists(gitignorePath))
+        ? await readFile(gitignorePath, "utf-8")
+        : "";
+    await writeText({
+        repoRoot,
+        relativePath: ".gitignore",
+        content: mergeGitignoreManagedBlock(existingGitignore, buildManagedGitignoreBlock()),
+        merge: true,
+        written,
+        skipped,
+    });
+    for (const doc of CORE_DOC_FILES) {
+        const generated = buildGeneratedCoreDoc({
+            doc: doc.target,
+            projectName,
+            governanceRoot,
+        });
+        if (generated) {
+            await writeTextIfMissing({
+                repoRoot,
+                relativePath: path.join(governanceRoot, doc.target),
+                content: generated,
+                merge,
+                written,
+                skipped,
+            });
+            continue;
+        }
+        await copyFileIfMissing({
+            assetRoot,
+            repoRoot,
+            sourceRelativePath: path.join("docs", doc.source),
+            targetRelativePath: path.join(governanceRoot, doc.target),
+            merge,
+            written,
+            skipped,
+        });
+    }
+    for (const dir of GOVERNANCE_README_DIRS) {
+        await writeTextIfMissing({
+            repoRoot,
+            relativePath: path.join(governanceRoot, dir, "README.md"),
+            content: buildGovernanceDirectoryReadme({ dir, projectName }),
+            merge,
+            written,
+            skipped,
+        });
+    }
+    await copyDirMerge({
+        assetRoot,
+        repoRoot,
+        sourceRelativePath: "docs/templates",
+        targetRelativePath: path.join(governanceRoot, "templates"),
+        written,
+    });
+    if (profile === "full") {
+        // Project repo-local skills live only under `.agents/skills/`.
+        // The package still ships `skills/` as the built-in fallback source.
+        await copyDirMerge({
+            assetRoot,
+            repoRoot,
+            sourceRelativePath: "skills",
+            targetRelativePath: ".agents/skills",
+            written,
+        });
+    }
+    else {
+        skipped.push(".agents/skills/");
+    }
+    skipped.push("examples/");
+    for (const [relativePath, content] of Object.entries(buildInitScriptFiles(governanceRoot))) {
+        await writeText({
+            repoRoot,
+            relativePath,
+            content,
+            merge: true,
+            written,
+            skipped,
+        });
+    }
+    await ensureHarnessDirs(repoRoot, written);
+    await writeCompatPrompts({ repoRoot, merge, written, skipped });
+    const clientRecoveryMode = options.clientRecovery ?? "auto";
+    const clientRecovery = clientRecoveryMode === "off"
+        ? undefined
+        : await runClientRecovery({
+            repoRoot,
+            mode: clientRecoveryMode,
+        });
+    const clientRecoveryPaths = [
+        OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH,
+        OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH,
+        PI_CONTEXT_OVERFLOW_EXTENSION_PATH,
+        PI_PROJECT_SETTINGS_PATH,
+    ];
+    if (clientRecoveryMode === "off") {
+        for (const recoveryPath of clientRecoveryPaths)
+            skipped.push(recoveryPath);
+    }
+    else if (clientRecovery) {
+        const installResults = [
+            clientRecovery.plugin,
+            clientRecovery.overflowPlugin,
+            clientRecovery.piExtension,
+            { written: clientRecovery.pi?.wrote === true },
+        ];
+        for (const [index, recoveryPath] of clientRecoveryPaths.entries()) {
+            if (installResults[index]?.written)
+                written.push(recoveryPath);
+        }
+    }
+    await writeInitSurfaceState({
+        repoRoot,
+        projectName,
+        governanceRoot,
+        stateKind: "recorded",
+        acceptCurrentHarnessAsMerge: model !== undefined,
+    });
+    written.push(INIT_SURFACE_STATE_PATH);
+    return {
+        repoRoot,
+        projectName,
+        governanceRoot,
+        profile,
+        written,
+        skipped,
+        clientRecovery,
+    };
+}
+function actionForMissing(pathName, state) {
+    if (state.mode === "state")
+        return undefined;
+    if (state.mode === "directory") {
+        return {
+            type: "create-directory",
+            path: pathName,
+            reason: "required init directory is missing",
+        };
+    }
+    if (state.mode === "copied") {
+        return {
+            type: "copy-missing",
+            path: pathName,
+            reason: "required bundled init file is missing",
+        };
+    }
+    if (state.mode === "generated") {
+        return {
+            type: "write-generated-missing",
+            path: pathName,
+            reason: "required generated init file is missing",
+        };
+    }
+    return {
+        type: "refresh-managed-block",
+        path: pathName,
+        reason: "managed block file is missing or stale",
+    };
+}
+function modelMergeTaskFor(pathName, state, allPaths, recordedState) {
+    return {
+        taskId: `init-merge-${sha256Text(pathName).slice(0, 12)}`,
+        path: pathName,
+        reason: "target file exists but does not match the current loop-agent initialization surface",
+        sourcePath: state.sourcePath,
+        allowedPaths: [pathName],
+        forbiddenPaths: [
+            ...allPaths.filter((candidate) => candidate !== pathName),
+            ".harness/dag-runs/**",
+            ".harness/runs/**",
+            ".git/**",
+        ],
+        mergeRules: [
+            "Preserve target-project user content and project-specific commands.",
+            "Adopt the current loop-agent initialization structure where it does not conflict with local intent.",
+            "Do not delete user-authored sections merely because they differ from the package template.",
+            "Keep writes inside allowedPaths only.",
+        ],
+        verification: [
+            "loop-agent init check-update --repo-root . --json",
+            "loop-agent init doctor --repo-root .",
+            "loop-agent inspect --repo-root .",
+            "loop-agent docs audit --repo-root .",
+            "bash scripts/check-repo.sh",
+        ],
+        evidence: {
+            baseSha256: recordedState?.files[pathName]?.currentSha256,
+            currentSha256: state.currentSha256,
+            desiredSha256: state.sourceSha256,
+            sourceAnchorSha256: state.sourceAnchorSha256,
+        },
+    };
+}
+function recommendedNextFor(report) {
+    const next = [];
+    if (report.surfaceState === "missing") {
+        next.push("loop-agent init update --repo-root <target> --bootstrap-surface");
+    }
+    if (report.deterministicActions.some((action) => action.type !== "bootstrap-surface")) {
+        next.push("loop-agent init update --repo-root <target> --apply-safe");
+    }
+    if (report.modelMergeTasks.length > 0) {
+        next.push("loop-agent init check-update --repo-root <target> --markdown");
+    }
+    if (report.humanDecisions.length > 0) {
+        next.push("Review humanDecisions before applying semantic or policy-sensitive changes.");
+    }
+    if (next.length === 0)
+        next.push("No init update actions are needed.");
+    return next;
+}
+const CLIENT_RECOVERY_SURFACE_PATHS = new Set([
+    OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH,
+    OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH,
+    PI_CONTEXT_OVERFLOW_EXTENSION_PATH,
+    PI_PROJECT_SETTINGS_PATH,
+]);
+function isClientRecoverySurfacePath(pathName) {
+    return CLIENT_RECOVERY_SURFACE_PATHS.has(pathName);
+}
+export async function checkInitUpdate(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const { projectName, governanceRoot } = await resolveInitProjectContext({
+        repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+    });
+    const clientRecoveryMode = input.clientRecovery ?? "auto";
+    const skipClientRecoverySurfaces = clientRecoveryMode === "off";
+    const recordedState = await readExistingSurfaceState(repoRoot);
+    const assetRoot = await findPackageRoot();
+    const surfaceState = recordedState?.stateKind ?? "missing";
+    const currentState = await buildCurrentSurfaceState({
+        repoRoot,
+        projectName,
+        governanceRoot,
+        stateKind: recordedState?.stateKind ?? "inferred-baseline",
+    });
+    const allPaths = Object.keys(currentState.files).sort();
+    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",
+            path: INIT_SURFACE_STATE_PATH,
+            reason: "target project has no recorded init surface baseline",
+        });
+    }
+    for (const [pathName, state] of Object.entries(currentState.files)) {
+        // Mirror fresh init: client-recovery=off never reinstalls recovery surfaces.
+        if (skipClientRecoverySurfaces && isClientRecoverySurfacePath(pathName)) {
+            continue;
+        }
+        // `.pi/settings.json` is a structured project configuration: fill only
+        // absent nested recovery fields and preserve every explicit project value.
+        if (pathName === PI_PROJECT_SETTINGS_PATH &&
+            state.relationship === "local-existing-unknown") {
+            const projectPi = await inspectProjectPiSettings({ repoRoot });
+            if (projectPi.action === "write") {
+                deterministicActions.push({
+                    type: "merge-pi-project-settings",
+                    path: pathName,
+                    reason: "fill missing project Pi retry/compaction fields without overwriting explicit values",
+                });
+                continue;
+            }
+            if (projectPi.reason === "matches" || projectPi.reason === "enabled-false") {
+                continue;
+            }
+        }
+        if (state.relationship === "missing-from-target") {
+            if (retiredTargetPaths.has(pathName))
+                continue;
+            const action = actionForMissing(pathName, state);
+            if (action)
+                deterministicActions.push(action);
+            continue;
+        }
+        if (state.relationship === "managed-block-present") {
+            deterministicActions.push({
+                type: "refresh-managed-block",
+                path: pathName,
+                reason: "managed block is missing or differs from the current package block",
+            });
+            continue;
+        }
+        if (state.relationship === "local-existing-unknown") {
+            const acceptedMerge = recordedState?.files[pathName]?.acceptedMerge;
+            if (acceptedMerge) {
+                // Generated acceptance is bound to the stable source anchor so that
+                // project-derived desired drift (projectName/governanceRoot changes)
+                // cannot invalidate an already accepted merge. Copied files remain
+                // byte-strict; desiredSha256 stays the audit receipt in both cases.
+                const anchorAccepted = state.mode === "generated" &&
+                    state.sourceAnchorSha256 !== undefined &&
+                    acceptedMerge.sourceAnchorSha256 === state.sourceAnchorSha256;
+                if (acceptedMerge.currentSha256 === state.currentSha256 &&
+                    (anchorAccepted ||
+                        acceptedMerge.desiredSha256 === state.sourceSha256)) {
+                    continue;
+                }
+                // A previously accepted semantic merge is user-preserving ownership.
+                // A later desired/current change must be merged again, never refreshed
+                // as an unchanged package-owned file.
+                modelMergeTasks.push(modelMergeTaskFor(pathName, state, allPaths, recordedState));
+                continue;
+            }
+            if (state.mode === "directory") {
+                humanDecisions.push({
+                    path: pathName,
+                    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, recordedState));
+            }
+        }
+    }
+    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");
+    if (await exists(harnessPath)) {
+        try {
+            const harness = JSON.parse(await readFile(harnessPath, "utf-8"));
+            if (recordedState &&
+                isRecord(harness) &&
+                harness.$schema !== expectedHarnessSchemaRef(governanceRoot)) {
+                deterministicActions.push({
+                    type: "add-harness-schema-ref",
+                    path: "harness.json",
+                    reason: "harness.json is missing or has a stale IDE JSON Schema reference",
+                });
+            }
+            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}`,
+                });
+            }
+            // A harness that already matches the current generated surface except for
+            // opaque Pi routing fields is modern, not a legacy-routing candidate.
+            // Keep the explicit migration assessment for every other harness shape.
+            if (isRecord(harness) &&
+                currentState.files["harness.json"]?.relationship !==
+                    "matches-current-generated") {
+                const modelMigration = assessHarnessModelMigration(harness);
+                if (modelMigration.kind === "safe") {
+                    deterministicActions.push({
+                        type: "migrate-harness-model-fields",
+                        path: "harness.json",
+                        reason: "expand one proven-equivalent legacy model into the Pi LOW/MED/HIGH matrix",
+                    });
+                }
+                else if (modelMigration.kind === "ambiguous") {
+                    const state = currentState.files["harness.json"];
+                    const mergeTask = modelMergeTaskFor("harness.json", state, allPaths, recordedState);
+                    mergeTask.reason = `legacy model configuration requires a human/model merge: ${modelMigration.reason}`;
+                    mergeTask.mergeRules = [
+                        "Preserve every existing harness.json field unless the user explicitly approves its migration.",
+                        "Map only unambiguous complete provider/model references to executors.pi.LOW, MED, and HIGH.",
+                        "Do not retain defaultModel when all three tiers are present; do not invent a provider for bare model ids.",
+                        "Do not restore models, modelProfiles, modelRouting, cursor, or other legacy routing fields.",
+                    ];
+                    mergeTask.verification = [
+                        "loop-agent init check-update --repo-root . --json",
+                        "loop-agent inspect --repo-root .",
+                        "bash scripts/check-repo.sh",
+                    ];
+                    const existingTask = modelMergeTasks.findIndex((task) => task.path === "harness.json");
+                    if (existingTask >= 0)
+                        modelMergeTasks[existingTask] = mergeTask;
+                    else
+                        modelMergeTasks.push(mergeTask);
+                }
+            }
+        }
+        catch {
+            // leave malformed harness for model merge / doctor
+        }
+    }
+    const partial = {
+        repoRoot,
+        controllerVersion: currentState.controllerVersion,
+        surfaceState,
+        deterministicActions,
+        modelMergeTasks,
+        humanDecisions,
+        summary: {
+            missing: deterministicActions.filter((action) => action.type !== "bootstrap-surface").length,
+            modelMerge: modelMergeTasks.length,
+            humanDecision: humanDecisions.length,
+        },
+    };
+    const recommendedNext = recommendedNextFor(partial);
+    // Project settings are part of the surface. Do not inspect user home by default.
+    const piInspection = await inspectProjectPiSettings({ repoRoot });
+    return {
+        ...partial,
+        ok: deterministicActions.length === 0 &&
+            modelMergeTasks.length === 0 &&
+            humanDecisions.length === 0,
+        recommendedNext,
+        clientRecovery: {
+            pi: piInspection,
+        },
+    };
+}
+async function applySafeAction(input) {
+    if (input.action.type === "merge-pi-project-settings") {
+        return (await applyProjectPiSettingsMerge({ repoRoot: input.repoRoot })).wrote === true;
+    }
+    if (input.action.type === "add-harness-schema-ref") {
+        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))
+            return false;
+        if (harness.$schema === expectedHarnessSchemaRef(input.governanceRoot))
+            return false;
+        const next = {
+            ...harness,
+            $schema: expectedHarnessSchemaRef(input.governanceRoot),
+        };
+        await writeFile(target, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+        return true;
+    }
+    if (input.action.type === "strip-pi-requires-api-key") {
+        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) ||
+            !isRecord(harness.executors) ||
+            !isRecord(harness.executors.pi)) {
+            return false;
+        }
+        if (!Object.hasOwn(harness.executors.pi, "requiresApiKey")) {
+            return false;
+        }
+        const nextPi = { ...harness.executors.pi };
+        delete nextPi.requiresApiKey;
+        const next = {
+            ...harness,
+            executors: {
+                ...harness.executors,
+                pi: nextPi,
+            },
+        };
+        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.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") {
+        if (await exists(target))
+            return false;
+        await mkdir(target, { recursive: true });
+        return true;
+    }
+    const desired = await buildDesiredSurfaceContent({
+        assetRoot,
+        repoRoot: input.repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+        entry,
+    });
+    if (desired.content === undefined)
+        return false;
+    await mkdir(path.dirname(target), { recursive: true });
+    if (input.action.type === "refresh-managed-block") {
+        const existing = (await exists(target))
+            ? await readFile(target, "utf-8")
+            : "";
+        const next = input.action.path === ".gitignore"
+            ? mergeGitignoreManagedBlock(existing, desired.content)
+            : input.action.path === "README.md" && existing.trim().length === 0
+                ? buildTargetReadme({
+                    projectName: input.projectName,
+                    governanceRoot: input.governanceRoot,
+                })
+                : input.action.path === "AGENTS.md" && existing.trim().length === 0
+                    ? `# AGENTS.md\n\n${desired.content}\n`
+                    : mergeManagedBlock(existing, desired.content);
+        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");
+    return true;
+}
+export async function applyInitUpdate(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const { projectName, governanceRoot } = await resolveInitProjectContext({
+        repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+    });
+    const applied = [];
+    const skipped = [];
+    const clientRecoveryMode = input.clientRecovery ?? "auto";
+    if (input.bootstrapSurface) {
+        await writeInitSurfaceState({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            stateKind: "inferred-baseline",
+        });
+        applied.push({
+            type: "bootstrap-surface",
+            path: INIT_SURFACE_STATE_PATH,
+            reason: "wrote inferred init surface baseline",
+        });
+    }
+    if (input.applySafe) {
+        const existingSurface = await readExistingSurfaceState(repoRoot);
+        // Preserve source strength: recorded stays recorded so unchanged owned files
+        // remain deterministic refresh candidates; bootstrap/inferred stays inferred.
+        const preservedStateKind = existingSurface?.stateKind === "recorded"
+            ? "recorded"
+            : "inferred-baseline";
+        const report = await checkInitUpdate({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            clientRecovery: clientRecoveryMode,
+            homeDir: input.homeDir,
+        });
+        for (const action of report.deterministicActions) {
+            if (action.type === "bootstrap-surface") {
+                skipped.push(action);
+                continue;
+            }
+            // The report was produced immediately before this batch. Each action also
+            // performs its own target check; missing-file writes refuse existing paths,
+            // while managed blocks merge into the latest user-authored content.
+            if (await applySafeAction({ repoRoot, projectName, governanceRoot, action }))
+                applied.push(action);
+            else
+                skipped.push(action);
+        }
+        await writeInitSurfaceState({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            stateKind: preservedStateKind,
+            preserveOwnershipFrom: existingSurface,
+        });
+    }
+    // Pi user config is only mutated with explicit --client-recovery=user.
+    // Do not reinstall the project plugin here — that would bypass ownership and
+    // clobber user-modified plugins; plugin updates stay on deterministic actions.
+    if (clientRecoveryMode === "user") {
+        await applyPiRetryMerge({
+            homeDir: input.homeDir ?? os.homedir(),
+        });
+    }
+    return {
+        applied,
+        skipped,
+        report: await checkInitUpdate({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            clientRecovery: clientRecoveryMode,
+            homeDir: input.homeDir,
+        }),
+    };
+}
+function formatClientRecoverySummary(report) {
+    if (!report.clientRecovery?.pi)
+        return [];
+    const pi = report.clientRecovery.pi;
+    return [
+        `clientRecovery.pi.reason: ${pi.reason}`,
+        `clientRecovery.pi.action: ${pi.action}`,
+        `clientRecovery.pi.path: ${pi.path}`,
+    ];
+}
+function formatCheckUpdateText(report) {
+    return [
+        `loop-agent init update check for ${report.repoRoot}`,
+        `controllerVersion: ${report.controllerVersion}`,
+        `surfaceState: ${report.surfaceState}`,
+        `deterministicActions: ${report.deterministicActions.length}`,
+        `modelMergeTasks: ${report.modelMergeTasks.length}`,
+        `humanDecisions: ${report.humanDecisions.length}`,
+        ...formatClientRecoverySummary(report),
+        "recommendedNext:",
+        ...report.recommendedNext.map((item) => `- ${item}`),
+    ].join("\n");
+}
+function formatCheckUpdateMarkdown(report) {
+    const piLines = formatClientRecoverySummary(report).map((line) => `- ${line}`);
+    const lines = [
+        "# loop-agent init check-update",
+        "",
+        `- repoRoot: \`${report.repoRoot}\``,
+        `- controllerVersion: \`${report.controllerVersion}\``,
+        `- surfaceState: \`${report.surfaceState}\``,
+        ...(piLines.length > 0
+            ? ["", "## Client Recovery (Pi user config, read-only)", "", ...piLines]
+            : []),
+        "",
+        "## Deterministic Actions",
+        "",
+        ...(report.deterministicActions.length
+            ? report.deterministicActions.map((action) => `- \`${action.type}\` \`${action.path}\`: ${action.reason}`)
+            : ["- None"]),
+        "",
+        "## Model Merge Tasks",
+        "",
+    ];
+    if (report.modelMergeTasks.length === 0) {
+        lines.push("- None", "");
+    }
+    else {
+        for (const task of report.modelMergeTasks) {
+            lines.push(`### ${task.path}`, "", task.reason, "", "allowedPaths:", ...task.allowedPaths.map((item) => `- ${item}`), "", "forbiddenPaths:", ...task.forbiddenPaths.map((item) => `- ${item}`), "", "mergeRules:", ...task.mergeRules.map((item) => `- ${item}`), "", "verification:", ...task.verification.map((item) => `- ${item}`), "");
+        }
+    }
+    lines.push("## Human Decisions", "", ...(report.humanDecisions.length
+        ? report.humanDecisions.map((decision) => `- \`${decision.path}\`: ${decision.reason}`)
+        : ["- None"]), "", "## Recommended Next", "", ...report.recommendedNext.map((item) => `- ${item}`), "");
+    return lines.join("\n");
+}
+export async function runInitDoctor(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const checks = [];
+    const add = (name, ok, message) => checks.push({ name, ok, message });
+    try {
+        const manifest = await loadHarnessManifest(repoRoot);
+        add("harness.json", manifest.adapter === "loop-agent" || manifest.project === "loop-agent", `project=${manifest.project}`);
+        add("governance root", await exists(path.join(repoRoot, manifest.governanceRoot, "README.md")), manifest.governanceRoot);
+    }
+    catch (error) {
+        add("harness.json", false, error instanceof Error ? error.message : String(error));
+    }
+    const agents = path.join(repoRoot, "AGENTS.md");
+    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, ".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/"), ".gitignore managed runtime ignores");
+    const requiredScripts = Object.keys(INIT_SCRIPT_FILES);
+    const missingScripts = [];
+    for (const script of requiredScripts) {
+        if (!(await exists(path.join(repoRoot, script))))
+            missingScripts.push(script);
+    }
+    add("script matrix", missingScripts.length === 0, missingScripts.length === 0
+        ? `${requiredScripts.length} scripts`
+        : `missing: ${missingScripts.join(", ")}`);
+    add("compat prompts", (await exists(path.join(repoRoot, ".harness", "prompts", "analyze.md"))) &&
+        (await exists(path.join(repoRoot, ".harness", "prompts", "plan.md"))), ".harness/prompts/analyze.md");
+    add("harness runtime dirs", await exists(path.join(repoRoot, ".harness", "dag-runs", "active")), ".harness/dag-runs/active");
+    return {
+        ok: checks.every((check) => check.ok),
+        repoRoot,
+        checks,
+    };
+}
+export async function runInitReconcile(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const preReport = await checkInitUpdate({
+        repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+    });
+    if (preReport.surfaceState === "missing") {
+        return { status: "needs-baseline", report: preReport };
+    }
+    if (preReport.humanDecisions.length > 0) {
+        return { status: "needs-human-decision", report: preReport };
+    }
+    const runtimeActivity = await input.readRuntimeActivity(repoRoot);
+    if (isInitRuntimeActive(runtimeActivity)) {
+        return {
+            status: "blocked-active-runtime",
+            report: preReport,
+            runtimeActivity,
+        };
+    }
+    const update = await applyInitUpdate({
+        repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+        applySafe: true,
+    });
+    const status = update.report.ok
+        ? "clean"
+        : update.report.modelMergeTasks.length > 0
+            ? "needs-model-merge"
+            : "needs-safe-update";
+    return {
+        status,
+        report: update.report,
+        applied: update.applied,
+        skipped: update.skipped,
+    };
+}
+function parseInitArgs(repoRoot, args) {
+    let subcommand;
+    let projectName;
+    let governanceRoot;
+    let profile = "full";
+    let merge = true;
+    let provider;
+    let model;
+    let clientRecovery = "auto";
+    let json = false;
+    let markdown = false;
+    let bootstrapSurface = false;
+    let applySafe = false;
+    let runId;
+    let upgradeStatus = false;
+    let upgradeContinue = false;
+    let upgradeReport = false;
+    let versionChoice;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if ((arg === "instructions" ||
+            arg === "doctor" ||
+            arg === "check-update" ||
+            arg === "update" ||
+            arg === "reconcile" ||
+            arg === "upgrade") &&
+            !subcommand) {
+            subcommand = arg;
+            continue;
+        }
+        if (arg === "--project-name")
+            projectName = args[++i];
+        else if (arg.startsWith("--project-name="))
+            projectName = arg.slice("--project-name=".length);
+        else if (arg === "--governance-root")
+            governanceRoot = args[++i] ?? governanceRoot;
+        else if (arg.startsWith("--governance-root="))
+            governanceRoot = arg.slice("--governance-root=".length);
+        else if (arg === "--profile")
+            profile = args[++i] ?? profile;
+        else if (arg.startsWith("--profile="))
+            profile = arg.slice("--profile=".length);
+        else if (arg === "--merge")
+            merge = true;
+        else if (arg === "--no-merge")
+            merge = false;
+        else if (arg === "--provider")
+            provider = args[++i];
+        else if (arg.startsWith("--provider="))
+            provider = arg.slice("--provider=".length);
+        else if (arg === "--model")
+            model = args[++i];
+        else if (arg.startsWith("--model="))
+            model = arg.slice("--model=".length);
+        else if (arg === "--client-recovery")
+            clientRecovery = parseClientRecoveryMode(args[++i]);
+        else if (arg.startsWith("--client-recovery="))
+            clientRecovery = parseClientRecoveryMode(arg.slice("--client-recovery=".length));
+        else if (arg === "--json")
+            json = true;
+        else if (arg === "--markdown")
+            markdown = true;
+        else if (arg === "--bootstrap-surface")
+            bootstrapSurface = true;
+        else if (arg === "--apply-safe")
+            applySafe = true;
+        else if (arg === "--run-id")
+            runId = args[++i];
+        else if (arg.startsWith("--run-id="))
+            runId = arg.slice("--run-id=".length);
+        else if (arg === "--status")
+            upgradeStatus = true;
+        else if (arg === "--continue")
+            upgradeContinue = true;
+        else if (arg === "--report")
+            upgradeReport = true;
+        else if (arg === "--version-choice")
+            versionChoice = args[++i];
+        else if (arg.startsWith("--version-choice="))
+            versionChoice = arg.slice("--version-choice=".length);
+        else if (arg.startsWith("-"))
+            throw new Error(`unknown init flag: ${arg}`);
+        else
+            throw new Error(`unexpected init argument: ${arg}`);
+    }
+    if (profile !== "full" && profile !== "minimal")
+        throw new Error("init --profile must be full or minimal");
+    if (versionChoice && !["current", "upgrade", "cancel", "retry"].includes(versionChoice)) {
+        throw new Error("init upgrade --version-choice must be current|upgrade|cancel|retry");
+    }
+    const normalizedModel = normalizeInitModelReference({ provider, model });
+    return {
+        repoRoot,
+        projectName,
+        governanceRoot,
+        profile,
+        merge,
+        provider,
+        model: normalizedModel,
+        clientRecovery,
+        subcommand,
+        json,
+        markdown,
+        bootstrapSurface,
+        applySafe,
+        runId,
+        upgradeStatus,
+        upgradeContinue,
+        upgradeReport,
+        versionChoice,
+    };
+}
+export async function runInit(repoRoot, rawArgs, dependencies) {
+    const parsed = parseInitArgs(repoRoot, rawArgs);
+    if (parsed.subcommand === "instructions") {
+        console.log(buildInitInstructions(parsed));
+        return;
+    }
+    if (parsed.subcommand === "doctor") {
+        const report = await runInitDoctor({ repoRoot: parsed.repoRoot });
+        console.log(JSON.stringify(report, null, 2));
+        if (!report.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (parsed.subcommand === "check-update") {
+        const report = await checkInitUpdate(parsed);
+        if (parsed.json)
+            console.log(JSON.stringify(report, null, 2));
+        else if (parsed.markdown)
+            console.log(formatCheckUpdateMarkdown(report));
+        else
+            console.log(formatCheckUpdateText(report));
+        return;
+    }
+    if (parsed.subcommand === "update") {
+        if (!parsed.bootstrapSurface && !parsed.applySafe) {
+            throw new Error("usage: init update [--bootstrap-surface] [--apply-safe]");
+        }
+        const result = await applyInitUpdate(parsed);
+        console.log(parsed.json
+            ? JSON.stringify(result, null, 2)
+            : formatInitUpdateResult(result));
+        return;
+    }
+    if (parsed.subcommand === "upgrade") {
+        const { runInitUpgrade } = await import("./init-upgrade.js");
+        const selected = [parsed.upgradeStatus, parsed.upgradeContinue, parsed.upgradeReport].filter(Boolean).length;
+        if (selected > 1)
+            throw new Error("init upgrade accepts only one of --status, --continue, or --report");
+        const result = await runInitUpgrade({
+            repoRoot: parsed.repoRoot,
+            runId: parsed.runId,
+            mode: parsed.upgradeStatus ? "status" : parsed.upgradeContinue ? "continue" : parsed.upgradeReport ? "report" : "start",
+            versionChoice: parsed.versionChoice,
+            readRuntimeActivity: dependencies.readRuntimeActivity,
+        });
+        if ("markdown" in result)
+            console.log(result.markdown);
+        else
+            console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitUpgradeResult(result));
+        return;
+    }
+    if (parsed.subcommand === "reconcile") {
+        const result = await runInitReconcile({
+            ...parsed,
+            readRuntimeActivity: dependencies.readRuntimeActivity,
+        });
+        console.log(parsed.json
+            ? JSON.stringify(result, null, 2)
+            : formatReconcileResult(result));
+        return;
+    }
+    const result = await initializeLoopAgentProject(parsed);
+    console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitResult(result));
+}
+function formatInitUpgradeResult(result) {
+    return [
+        `loop-agent init upgrade: ${result.status}`,
+        `runId: ${result.runId}`,
+        `phase: ${result.phase}`,
+        `modelMergeTasks: ${result.modelMergeTasks.length}`,
+        `humanDecisions: ${result.humanDecisions.length}`,
+        `next: ${result.nextAction}`,
+    ].join("\n");
+}
+function formatInitUpdateResult(result) {
+    return [
+        "loop-agent init update complete",
+        `applied: ${result.applied.length}`,
+        `skipped: ${result.skipped.length}`,
+        `remaining deterministicActions: ${result.report.deterministicActions.length}`,
+        `remaining modelMergeTasks: ${result.report.modelMergeTasks.length}`,
+        "recommendedNext:",
+        ...result.report.recommendedNext.map((item) => `- ${item}`),
+    ].join("\n");
+}
+function formatReconcileResult(result) {
+    const lines = [
+        `loop-agent init reconcile: ${result.status}`,
+        `surfaceState: ${result.report.surfaceState}`,
+    ];
+    if (result.applied && result.skipped) {
+        lines.push(`applied: ${result.applied.length}`, `skipped: ${result.skipped.length}`);
+    }
+    if (result.runtimeActivity) {
+        lines.push(`activeDagRuns: ${result.runtimeActivity.activeDagRunIds.length}`, `activeWorkerTasks: ${result.runtimeActivity.activeWorkerTasks}`, `activeWorkerBatches: ${result.runtimeActivity.activeWorkerBatches}`);
+        if (result.runtimeActivity.workerProjectionError) {
+            lines.push(`workerProjectionError: ${result.runtimeActivity.workerProjectionError}`);
+        }
+    }
+    lines.push(`deterministicActions: ${result.report.deterministicActions.length}`, `modelMergeTasks: ${result.report.modelMergeTasks.length}`, `humanDecisions: ${result.report.humanDecisions.length}`, "recommendedNext:", ...result.report.recommendedNext.map((item) => `- ${item}`));
+    return lines.join("\n");
+}
+function formatInitResult(result) {
+    return [
+        `Initialized loop-agent harness at ${result.repoRoot}`,
+        `project: ${result.projectName}`,
+        `governanceRoot: ${result.governanceRoot}`,
+        `profile: ${result.profile}`,
+        `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, ${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) {
+    const files = [];
+    async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else
+                files.push(repoRelative(repoRoot, full));
+        }
+    }
+    await access(repoRoot);
+    await walk(repoRoot);
+    return files.sort();
+}