@tea-agent/loop-agent 0.4.0 → 0.5.0

package/dist/commands/init.js

@@ -6,6 +6,8 @@ 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 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 CORE_DOC_FILES = [
     "README.md",
@@ -90,474 +92,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,
@@ -720,17 +722,88 @@ function mergeManagedBlock(existing, block) {
     }
     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; keep prompts/ and directory structure shareable. */
+export function buildManagedGitignoreBlock() {
+    return [
+        GITIGNORE_BLOCK_START,
+        "# loop-agent runtime: ignore personal/session facts; keep prompts and directory placeholders shareable",
+        "",
+        "# tasks (source + runtime state per developer/session)",
+        ".harness/tasks/*",
+        "!.harness/tasks/.gitkeep",
+        "",
+        "# DAG runs",
+        ".harness/dag-runs/active/*",
+        "!.harness/dag-runs/active/.gitkeep",
+        ".harness/dag-runs/completed/*",
+        "!.harness/dag-runs/completed/.gitkeep",
+        ".harness/dag-runs/paused/*",
+        "!.harness/dag-runs/paused/.gitkeep",
+        "",
+        "# one-shot executor runs",
+        ".harness/runs/*",
+        "!.harness/runs/.gitkeep",
+        "",
+        "# session / cache / logs / recomputable surface state",
+        ".harness/live/",
+        ".harness/cache/",
+        ".harness/*.log",
+        ".harness/init-surface.json",
+        "",
+        "# worker task pool",
+        ".task-pool/",
+        "",
+        "# multi-worktree parallel mode",
+        ".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 modelOverride = input.provider || input.model
-        ? {
-            analyze: { provider: input.provider, model: input.model },
-            plan: { provider: input.provider, model: input.model },
-            implement: { provider: input.provider, model: input.model },
-            verify: { provider: input.provider, model: input.model },
-            retrospective: { provider: input.provider, model: input.model },
-        }
-        : undefined;
-    return {
+    const templateExecutors = isRecord(input.template.executors)
+        ? { ...input.template.executors }
+        : {};
+    const existingExecutors = isRecord(input.existing.executors)
+        ? input.existing.executors
+        : {};
+    // Cursor executor is opt-in for package developers; do not project it to target apps.
+    // Keep it only when the target already configured executors.cursor.
+    if (!isRecord(existingExecutors.cursor)) {
+        delete templateExecutors.cursor;
+    }
+    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;
+    }
+    // Prefer DAG-facing executors.*.defaultModel over legacy top-level models.*.
+    // --provider/--model still apply as a convenience override for pi defaultModel.
+    if (input.provider || input.model) {
+        const piExisting = isRecord(mergedExecutors.pi) ? mergedExecutors.pi : {};
+        mergedExecutors.pi = {
+            ...piExisting,
+            ...(input.model ? { defaultModel: input.model } : {}),
+        };
+    }
+    const harness = {
         ...input.existing,
         version: 1,
         project: input.projectName,
@@ -771,11 +844,30 @@ function buildHarness(input) {
             standardVerify: "bash scripts/ci-governance.sh",
             fullVerify: "bash scripts/ci.sh",
         }),
-        models: modelOverride ?? input.existing.models ?? input.template.models ?? {},
-        modelProfiles: input.existing.modelProfiles ?? input.template.modelProfiles ?? {},
-        modelRouting: input.existing.modelRouting ?? input.template.modelRouting ?? {},
-        executors: mergeRecord(input.template.executors, input.existing.executors),
+        executors: mergedExecutors,
     };
+    // Do not project legacy step-routing models / modelProfiles / modelRouting into
+    // new or refreshed harness.json. Keep them only when the target already has them
+    // so old files remain loadable until the user migrates.
+    if (isRecord(input.existing.models) && Object.keys(input.existing.models).length > 0) {
+        harness.models = input.existing.models;
+    }
+    else {
+        delete harness.models;
+    }
+    if (isRecord(input.existing.modelProfiles) && Object.keys(input.existing.modelProfiles).length > 0) {
+        harness.modelProfiles = input.existing.modelProfiles;
+    }
+    else {
+        delete harness.modelProfiles;
+    }
+    if (isRecord(input.existing.modelRouting) && Object.keys(input.existing.modelRouting).length > 0) {
+        harness.modelRouting = input.existing.modelRouting;
+    }
+    else {
+        delete harness.modelRouting;
+    }
+    return harness;
 }
 async function writeTextIfMissing(input) {
     const target = path.join(input.repoRoot, input.relativePath);
@@ -899,8 +991,11 @@ function inferInitSurfaceMode(relativePath) {
         relativePath.endsWith("/")) {
         return "directory";
     }
-    if (relativePath === "README.md" || relativePath === "AGENTS.md")
+    if (relativePath === "README.md" ||
+        relativePath === "AGENTS.md" ||
+        relativePath === ".gitignore") {
         return "managed-block";
+    }
     if (relativePath === "harness.json" ||
         relativePath.startsWith("scripts/") ||
         relativePath.startsWith(".harness/prompts/") ||
@@ -934,6 +1029,9 @@ async function buildDesiredSurfaceContent(input) {
             }),
         };
     }
