@tea-agent/loop-agent 0.2.1 → 0.4.0

package/dist/commands/init.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { access, copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -5,6 +6,7 @@ import { copyDir } from "../shared/copy-dir.js";
 import { loadHarnessManifest } from "../governance/harness.js";
 const MANAGED_BLOCK_START = "<!-- LOOP_AGENT_INIT_START -->";
 const MANAGED_BLOCK_END = "<!-- LOOP_AGENT_INIT_END -->";
+const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
 const CORE_DOC_FILES = [
     "README.md",
     "architecture/runtime-boundaries.md",
@@ -88,474 +90,474 @@ const COMPAT_PROMPTS = {
     ].join("\n"),
 };
 const GOVERNANCE_ROOT_TOKEN = "__LOOP_AGENT_GOVERNANCE_ROOT__";
-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"
-  "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_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"
+  "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_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_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_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_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 docs/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_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 docs/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_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}"
-
-skill_md="skills/loop-agent/SKILL.md"
-if [[ ! -f "\${skill_md}" ]]; then
-  echo "skill entry 检查失败：缺少 \${skill_md}" >&2
-  exit 1
-fi
-
-required_refs=(
-  "references/harness-policy.md"
-  "references/hybrid-dag.md"
-  "references/verification-and-failure-handling.md"
-  "references/command-reference.md"
-)
-
-missing=()
-for ref in "\${required_refs[@]}"; do
-  [[ -f "skills/loop-agent/\${ref}" ]] || missing+=("\${ref}")
-done
-
-while IFS= read -r ref; do
-  [[ -z "\${ref}" ]] && continue
-  [[ -f "skills/loop-agent/\${ref}" ]] || missing+=("\${ref}")
-done < <(grep -Eo 'references/[A-Za-z0-9._/-]+\\.md' "\${skill_md}" | sort -u || true)
-
-if (( \${#missing[@]} > 0 )); then
-  echo "skill entry 检查失败：引用的 reference 文件不存在：" >&2
-  printf '  - %s\\n' "\${missing[@]}" >&2
-  exit 1
-fi
-
-line_count="$(wc -l < "\${skill_md}" | tr -d ' ')"
-if [[ "\${line_count}" =~ ^[0-9]+$ && "\${line_count}" -gt 220 ]]; then
-  echo "skill entry 检查警告：\${skill_md} 行数为 \${line_count}，建议保持入口精简并把细节放入 references/" >&2
-fi
-
-echo "skill entry 检查通过：references ok, lines=\${line_count}"
+const INIT_CHECK_SKILL_ENTRY_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+skill_md="skills/loop-agent/SKILL.md"
+if [[ ! -f "\${skill_md}" ]]; then
+  echo "skill entry 检查失败：缺少 \${skill_md}" >&2
+  exit 1
+fi
+
+required_refs=(
+  "references/harness-policy.md"
+  "references/hybrid-dag.md"
+  "references/verification-and-failure-handling.md"
+  "references/command-reference.md"
+)
+
+missing=()
+for ref in "\${required_refs[@]}"; do
+  [[ -f "skills/loop-agent/\${ref}" ]] || missing+=("\${ref}")
+done
+
+while IFS= read -r ref; do
+  [[ -z "\${ref}" ]] && continue
+  [[ -f "skills/loop-agent/\${ref}" ]] || missing+=("\${ref}")
+done < <(grep -Eo 'references/[A-Za-z0-9._/-]+\\.md' "\${skill_md}" | sort -u || true)
+
+if (( \${#missing[@]} > 0 )); then
+  echo "skill entry 检查失败：引用的 reference 文件不存在：" >&2
+  printf '  - %s\\n' "\${missing[@]}" >&2
+  exit 1
+fi
+
+line_count="$(wc -l < "\${skill_md}" | tr -d ' ')"
+if [[ "\${line_count}" =~ ^[0-9]+$ && "\${line_count}" -gt 220 ]]; then
+  echo "skill entry 检查警告：\${skill_md} 行数为 \${line_count}，建议保持入口精简并把细节放入 references/" >&2
+fi
+
+echo "skill entry 检查通过：references ok, lines=\${line_count}"
 `;
-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"
-)
-
-for check in "\${checks[@]}"; do
-  echo "==> bash \${check}"
-  bash "\${check}"
-  echo
-done
-
-echo "仓库治理检查全部通过"
+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"
+)
+
+for check in "\${checks[@]}"; do
+  echo "==> bash \${check}"
+  bash "\${check}"
+  echo
+done
+
+echo "仓库治理检查全部通过"
 `;
-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_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
-}
-
-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
-        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 与 docs/verification-matrix.md。"
-fi
-
-if (( \${#notes[@]} > 0 )); then
-  echo "项目验证探测备注："
-  for note in "\${notes[@]}"; do
-    echo "  - \${note}"
-  done
-fi
+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
+}
+
+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
+        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 与 docs/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_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,
@@ -846,6 +848,236 @@ async function writeCompatPrompts(input) {
         });
     }
 }
+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);
+}
+function normalizeRelativePath(relativePath) {
+    return relativePath.split(path.sep).join("/");
+}
+function manifestPathToTargetPath(relativePath, governanceRoot) {
+    if (governanceRoot !== "docs" && relativePath.startsWith("docs/")) {
+        return `${governanceRoot}/${relativePath.slice("docs/".length)}`;
+    }
+    return relativePath;
+}
+function targetPathToManifestPath(relativePath, governanceRoot) {
+    if (governanceRoot !== "docs" && relativePath.startsWith(`${governanceRoot}/`)) {
+        return `docs/${relativePath.slice(`${governanceRoot}/`.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 entries = initFullRequired.map((relativePath) => ({
+        path: relativePath,
+        mode: initSurface[relativePath] ?? inferInitSurfaceMode(relativePath),
+    }));
+    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 };
+}
+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")
+        return "managed-block";
+    if (relativePath === "harness.json" ||
+        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: buildManagedAgentsBlock({
+                projectName: input.projectName,
+                governanceRoot: input.governanceRoot,
+            }),
+        };
+    }
+    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.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] };
+    }
+    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 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;
+}
+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,
+        });
+        const sourceSha256 = desired.content === undefined ? undefined : sha256Text(desired.content);
+        const base = {
+            status: targetStat ? "present" : "missing",
+            relationship: "missing-from-target",
+            sourceSha256,
+            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 currentBlock = extractManagedBlock(current.toString("utf-8"));
+            files[targetRelativePath] = {
+                ...base,
+                currentSha256,
+                relationship: currentBlock && sourceSha256 && sha256Text(currentBlock) === sourceSha256
+                    ? "managed-block-current"
+                    : "managed-block-present",
+            };
+            continue;
+        }
+        files[targetRelativePath] = {
+            ...base,
+            currentSha256,
+            relationship: sourceSha256 && 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);
+    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;
+}
+async function resolveInitProjectContext(input) {
+    const harness = await readJsonIfExists(path.join(input.repoRoot, "harness.json"));
+    return {
+        projectName: input.projectName ??
+            (typeof harness.project === "string" ? harness.project : undefined) ??
+            path.basename(input.repoRoot),
+        governanceRoot: input.governanceRoot ??
+            (typeof harness.governanceRoot === "string" ? harness.governanceRoot : undefined) ??
+            "docs",
+    };
+}
 function buildManagedReadmeBlock(input) {
     return [
         MANAGED_BLOCK_START,
@@ -1389,8 +1621,277 @@ export async function initializeLoopAgentProject(options) {
     }
     await ensureHarnessDirs(repoRoot, written);
     await writeCompatPrompts({ repoRoot, merge, written, skipped });
+    await writeInitSurfaceState({ repoRoot, projectName, governanceRoot, stateKind: "recorded" });
+    written.push(INIT_SURFACE_STATE_PATH);
     return { repoRoot, projectName, governanceRoot, profile, written, skipped };
 }
+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) {
+    return {
+        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 .",
+            "bash scripts/check-repo.sh",
+        ],
+    };
+}
+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;
+}
+export async function checkInitUpdate(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const { projectName, governanceRoot } = await resolveInitProjectContext({
+        repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+    });
+    const recordedState = await readExistingSurfaceState(repoRoot);
+    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 = [];
+    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)) {
+        if (state.relationship === "missing-from-target") {
+            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") {
+            if (state.mode === "directory") {
+                humanDecisions.push({
+                    path: pathName,
+                    reason: "required init directory path exists but is not a directory",
+                });
+            }
+            else {
+                modelMergeTasks.push(modelMergeTaskFor(pathName, state, allPaths));
+            }
+        }
+    }
+    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);
+    return {
+        ...partial,
+        ok: deterministicActions.length === 0 &&
+            modelMergeTasks.length === 0 &&
+            humanDecisions.length === 0,
+        recommendedNext,
+    };
+}
+async function applySafeAction(input) {
+    const assetRoot = await findPackageRoot();
+    const entry = {
+        path: input.action.path,
+        mode: input.action.type === "create-directory"
+            ? "directory"
+            : input.action.type === "copy-missing"
+                ? "copied"
+                : input.action.type === "refresh-managed-block"
+                    ? "managed-block"
+                    : "generated",
+    };
+    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 === "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 (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 = [];
+    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 report = await checkInitUpdate({ repoRoot, projectName, governanceRoot });
+        for (const action of report.deterministicActions) {
+            if (action.type === "bootstrap-surface") {
+                skipped.push(action);
+                continue;
+            }
+            const currentState = await buildCurrentSurfaceState({
+                repoRoot,
+                projectName,
+                governanceRoot,
+                stateKind: "inferred-baseline",
+            });
+            const relationship = currentState.files[action.path]?.relationship;
+            if (relationship === "local-existing-unknown") {
+                skipped.push(action);
+                continue;
+            }
+            if (await applySafeAction({ repoRoot, projectName, governanceRoot, action }))
+                applied.push(action);
+            else
+                skipped.push(action);
+        }
+        await writeInitSurfaceState({ repoRoot, projectName, governanceRoot, stateKind: "inferred-baseline" });
+    }
+    return {
+        applied,
+        skipped,
+        report: await checkInitUpdate({ repoRoot, projectName, governanceRoot }),
+    };
+}
+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}`,
+        "recommendedNext:",
+        ...report.recommendedNext.map((item) => `- ${item}`),
+    ].join("\n");
+}
+function formatCheckUpdateMarkdown(report) {
+    const lines = [
+        "# loop-agent init check-update",
+        "",
+        `- repoRoot: \`${report.repoRoot}\``,
+        `- controllerVersion: \`${report.controllerVersion}\``,
+        `- surfaceState: \`${report.surfaceState}\``,
+        "",
+        "## 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 = [];
@@ -1432,9 +1933,12 @@ function parseInitArgs(repoRoot, args) {
     let provider;
     let model;
     let json = false;
+    let markdown = false;
+    let bootstrapSurface = false;
+    let applySafe = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
-        if ((arg === "instructions" || arg === "doctor") && !subcommand) {
+        if ((arg === "instructions" || arg === "doctor" || arg === "check-update" || arg === "update") && !subcommand) {
             subcommand = arg;
             continue;
         }
@@ -1464,6 +1968,12 @@ function parseInitArgs(repoRoot, args) {
             model = arg.slice("--model=".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.startsWith("-"))
             throw new Error(`unknown init flag: ${arg}`);
         else
@@ -1471,7 +1981,20 @@ function parseInitArgs(repoRoot, args) {
     }
     if (profile !== "full" && profile !== "minimal")
         throw new Error("init --profile must be full or minimal");
-    return { repoRoot, projectName, governanceRoot, profile, merge, provider, model, subcommand, json };
+    return {
+        repoRoot,
+        projectName,
+        governanceRoot,
+        profile,
+        merge,
+        provider,
+        model,
+        subcommand,
+        json,
+        markdown,
+        bootstrapSurface,
+        applySafe,
+    };
 }
 export async function runInit(repoRoot, rawArgs) {
     const parsed = parseInitArgs(repoRoot, rawArgs);
@@ -1486,9 +2009,38 @@ export async function runInit(repoRoot, rawArgs) {
             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;
+    }
     const result = await initializeLoopAgentProject(parsed);
     console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitResult(result));
 }
+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 formatInitResult(result) {
     return [
         `Initialized loop-agent harness at ${result.repoRoot}`,