+    if (manifestPath === ".gitignore") {
+        return { content: buildManagedGitignoreBlock() };
+    }
     if (manifestPath === "harness.json") {
         const template = await readJsonIfExists(path.join(input.assetRoot, "harness.json"));
         return {
@@ -953,6 +1051,16 @@ async function buildDesiredSurfaceContent(input) {
         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({
@@ -1031,7 +1139,10 @@ async function buildCurrentSurfaceState(input) {
         const current = await readFile(targetPath);
         const currentSha256 = sha256Buffer(current);
         if (entry.mode === "managed-block") {
-            const currentBlock = extractManagedBlock(current.toString("utf-8"));
+            const text = current.toString("utf-8");
+            const currentBlock = entry.path === ".gitignore" || targetRelativePath === ".gitignore"
+                ? extractGitignoreManagedBlock(text)
+                : extractManagedBlock(text);
             files[targetRelativePath] = {
                 ...base,
                 currentSha256,
@@ -1462,7 +1573,8 @@ export function buildInitInstructions(input) {
         "- After deterministic initialization, inspect README/config/build files (for example package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gradle files, Makefile, .sln/.csproj, or project-specific scripts) and adapt `scripts/ci-tests.sh` plus the verification matrix to the real project.",
         "- Enrich the root `README.md`: keep the deterministic project title and the loop-agent managed block intact, and fill the human-authored sections (项目概览, 技术栈与目录结构, 开发与验证) from the target project's actual files. The root README must serve both as a human-first project entry and as an agent work entry; replace the initialization-model supplement comments when the project files provide the information.",
         "- Populate `docs/verification-matrix.md` with the target project's actual quick, standard, and full verification commands derived from its real language and toolchain, keeping the governance rows intact.",
-        "- Copy repo-local skills by default so the target repo has auditable skill instructions.",
+        "- Copy repo-local skills by default so the target repo has auditable skill instructions; full profile also mirrors skills into `.agents/skills/` for external agents.",
+        "- Merge a loop-agent managed block into `.gitignore` that ignores harness runtime facts (tasks, dag-runs, runs, live, cache, init-surface.json, .task-pool) while keeping prompts and directory placeholders shareable.",
         "- Do not copy examples by default; examples stay bundled in the tool and are available through `loop-agent examples`.",
         "- Add or update a loop-agent managed block in AGENTS.md.",
         "- 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.",
@@ -1556,6 +1668,18 @@ export async function initializeLoopAgentProject(options) {
         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, projectName, governanceRoot });
         if (generated) {
@@ -1604,9 +1728,21 @@ export async function initializeLoopAgentProject(options) {
             targetRelativePath: "skills",
             written,
         });
+        // Mirror bundled skills into the agent-compatible `.agents/skills/` path so
+        // external agents (e.g. OpenCode) that auto-discover `.agents/skills/<name>/SKILL.md`
+        // share the same skill content as loop-agent's primary `skills/` path.
+        // The package still ships only `skills/`; `.agents/skills` is a target projection.
+        await copyDirMerge({
+            assetRoot,
+            repoRoot,
+            sourceRelativePath: "skills",
+            targetRelativePath: ".agents/skills",
+            written,
+        });
     }
     else {
         skipped.push("skills/");
+        skipped.push(".agents/skills/");
     }
     skipped.push("examples/");
     for (const [relativePath, content] of Object.entries(buildInitScriptFiles(governanceRoot))) {
@@ -1736,6 +1872,27 @@ export async function checkInitUpdate(input) {
             }
         }
     }
+    // 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 (isRecord(harness) &&
+                isRecord(harness.executors) &&
+                isRecord(harness.executors.pi) &&
+                Object.prototype.hasOwnProperty.call(harness.executors.pi, "requiresApiKey")) {
+                deterministicActions.push({
+                    type: "strip-pi-requires-api-key",
+                    path: "harness.json",
+                    reason: "executors.pi.requiresApiKey is unused; strip it while keeping user model config and cursor.requiresApiKey",
+                });
+            }
+        }
+        catch {
+            // leave malformed harness for model merge / doctor
+        }
+    }
     const partial = {
         repoRoot,
         controllerVersion: currentState.controllerVersion,
@@ -1759,6 +1916,29 @@ export async function checkInitUpdate(input) {
     };
 }
 async function applySafeAction(input) {
+    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.prototype.hasOwnProperty.call(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;
+    }
     const assetRoot = await findPackageRoot();
     const entry = {
         path: input.action.path,
@@ -1789,11 +1969,13 @@ async function applySafeAction(input) {
     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);
+        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;
     }
@@ -1826,16 +2008,18 @@ export async function applyInitUpdate(input) {
                 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 (action.type !== "strip-pi-requires-api-key") {
+                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);
@@ -1909,6 +2093,10 @@ export async function runInitDoctor(input) {
     const readme = path.join(repoRoot, "README.md");
     add("README loop-agent block", (await exists(readme)) && (await readFile(readme, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
     add("repo-local skills", await exists(path.join(repoRoot, "skills", "loop-agent", "SKILL.md")), "skills/loop-agent/SKILL.md");
+    add("agent-compatible skills mirror", await exists(path.join(repoRoot, ".agents", "skills", "loop-agent", "SKILL.md")), ".agents/skills/loop-agent/SKILL.md");
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const gitignoreContent = (await exists(gitignorePath)) ? await readFile(gitignorePath, "utf-8") : "";
+    add("gitignore loop-agent block", gitignoreContent.includes(GITIGNORE_BLOCK_START) && gitignoreContent.includes(".harness/tasks/*"), ".gitignore managed runtime ignores");
     const requiredScripts = Object.keys(INIT_SCRIPT_FILES);
     const missingScripts = [];
     for (const script of requiredScripts) {