@tea-agent/loop-agent 0.1.0 → 0.2.0

package/dist/commands/init.js

@@ -0,0 +1,1495 @@
+import { access, copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+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 CORE_DOC_FILES = [
+    "README.md",
+    "architecture/runtime-boundaries.md",
+    "development-principles.md",
+    "feature-workflow.md",
+    "verification-matrix.md",
+    "loop-agent-harness.md",
+    "harness-methodology-tdd.md",
+    "harness-methodology-verification.md",
+    "harness-methodology-debugging.md",
+];
+const GOVERNANCE_README_DIRS = [
+    "decisions",
+    "design",
+    "exec-plans",
+    "exec-plans/active",
+    "exec-plans/completed",
+    "progress",
+    "reports",
+];
+const DAG_HARD_GATE_TRIGGER = "For changes that affect the project's public contract, execution surface, delivery pipeline, automation/governance, data model, security or permission model, cross-module behavior, or user-visible workflows, this is a hard pre-edit gate: create the task, write both source files, generate the DAG, and review the DAG/writeSet before editing implementation files.";
+const COMPAT_PROMPTS = {
+    "analyze.md": [
+        "# Role: Task Analyst",
+        "",
+        "Read the repository entrypoints, task source materials, and relevant docs.",
+        "Return an analysis report covering objective, current state, affected files, constraints, risks, and open questions.",
+        "Do not modify files.",
+        "",
+    ].join("\n"),
+    "spec.md": [
+        "# Role: Specification Writer",
+        "",
+        "Turn the task source and analysis into a bounded implementation contract.",
+        "State scope, non-goals, acceptance criteria, allowed paths, forbidden paths, and verification commands.",
+        "Do not modify files outside task-owned artifacts.",
+        "",
+    ].join("\n"),
+    "plan.md": [
+        "# Role: Implementation Planner",
+        "",
+        "Create a minimal, ordered, verifiable implementation plan from the task source and analysis.",
+        "Keep the plan aligned with allowed paths, forbidden paths, hard constraints, rollback points, and verification.",
+        "Do not modify implementation files.",
+        "",
+    ].join("\n"),
+    "implement.md": [
+        "# Role: Bounded Implementer",
+        "",
+        "Implement the approved plan with the smallest focused change.",
+        "Stay within allowed paths and writeSet. Preserve unrelated user changes. Do not use placeholder implementations.",
+        "",
+    ].join("\n"),
+    "verify.md": [
+        "# Role: Verifier",
+        "",
+        "Run or specify deterministic verification for the completed change.",
+        "Report exact commands, pass/fail results, residual risk, and whether acceptance criteria are covered.",
+        "",
+    ].join("\n"),
+    "retrospective.md": [
+        "# Role: Retrospective Writer",
+        "",
+        "Summarize what changed, why, verification evidence, risks, and follow-up work.",
+        "Promote durable lessons to docs, reports, progress, tests, scripts, or templates when appropriate.",
+        "",
+    ].join("\n"),
+    "feature-study-analyze.md": [
+        "# Role: Feature Study Analyst",
+        "",
+        "Analyze configured reference repos/docs read-only. Identify architecture, state, data flow, and transferable patterns.",
+        "Do not edit reference repositories.",
+        "",
+    ].join("\n"),
+    "feature-study-plan.md": [
+        "# Role: Feature Study Planner",
+        "",
+        "Produce a lightweight implementation plan from the feature-study analysis.",
+        "Prefer simple recoverable files and verifiable increments over heavyweight storage or broad rewrites.",
+        "",
+    ].join("\n"),
+};
+const GOVERNANCE_ROOT_TOKEN = "__LOOP_AGENT_GOVERNANCE_ROOT__";
+const 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_LINKS_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+if [[ ! -d "${GOVERNANCE_ROOT_TOKEN}" ]]; then
+  echo "docs 链接检查失败：缺少 ${GOVERNANCE_ROOT_TOKEN}/" >&2
+  exit 1
+fi
+
+missing=()
+while IFS= read -r -d '' file; do
+  while IFS= read -r link; do
+    [[ -z "\${link}" ]] && continue
+    [[ "\${link}" == http://* || "\${link}" == https://* || "\${link}" == mailto:* || "\${link}" == "#"* ]] && continue
+    [[ "\${link}" == *"://"* ]] && continue
+    target="\${link%%#*}"
+    [[ -z "\${target}" ]] && continue
+    [[ "\${target}" == /* ]] && continue
+    base="$(dirname "\${file}")"
+    if [[ ! -e "\${base}/\${target}" ]]; then
+      missing+=("\${file}: \${link}")
+    fi
+  done < <(grep -Eo '\\[[^]]+\\]\\([^)]+\\)' "\${file}" | sed -E 's/^.*\\(([^)]+)\\)$/\\1/' || true)
+done < <(find "${GOVERNANCE_ROOT_TOKEN}" -type f -name '*.md' -print0)
+
+if (( \${#missing[@]} > 0 )); then
+  echo "docs 链接检查失败：" >&2
+  for item in "\${missing[@]}"; do
+    echo "  - \${item}" >&2
+  done
+  exit 1
+fi
+
+echo "docs 链接检查通过"
+`;
+const INIT_CHECK_ACTIVE_PLAN_STATUS_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+active_dir="${GOVERNANCE_ROOT_TOKEN}/exec-plans/active"
+[[ -d "\${active_dir}" ]] || { echo "active plan 检查失败：缺少 \${active_dir}" >&2; exit 1; }
+
+bad=()
+while IFS= read -r -d '' file; do
+  name="$(basename "\${file}")"
+  [[ "\${name}" == "README.md" ]] && continue
+  if grep -Eiq 'status:[[:space:]]*(completed|done|closed)|状态[:：][[:space:]]*(已完成|完成|关闭)' "\${file}"; then
+    bad+=("\${file}")
+  fi
+done < <(find "\${active_dir}" -maxdepth 1 -type f -name '*.md' -print0)
+
+if (( \${#bad[@]} > 0 )); then
+  echo "active plan 状态检查失败：已完成计划不应留在 active 目录：" >&2
+  for item in "\${bad[@]}"; do
+    echo "  - \${item}" >&2
+  done
+  exit 1
+fi
+
+echo "active plan 状态检查通过"
+`;
+const INIT_CHECK_EXEC_PLAN_INDEX_SYNC_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+required=(
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/active/README.md"
+  "${GOVERNANCE_ROOT_TOKEN}/exec-plans/completed/README.md"
+)
+
+for item in "\${required[@]}"; do
+  if [[ ! -f "\${item}" ]]; then
+    echo "exec-plan 索引同步检查失败：缺少 \${item}" >&2
+    exit 1
+  fi
+done
+
+echo "exec-plan 索引同步检查通过"
+`;
+const INIT_CHECK_HARNESS_RUNTIME_CLEAN_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+failures=()
+
+count_entries() {
+  local dir="$1"
+  if [[ ! -d "\${dir}" ]]; then
+    echo 0
+    return
+  fi
+  find "\${dir}" -mindepth 1 -maxdepth 1 ! -name .gitkeep | wc -l | tr -d ' '
+}
+
+if [[ "\${HARNESS_ALLOW_ACTIVE_DAG_RUNS:-}" != "1" ]]; then
+  active_dag_count="$(count_entries ".harness/dag-runs/active")"
+  [[ "\${active_dag_count}" == "0" ]] || failures+=(".harness/dag-runs/active contains \${active_dag_count} entries")
+fi
+
+if [[ "\${HARNESS_ALLOW_ACTIVE_TOOL_RUNS:-\${HARNESS_ALLOW_ACTIVE_ONE_SHOT_RUNS:-}}" != "1" ]]; then
+  active_run_count="$(count_entries ".harness/runs/active")"
+  [[ "\${active_run_count}" == "0" ]] || failures+=(".harness/runs/active contains \${active_run_count} entries")
+fi
+
+if [[ -d artifacts ]]; then
+  artifact_count="$(find artifacts -mindepth 1 -maxdepth 1 ! -name .gitkeep | wc -l | tr -d ' ')"
+  [[ "\${artifact_count}" == "0" ]] || failures+=("root artifacts/ contains \${artifact_count} entries; use 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_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_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_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+cd "\${ROOT_DIR}"
+
+bash scripts/ci-governance.sh
+bash scripts/ci-tests.sh
+`;
+const INIT_SCRIPT_FILES = {
+    "scripts/check-engineering-structure.sh": INIT_CHECK_ENGINEERING_STRUCTURE_SH,
+    "scripts/check-doc-index.sh": INIT_CHECK_DOC_INDEX_SH,
+    "scripts/check-doc-links.sh": INIT_CHECK_DOC_LINKS_SH,
+    "scripts/check-active-plan-status.sh": INIT_CHECK_ACTIVE_PLAN_STATUS_SH,
+    "scripts/check-exec-plan-index-sync.sh": INIT_CHECK_EXEC_PLAN_INDEX_SYNC_SH,
+    "scripts/check-harness-runtime-clean.sh": INIT_CHECK_HARNESS_RUNTIME_CLEAN_SH,
+    "scripts/check-architecture-boundaries.sh": INIT_CHECK_ARCHITECTURE_BOUNDARIES_SH,
+    "scripts/check-skill-entry.sh": INIT_CHECK_SKILL_ENTRY_SH,
+    "scripts/check-repo.sh": INIT_CHECK_REPO_SH,
+    "scripts/ci-governance.sh": INIT_CI_GOVERNANCE_SH,
+    "scripts/ci-tests.sh": INIT_CI_TESTS_SH,
+    "scripts/ci.sh": INIT_CI_SH,
+};
+function buildInitScriptFiles(governanceRoot) {
+    return Object.fromEntries(Object.entries(INIT_SCRIPT_FILES).map(([relativePath, content]) => [
+        relativePath,
+        content.replaceAll(GOVERNANCE_ROOT_TOKEN, governanceRoot),
+    ]));
+}
+function repoRelative(targetRoot, filePath) {
+    return path.relative(targetRoot, filePath).split(path.sep).join("/");
+}
+async function exists(filePath) {
+    return Boolean(await stat(filePath).catch(() => null));
+}
+async function findPackageRoot() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (await exists(path.join(current, "package.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.resolve(".");
+        current = parent;
+    }
+}
+async function readJsonIfExists(filePath) {
+    if (!(await exists(filePath)))
+        return {};
+    return JSON.parse(await readFile(filePath, "utf-8"));
+}
+function mergeRecord(base, patch) {
+    return {
+        ...(typeof base === "object" && base !== null && !Array.isArray(base)
+            ? base
+            : {}),
+        ...patch,
+    };
+}
+function buildManagedAgentsBlock(input) {
+    return [
+        MANAGED_BLOCK_START,
+        "## loop-agent 治理",
+        "",
+        `本仓库已初始化为 \`${input.projectName}\` 的 loop-agent harness 项目。`,
+        "",
+        "### 默认立场",
+        "",
+        "- 仓库是记录系统：决策、契约、计划、验证、报告和交接应进入可追踪文件。",
+        "- 一次只推进一个有边界、可验证的工作块。",
+        "- 实现前先搜索现有代码、文档、脚本和测试，避免重复造轮子。",
+        "- Shell 验证是完成依据；模型建议不能替代命令证据。",
+        "- 保留无关的用户改动，不要回退自己没有做的修改。",
+        "",
+        "### 初始化闭环",
+        "",
+        "当用户要求在本仓库初始化 loop-agent，或发现 `README.md` / `docs/verification-matrix.md` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。",
+        "",
+        "标准流程：",
+        "",
+        "1. 运行 `loop-agent init instructions --repo-root .` 获取完整初始化指引。",
+        "2. 运行 `loop-agent init --repo-root . --profile full --merge` 完成确定性脚手架。",
+        "3. 立即读取目标项目的 README、manifest/build/config 文件和顶层源码/模块目录，识别项目类型、模块、运行入口和验证命令。",
+        "4. 基于真实项目文件补全或修正根 `README.md`、`docs/verification-matrix.md`，必要时适配 `scripts/ci-tests.sh`。",
+        "5. 运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .` 和 quick verification。",
+        "",
+        "如果仓库信息不足，写明“尚未从仓库文件中识别到 ...”以及下一步需要的事实；不要留下泛化占位符，也不要只提示用户稍后手填。",
+        "",
+        "### 开始顺序",
+        "",
+        "改文件前先完成：",
+        "",
+        "1. 运行 `pwd`。",
+        "2. 阅读 `README.md`。",
+        "3. 阅读 `harness.json`。",
+        `4. 阅读 \`${input.governanceRoot}/README.md\`。`,
+        `5. 实现类工作继续阅读 \`${input.governanceRoot}/development-principles.md\`、\`${input.governanceRoot}/feature-workflow.md\` 和 \`${input.governanceRoot}/verification-matrix.md\`。`,
+        `6. 涉及测试、验证声明或调试时继续阅读 \`${input.governanceRoot}/harness-methodology-tdd.md\`、\`${input.governanceRoot}/harness-methodology-verification.md\` 和 \`${input.governanceRoot}/harness-methodology-debugging.md\`。`,
+        "7. 查看最近提交、相关 plan/progress/report，并检查 `git status --short --branch`。",
+        "8. 运行与本次任务相关的最小基线验证。",
+        "",
+        "### Agent DAG 路径",
+        "",
+        "默认使用 Agent DAG 作为实现工作流：",
+        "",
+        "```bash",
+        "loop-agent new-task <task-id> \"任务标题\"",
+        "# write .harness/tasks/<task-id>/source/需求.md",
+        "# write .harness/tasks/<task-id>/source/执行约束.md",
+        "loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json",
+        "loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance",
+        "loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .",
+        "```",
+        "",
+        "任务 source 是必需项。`source/需求.md` 写目标、范围、非目标、验收标准和相关链接；`source/执行约束.md` 写允许路径、禁止路径、受保护变更、不变量、预期验证和失败条件。",
+        "",
+        "凡是影响项目公共契约、执行入口、交付流水线、自动化/治理、数据模型、安全或权限模型、跨模块行为、用户可见工作流的改动，都必须在编辑实现文件前先创建任务、写好两个 source 文件、生成 DAG，并审查 DAG/writeSet。",
+        "",
+        "执行 DAG 前必须审查 profile routing、governance profile、writer 的 `writeSet`、`allowedPaths`、`forbiddenPaths`、shell verification 和 decision gate mode。不要执行占位或过宽的写入范围。",
+        "",
+        "### 运行态与 Skills",
+        "",
+        "- `.harness/tasks/` 保存任务状态和 source 材料。",
+        "- `.harness/dag-runs/` 与 `.harness/runs/` 保存运行事实；已完成事实只读。",
+        "- `skills/` 保存仓库本地 skill 指令；本地缺失时 runtime 可回退到 npm 包内置 skills。",
+        "- 示例内置在工具中；优先使用 `loop-agent examples list` 和 `loop-agent examples show <name>` 查看，不默认提交到目标仓库。",
+        "",
+        "### 验证",
+        "",
+        `使用 \`${input.governanceRoot}/verification-matrix.md\` 选择验证命令。常用门禁：`,
+        "",
+        "```bash",
+        "bash scripts/check-repo.sh",
+        "bash scripts/ci-governance.sh",
+        "bash scripts/ci-tests.sh",
+        "bash scripts/ci.sh",
+        "loop-agent inspect",
+        "loop-agent doctor",
+        "loop-agent docs audit",
+        "```",
+        "",
+        "`scripts/ci-tests.sh` 必须反映目标项目真实语言和工具链。初始化生成版本会保守探测常见入口；当已知项目专属命令时，应按目标项目实际情况适配。",
+        "",
+        "Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或兼容 Bash。实际文件操作使用平台原生路径；`/` 仅用于稳定仓库引用、Markdown/JSON 证据引用和 glob 约定。",
+        "",
+        "### 交接",
+        "",
+        "较大的交接应说明改了什么、为什么这样改、验证命令和结果、影响到的 docs/tests/scripts/contracts、剩余风险和下一步。长期结论应进入 docs/progress、docs/reports、docs/exec-plans、docs/decisions、测试、脚本或模板。",
+        MANAGED_BLOCK_END,
+    ].join("\n");
+}
+function mergeManagedBlock(existing, block) {
+    const start = existing.indexOf(MANAGED_BLOCK_START);
+    const end = existing.indexOf(MANAGED_BLOCK_END);
+    if (start >= 0 && end > start) {
+        return `${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + MANAGED_BLOCK_END.length).trimStart()}`.trimEnd() + "\n";
+    }
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+function 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 {
+        ...input.existing,
+        version: 1,
+        project: input.projectName,
+        adapter: "loop-agent",
+        governanceRoot: input.governanceRoot,
+        features: mergeRecord(input.template.features, input.existing.features),
+        workflowPolicy: mergeRecord(input.template.workflowPolicy, input.existing.workflowPolicy),
+        entrypoints: mergeRecord(input.existing.entrypoints, {
+            readme: "README.md",
+            agents: "AGENTS.md",
+            governanceIndex: `${input.governanceRoot}/README.md`,
+            principles: `${input.governanceRoot}/development-principles.md`,
+            workflow: `${input.governanceRoot}/feature-workflow.md`,
+            verificationMatrix: `${input.governanceRoot}/verification-matrix.md`,
+            loopAgentHarness: `${input.governanceRoot}/loop-agent-harness.md`,
+        }),
+        artifacts: mergeRecord(input.existing.artifacts, {
+            templatesDir: `${input.governanceRoot}/templates`,
+            execPlansDir: `${input.governanceRoot}/exec-plans`,
+            progressDir: `${input.governanceRoot}/progress`,
+            reportsDir: `${input.governanceRoot}/reports`,
+            decisionsDir: `${input.governanceRoot}/decisions`,
+        }),
+        scripts: mergeRecord(input.existing.scripts, {
+            checkEngineeringStructure: "scripts/check-engineering-structure.sh",
+            checkDocIndex: "scripts/check-doc-index.sh",
+            checkDocLinks: "scripts/check-doc-links.sh",
+            checkActivePlanStatus: "scripts/check-active-plan-status.sh",
+            checkExecPlanIndexSync: "scripts/check-exec-plan-index-sync.sh",
+            checkHarnessRuntimeClean: "scripts/check-harness-runtime-clean.sh",
+            checkArchitectureBoundaries: "scripts/check-architecture-boundaries.sh",
+            checkSkillEntry: "scripts/check-skill-entry.sh",
+            checkRepo: "scripts/check-repo.sh",
+            ciGovernance: "scripts/ci-governance.sh",
+            ciTests: "scripts/ci-tests.sh",
+            ci: "scripts/ci.sh",
+            quickVerify: "bash scripts/check-repo.sh",
+            standardVerify: "bash scripts/ci-governance.sh",
+            fullVerify: "bash scripts/ci.sh",
+        }),
+        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),
+    };
+}
+async function writeTextIfMissing(input) {
+    const target = path.join(input.repoRoot, input.relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (await exists(target)) {
+        input.skipped.push(input.relativePath);
+        return;
+    }
+    await writeFile(target, input.content, "utf-8");
+    input.written.push(input.relativePath);
+}
+async function writeText(input) {
+    const target = path.join(input.repoRoot, input.relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (!input.merge && (await exists(target))) {
+        input.skipped.push(input.relativePath);
+        return;
+    }
+    await writeFile(target, input.content, "utf-8");
+    input.written.push(input.relativePath);
+}
+async function copyFileIfMissing(input) {
+    const source = path.join(input.assetRoot, input.sourceRelativePath);
+    const target = path.join(input.repoRoot, input.targetRelativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    if ((await exists(target)) && !input.merge) {
+        input.skipped.push(input.targetRelativePath);
+        return;
+    }
+    if (await exists(target)) {
+        input.skipped.push(input.targetRelativePath);
+        return;
+    }
+    await copyFile(source, target);
+    input.written.push(input.targetRelativePath);
+}
+async function copyDirMerge(input) {
+    const source = path.join(input.assetRoot, input.sourceRelativePath);
+    const target = path.join(input.repoRoot, input.targetRelativePath);
+    await copyDir(source, target);
+    input.written.push(input.targetRelativePath.endsWith("/") ? input.targetRelativePath : `${input.targetRelativePath}/`);
+}
+async function ensureHarnessDirs(repoRoot, written) {
+    const dirs = [
+        ".harness/prompts",
+        ".harness/tasks",
+        ".harness/dag-runs/active",
+        ".harness/dag-runs/completed",
+        ".harness/dag-runs/paused",
+        ".harness/runs/active",
+        ".harness/runs/completed",
+        ".harness/runs/failed",
+        ".harness/cache",
+        ".harness/live",
+    ];
+    for (const dir of dirs) {
+        await mkdir(path.join(repoRoot, dir), { recursive: true });
+        written.push(dir);
+    }
+}
+async function writeCompatPrompts(input) {
+    for (const [name, content] of Object.entries(COMPAT_PROMPTS)) {
+        await writeText({
+            repoRoot: input.repoRoot,
+            relativePath: path.join(".harness", "prompts", name),
+            content,
+            merge: input.merge,
+            written: input.written,
+            skipped: input.skipped,
+        });
+    }
+}
+function buildManagedReadmeBlock(input) {
+    return [
+        MANAGED_BLOCK_START,
+        "## loop-agent 治理",
+        "",
+        `本仓库已初始化为 \`${input.projectName}\` 的 loop-agent harness 项目。loop-agent 负责 Agent DAG 生成、校验、执行与收口，并保留运行态事实。下面的内容是 deterministic CLI 生成的保守入口；目标项目的具体语义（技术栈、模块、运行命令、验证命令）应由初始化模型根据实际文件补全。`,
+        "",
+        "### 项目入口",
+        "",
+        "- `README.md`（本文件）：人类首次进入项目和 agent 开工的首入口，应同时覆盖项目概览与开发/验证入口。",
+        "- `harness.json`：loop-agent entrypoints、验证命令与 adapter 设置。",
+        "- `AGENTS.md`：agent 在本仓库的工作协议。",
+        `- \`${input.governanceRoot}/README.md\` - 治理文档索引（含原则、工作流、验证矩阵与方法论）`,
+        "",
+        "### 开发与验证入口",
+        "",
+        "开发、测试和门禁命令（按目标项目实际技术栈补全；下面是 loop-agent 治理脚本）：",
+        "",
+        "```bash",
+        "bash scripts/check-repo.sh",
+        "bash scripts/ci-governance.sh",
+        "bash scripts/ci-tests.sh",
+        "bash scripts/ci.sh",
+        "loop-agent inspect",
+        "loop-agent doctor",
+        "loop-agent docs audit",
+        "```",
+        "",
+        "`scripts/ci-tests.sh` 必须反映目标项目真实语言和工具链。初始化生成版本会保守探测常见入口；当已知项目专属命令时，应按目标项目实际情况适配，并在 verification-matrix.md 中同步登记。",
+        "",
+        "### loop-agent 工作流入口",
+        "",
+        "默认使用 Agent DAG 作为实现工作流：",
+        "",
+        "```bash",
+        "loop-agent new-task <task-id> \"任务标题\"",
+        "# write .harness/tasks/<task-id>/source/需求.md",
+        "# write .harness/tasks/<task-id>/source/执行约束.md",
+        "loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json",
+        "loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance",
+        "loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .",
+        "```",
+        "",
+        `详细工作流见 \`${input.governanceRoot}/feature-workflow.md\`；验证矩阵见 \`${input.governanceRoot}/verification-matrix.md\`。任务 source 是必需项：\`source/需求.md\` 写目标、范围、非目标、验收标准和相关链接，\`source/执行约束.md\` 写允许路径、禁止路径、受保护变更、不变量、预期验证和失败条件。`,
+        "",
+        "### 文档导航",
+        "",
+        `- \`${input.governanceRoot}/README.md\` - 治理文档索引（含原则、工作流、验证矩阵与方法论）`,
+        `- \`${input.governanceRoot}/development-principles.md\` - 仓库开发原则`,
+        `- \`${input.governanceRoot}/architecture/runtime-boundaries.md\` - runtime 层边界与依赖方向`,
+        `- \`${input.governanceRoot}/feature-workflow.md\` - 有边界的功能工作流`,
+        `- \`${input.governanceRoot}/verification-matrix.md\` - 治理与项目专属验证命令`,
+        `- \`${input.governanceRoot}/loop-agent-harness.md\` - 目标项目如何使用 loop-agent`,
+        "- `AGENTS.md` - agent 工作协议",
+        "- `harness.json` - loop-agent 入口与验证命令配置",
+        "",
+        "Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或兼容 Bash。实际文件操作使用平台原生路径；`/` 仅用于稳定仓库引用、Markdown/JSON 证据引用和 glob 约定。",
+        MANAGED_BLOCK_END,
+    ].join("\n");
+}
+function buildTargetReadme(input) {
+    return [
+        `# ${input.projectName}`,
+        "",
+        "> 本文件是项目入口。上面一行保留项目名称；下方 loop-agent managed block 由 deterministic CLI 生成。本文件正文人类可维护，用于描述项目概览、技术栈、目录结构、运行/验证命令等。初始化模型应根据目标项目实际文件补全本节正文。",
+        "",
+        "## 项目概览",
+        "",
+        "<!-- 初始化模型补充：项目是什么、解决什么问题、当前阶段。 -->",
+        "",
+        "## 技术栈与目录结构",
+        "",
+        "<!-- 初始化模型补充：语言、框架、构建工具、关键依赖与目录约定。 -->",
+        "",
+        "## 开发与验证",
+        "",
+        "<!-- 初始化模型补充：本地开发、测试、构建、门禁命令。 -->",
+        "",
+        buildManagedReadmeBlock(input),
+        "",
+    ].join("\n");
+}
+function buildTargetDocsReadme(input) {
+    return [
+        "# 文档索引 / Documentation Index",
+        "",
+        `本目录是 \`${input.projectName}\` 的 loop-agent 治理根目录，用于沉淀目标项目的持久工程上下文：决策、契约、计划、验证、报告与交接资料，与具体语言、框架或业务领域无关。`,
+        "",
+        `This directory is the loop-agent governance root for \`${input.projectName}\`. It records durable engineering context for the target project, independent of language, framework, or business domain.`,
+        "",
+        "## 核心文档 / Core Documents",
+        "",
+        "- `development-principles.md` - 仓库开发原则 / repository development principles",
+        "- `architecture/runtime-boundaries.md` - runtime 层边界与依赖方向 / runtime layer boundaries and dependency direction",
+        "- `feature-workflow.md` - 有边界的功能工作流 / bounded feature workflow",
+        "- `verification-matrix.md` - 治理与项目专属验证命令 / governance and project-specific verification commands",
+        "- `loop-agent-harness.md` - 目标项目如何使用 loop-agent / how this target project uses loop-agent",
+        "",
+        "## 方法论 / Methodology",
+        "",
+        "- `harness-methodology-tdd.md` - 行为变更与缺陷修复的 TDD 纪律 / TDD discipline for behavior changes and bug fixes",
+        "- `harness-methodology-verification.md` - 完成声明前的验证纪律 / verification discipline before completion claims",
+        "- `harness-methodology-debugging.md` - 修复前的系统性调试工作流 / systematic debugging workflow before fixes",
+        "",
+        "## 制品目录 / Artifacts",
+        "",
+        "- `design/README.md` - 设计笔记与实现契约 / design notes and implementation contracts",
+        "- `exec-plans/active/README.md` - 活跃执行计划 / active execution plans",
+        "- `exec-plans/completed/README.md` - 已完成执行计划 / completed execution plans",
+        "- `progress/README.md` - 进度交接日志 / progress handoff logs",
+        "- `reports/README.md` - 验证与审计报告 / verification and audit reports",
+        "- `decisions/README.md` - 架构决策 / architecture decisions",
+        "- `templates/` - 可复用的计划、报告与 DAG 模板 / reusable planning, reporting, and DAG templates",
+        "",
+        "## 验证 / Verification",
+        "",
+        "```bash",
+        "bash scripts/check-repo.sh",
+        "bash scripts/ci-tests.sh",
+        "bash scripts/ci.sh",
+        "```",
+        "",
+        "`ci-tests.sh` 刻意保持语言中立：它会探测常见的项目验证入口，初始化模型应在已知目标项目专属命令时按实际情况适配本文件。 / `ci-tests.sh` is intentionally language-neutral. It detects common project verification entrypoints and should be adapted by the initialization model when the target project has custom commands.",
+        "",
+    ].join("\n");
+}
+function buildTargetRuntimeBoundaries(input) {
+    return [
+        "# Runtime Boundaries",
+        "",
+        `本文定义 \`${input.projectName}\` 的 runtime 层边界、允许的依赖方向和治理检查入口。初始化版本是语言中立（language-neutral）模板；初始化模型应根据目标项目真实目录和技术栈补充具体层名、模块边界和例外。`,
+        "",
+        "## 默认分层",
+        "",
+        "```text",
+        "Interface / Entry layer",
+        "  └─ CLI、HTTP API、UI 页面、job 入口或其他用户/系统入口",
+        "",
+        "Application / Use-case layer",
+        "  └─ 一次用户意图或业务动作的编排接口",
+        "",
+        "Domain / Workflow layer",
+        "  └─ 核心业务规则、状态机、工作流或领域模型",
+        "",
+        "Executors / Integrations layer",
+        "  └─ 外部工具、SDK、数据库、消息队列、浏览器、模型或 shell 适配",
+        "",
+        "Infrastructure / Store layer",
+        "  └─ 文件系统、数据库、缓存、运行事实、原子写入和生命周期副作用",
+        "",
+        "Governance layer",
+        "  └─ scripts/check-*.sh、CI、文档审计、边界检查和验证矩阵",
+        "```",
+        "",
+        "## 依赖方向",
+        "",
+        "- Entry layer 可以依赖 Application / Use-case layer。",
+        "- Application / Use-case layer 可以依赖 Domain / Workflow、Infrastructure 和 Integrations。",
+        "- Domain / Workflow layer 不应依赖 Entry layer 的格式化、argv、HTTP/UI 细节。",
+        "- Executors / Integrations 不应依赖 Entry layer 的输出格式。",
+        "- Infrastructure / Store 应集中副作用，不把 raw path mutation 或持久化细节扩散给上层。",
+        "",
+        "## 目标项目适配",
+        "",
+        "初始化后请根据真实项目结构补充：",
+        "",
+        "- 入口目录和入口文件。",
+        "- 核心业务/domain/workflow 模块。",
+        "- infrastructure/store/integration 模块。",
+        "- 允许的例外、迁移计划和对应验证命令。",
+        "",
+        "## Governance hooks",
+        "",
+        "```bash",
+        "bash scripts/check-architecture-boundaries.sh",
+        "bash scripts/check-repo.sh",
+        "```",
+        "",
+        "`scripts/check-architecture-boundaries.sh` 是保守模板：只有当目标项目存在可识别目录时才启用对应 import 检查。不要为了通过脚本删除真实边界问题；应更新本文或修正依赖方向。",
+        "",
+    ].join("\n");
+}
+function buildTargetDevelopmentPrinciples(input) {
+    return [
+        "# Development Principles",
+        "",
+        `\`${input.projectName}\` uses loop-agent governed development. These principles apply regardless of language, framework, or deployment model.`,
+        "",
+        "## Operating Stance",
+        "",
+        "- The repository is the record system. Decisions, contracts, plans, tests, reports, and handoffs belong in tracked files.",
+        "- Work advances in small, reversible, verifiable increments.",
+        "- Baseline verification comes before new work when the current state is uncertain.",
+        "- Completion is defined by fresh evidence, not by intent or confidence.",
+        "- Preserve unrelated user changes.",
+        "",
+        "## Principles",
+        "",
+        "1. One task advances one bounded work block.",
+        "2. Search existing code, docs, scripts, and tests before designing new behavior.",
+        "3. Shell verification is the completion authority.",
+        "4. Runtime state belongs in `.harness/`; durable decisions belong in `docs/`.",
+        "5. Model writer nodes must be bounded by explicit allowed and forbidden paths.",
+        "6. Advisory model output must be followed by deterministic verification.",
+        "7. Repeated constraints should become docs, tests, scripts, checks, or templates.",
+        "8. Do not keep hidden process state only in chat.",
+        "9. Do not add placeholders as completed implementation.",
+        "10. Prefer existing local project patterns before adding new abstractions.",
+        "",
+        "## Target Project Adaptation",
+        "",
+        "The initialized scripts provide language-neutral governance. The initialization model should adapt project-specific verification commands after reading the target project's actual files and toolchain.",
+        "",
+    ].join("\n");
+}
+function buildTargetFeatureWorkflow(input) {
+    return [
+        "# Feature Workflow",
+        "",
+        "This document describes how work should move through this target repository using loop-agent.",
+        "",
+        "## Session Protocol",
+        "",
+        "1. Orient: read `README.md`, `harness.json`, `AGENTS.md`, and this docs index.",
+        "2. Select: choose one bounded work block.",
+        "3. Contract: state deliverables, non-goals, completion criteria, verification commands, and failure conditions.",
+        "4. Implement: make the smallest coherent change and update required docs, scripts, and tests.",
+        "5. Verify: run governance checks plus target project verification.",
+        "6. Handoff: record evidence in docs/progress, docs/reports, an exec plan, or an ADR when useful.",
+        "",
+        "## Agent DAG Path",
+        "",
+        "```bash",
+        "loop-agent new-task <task-id> \"Task title\"",
+        "# write .harness/tasks/<task-id>/source/需求.md",
+        "# write .harness/tasks/<task-id>/source/执行约束.md",
+        "loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json",
+        "loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance",
+        "loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .",
+        "```",
+        "",
+        DAG_HARD_GATE_TRIGGER,
+        "",
+        "Before executing a DAG, review profile routing, governance profile, writer writeSet, allowed paths, forbidden paths, shell verification, and decision gate mode.",
+        "",
+        "## Verification",
+        "",
+        `Use \`${input.governanceRoot}/verification-matrix.md\` to choose the narrowest command that proves the claim.`,
+        "",
+    ].join("\n");
+}
+function buildTargetVerificationMatrix() {
+    return [
+        "# Verification Matrix",
+        "",
+        "Use the narrowest command that proves the claim. This matrix is language-neutral: governance checks are generated by loop-agent, while project-specific checks should reflect the target project's actual toolchain.",
+        "",
+        "| Claim | Minimum verification | Stronger verification |",
+        "|---|---|---|",
+        "| loop-agent governance is valid | `bash scripts/check-repo.sh` | `bash scripts/ci-governance.sh` |",
+        "| target project tests are valid | `bash scripts/ci-tests.sh` | project-specific full test/build command |",
+        "| full local delivery is valid | `bash scripts/ci.sh` | add deployment/package-specific checks when relevant |",
+        "| docs/governance changed | `bash scripts/check-repo.sh` | `loop-agent docs audit` plus `bash scripts/ci-governance.sh` |",
+        "| model writer changed files | `git status --short` + relevant verification | `bash scripts/ci.sh` |",
+        "",
+        "## Generated Commands",
+        "",
+        "```bash",
+        "bash scripts/check-engineering-structure.sh",
+        "bash scripts/check-doc-index.sh",
+        "bash scripts/check-doc-links.sh",
+        "bash scripts/check-active-plan-status.sh",
+        "bash scripts/check-exec-plan-index-sync.sh",
+        "bash scripts/check-harness-runtime-clean.sh",
+        "bash scripts/check-architecture-boundaries.sh",
+        "bash scripts/check-skill-entry.sh",
+        "bash scripts/check-repo.sh",
+        "bash scripts/ci-governance.sh",
+        "bash scripts/ci-tests.sh",
+        "bash scripts/ci.sh",
+        "```",
+        "",
+        "## Project-Specific Verification",
+        "",
+        "`scripts/ci-tests.sh` detects common entrypoints such as package.json, Makefile, go.mod, Cargo.toml, Python test metadata, Maven, Gradle, and .NET projects. If no safe command is detected, it exits successfully with a clear message so the initialization model can adapt this file to the target project.",
+        "",
+        "After initialization, update this matrix with the target project's actual quick, standard, and full verification commands.",
+        "",
+    ].join("\n");
+}
+function buildTargetLoopAgentHarness(input) {
+    return [
+        "# loop-agent Harness",
+        "",
+        `This target project, \`${input.projectName}\`, is initialized to use loop-agent for governed task execution.`,
+        "",
+        "## Runtime Layout",
+        "",
+        "- `.harness/tasks/` stores task state and source materials.",
+        "- `.harness/dag-runs/` stores DAG run facts.",
+        "- `.harness/runs/` stores one-shot executor facts.",
+        "- `docs/` stores durable governance, plans, reports, progress, and decisions.",
+        "- `skills/` stores repo-local skill instructions; the CLI can fall back to bundled skills when needed.",
+        "",
+        "## Default Workflow",
+        "",
+        "Use `loop-agent new-task`, `loop-agent dag run-task`, `loop-agent dag validate`, and `loop-agent run-dag` for non-trivial implementation work.",
+        "",
+        "## Script Matrix",
+        "",
+        "`scripts/check-repo.sh` verifies loop-agent governance. `scripts/ci-tests.sh` handles target project verification through conservative language/toolchain detection and should be adapted after reading the project.",
+        "Copy or project only stack-agnostic governance scripts. For project-specific verification, packaging, release, or maintenance commands, generate the target-project version from templates plus the target repository's actual files instead of copying loop-agent's own TypeScript-specific scripts.",
+        "",
+    ].join("\n");
+}
+function buildGeneratedCoreDoc(input) {
+    switch (input.doc) {
+        case "README.md":
+            return buildTargetDocsReadme({ projectName: input.projectName });
+        case "architecture/runtime-boundaries.md":
+            return buildTargetRuntimeBoundaries({ projectName: input.projectName });
+        case "development-principles.md":
+            return buildTargetDevelopmentPrinciples({ projectName: input.projectName });
+        case "feature-workflow.md":
+            return buildTargetFeatureWorkflow({ governanceRoot: input.governanceRoot });
+        case "verification-matrix.md":
+            return buildTargetVerificationMatrix();
+        case "loop-agent-harness.md":
+            return buildTargetLoopAgentHarness({ projectName: input.projectName });
+        default:
+            return undefined;
+    }
+}
+function buildGovernanceDirectoryReadme(input) {
+    const title = input.dir
+        .split("/")
+        .map((part) => part.replace(/-/g, " "))
+        .join(" / ");
+    return [
+        `# ${title}`,
+        "",
+        `This directory stores ${input.projectName} governance artifacts generated during real work.`,
+        "",
+        "初始化只创建目录契约，不复制 loop-agent 源仓库的历史任务正文或历史索引。目标项目中的具体 plan、progress、report、decision 应由后续任务按真实执行事实生成。",
+        "",
+    ].join("\n");
+}
+export function buildInitInstructions(input) {
+    const projectName = input.projectName ?? path.basename(path.resolve(input.repoRoot));
+    const governanceRoot = input.governanceRoot ?? "docs";
+    return [
+        "# loop-agent Initialization Instructions",
+        "",
+        `Initialize the target repository as a loop-agent harness project: \`${input.repoRoot}\`.`,
+        "",
+        "## Confirm With User",
+        "",
+        `- Project name: default \`${projectName}\`.`,
+        `- Governance root: default \`${governanceRoot}\`.`,
+        "- Confirm provider/model. Defaults may be used, but the target project may need a different provider/model matrix.",
+        "- Default: merge existing AGENTS.md, harness.json, and docs/ instead of overwriting user content.",
+        "",
+        "## Apply Defaults",
+        "",
+        "- Use the current loop-agent harness.json as the default template, but write target project name plus `adapter: \"loop-agent\"`.",
+        `- ${DAG_HARD_GATE_TRIGGER}`,
+        "- Generate the target project's loop-agent script matrix from templates: structure check, docs index/link checks, active plan status, exec-plan index sync, harness runtime cleanliness, architecture boundaries, skill entry integrity, governance CI, project-test CI, and full CI.",
+        "- Copy or project only stack-agnostic governance scripts. For project-specific verification, packaging, release, or maintenance commands, generate the target-project version from templates plus the target repository's actual files instead of copying loop-agent's own TypeScript-specific scripts.",
+        "- Do not assume the target project is TypeScript, Node.js, frontend, backend, or any other specific stack.",
+        "- `scripts/ci-tests.sh` must be language-neutral: detect common project verification entrypoints conservatively, run only commands that exist, and clearly report when project-specific verification needs model/user adaptation.",
+        "- Default verification entries: quick `bash scripts/check-repo.sh`, standard `bash scripts/ci-governance.sh`, full `bash scripts/ci.sh`.",
+        `- Generate target-project versions of \`${governanceRoot}/README.md\`, \`${governanceRoot}/development-principles.md\`, \`${governanceRoot}/architecture/runtime-boundaries.md\`, \`${governanceRoot}/feature-workflow.md\`, \`${governanceRoot}/verification-matrix.md\`, and \`${governanceRoot}/loop-agent-harness.md\`; copy only generic methodology/template material as-is.`,
+        "- After deterministic initialization, inspect README/config/build files (for example package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gradle files, Makefile, .sln/.csproj, or project-specific scripts) and adapt `scripts/ci-tests.sh` plus the verification matrix to the real project.",
+        "- Enrich the root `README.md`: keep the deterministic project title and the loop-agent managed block intact, and fill the human-authored sections (项目概览, 技术栈与目录结构, 开发与验证) from the target project's actual files. The root README must serve both as a human-first project entry and as an agent work entry; replace the initialization-model supplement comments when the project files provide the information.",
+        "- Populate `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.",
+        "- 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.",
+        "- Create `.harness/` runtime directories but do not create historical run facts.",
+        "",
+        "## Automatic Workflow For Model-Executed Init",
+        "",
+        "When a model/agent is asked to initialize a target project, treat initialization as one automated workflow. Do not run deterministic init and then wait for another user turn to fill project-specific content.",
+        "",
+        "1. Resolve only the inputs that are genuinely unsafe to assume: provider/model, non-default governance root, overwrite policy, credentials, cost, or deployment side effects.",
+        "2. Run deterministic init with merge defaults.",
+        "3. Continue immediately into project inspection and adaptation.",
+        "4. Finish by running the init health checks and quick verification.",
+        "",
+        "If provider/model is not specified and the existing/default harness values are usable, proceed with those defaults and record the assumption in the handoff. Ask the user only when the choice affects credentials, cost, availability, or an explicitly requested model backend.",
+        "",
+        "## Required Model Adaptation",
+        "",
+        "Do not stop after the deterministic `loop-agent init` command. When these instructions are executed by an agent/model, the initialization is not complete until the target project has been inspected and the generated scaffolding has been adapted.",
+        "",
+        "Required post-init steps:",
+        "",
+        "1. Read the target project's existing README, manifest/build/config files, and top-level source/module directories.",
+        "2. Replace the root README's `初始化模型补充` comments when the information can be inferred from files. At minimum, fill project overview, technology stack/directory structure, and development/verification commands.",
+        "3. Update `docs/verification-matrix.md` with the target project's actual quick, standard, and full verification commands.",
+        "4. Update `scripts/ci-tests.sh` only when the conservative generated detector is insufficient for the target project.",
+        "5. Run `loop-agent init doctor`, `loop-agent inspect`, `loop-agent docs audit`, and the quick verification command.",
+        "",
+        "Completion rule: if target files provide enough evidence, the final README should not leave generic `初始化模型补充` comments in the sections that can be filled. If a section truly cannot be inferred, write a short explicit note such as `尚未从仓库文件中识别到 ...` instead of asking the user to fill it later.",
+        "",
+        "## Suggested Command",
+        "",
+        "```bash",
+        `loop-agent init --repo-root ${input.repoRoot} --profile full --merge`,
+        "loop-agent init doctor --repo-root <target>",
+        "loop-agent inspect --repo-root <target>",
+        "loop-agent docs audit --repo-root <target>",
+        "```",
+    ].join("\n");
+}
+export async function initializeLoopAgentProject(options) {
+    const repoRoot = path.resolve(options.repoRoot);
+    const projectName = options.projectName ?? path.basename(repoRoot);
+    const governanceRoot = options.governanceRoot ?? "docs";
+    const profile = options.profile ?? "full";
+    const merge = options.merge ?? true;
+    const written = [];
+    const skipped = [];
+    const assetRoot = await findPackageRoot();
+    const template = await readJsonIfExists(path.join(assetRoot, "harness.json"));
+    const existingHarness = await readJsonIfExists(path.join(repoRoot, "harness.json"));
+    await mkdir(repoRoot, { recursive: true });
+    const readmePath = path.join(repoRoot, "README.md");
+    const existingReadme = (await exists(readmePath)) ? await readFile(readmePath, "utf-8") : undefined;
+    const readmeContent = existingReadme
+        ? mergeManagedBlock(existingReadme, buildManagedReadmeBlock({ projectName, governanceRoot }))
+        : buildTargetReadme({ projectName, governanceRoot });
+    await writeText({
+        repoRoot,
+        relativePath: "README.md",
+        content: readmeContent,
+        merge: true,
+        written,
+        skipped,
+    });
+    const harness = buildHarness({
+        existing: existingHarness,
+        template,
+        projectName,
+        governanceRoot,
+        provider: options.provider,
+        model: options.model,
+    });
+    await writeText({
+        repoRoot,
+        relativePath: "harness.json",
+        content: `${JSON.stringify(harness, null, 2)}\n`,
+        merge: true,
+        written,
+        skipped,
+    });
+    const agentsPath = path.join(repoRoot, "AGENTS.md");
+    const existingAgents = (await exists(agentsPath)) ? await readFile(agentsPath, "utf-8") : `# AGENTS.md\n`;
+    await writeText({
+        repoRoot,
+        relativePath: "AGENTS.md",
+        content: mergeManagedBlock(existingAgents, buildManagedAgentsBlock({ projectName, governanceRoot })),
+        merge: true,
+        written,
+        skipped,
+    });
+    for (const doc of CORE_DOC_FILES) {
+        const generated = buildGeneratedCoreDoc({ doc, projectName, governanceRoot });
+        if (generated) {
+            await writeTextIfMissing({
+                repoRoot,
+                relativePath: path.join(governanceRoot, doc),
+                content: generated,
+                merge,
+                written,
+                skipped,
+            });
+            continue;
+        }
+        await copyFileIfMissing({
+            assetRoot,
+            repoRoot,
+            sourceRelativePath: path.join("docs", doc),
+            targetRelativePath: path.join(governanceRoot, doc),
+            merge,
+            written,
+            skipped,
+        });
+    }
+    for (const dir of GOVERNANCE_README_DIRS) {
+        await writeTextIfMissing({
+            repoRoot,
+            relativePath: path.join(governanceRoot, dir, "README.md"),
+            content: buildGovernanceDirectoryReadme({ dir, projectName }),
+            merge,
+            written,
+            skipped,
+        });
+    }
+    await copyDirMerge({
+        assetRoot,
+        repoRoot,
+        sourceRelativePath: "docs/templates",
+        targetRelativePath: path.join(governanceRoot, "templates"),
+        written,
+    });
+    if (profile === "full") {
+        await copyDirMerge({
+            assetRoot,
+            repoRoot,
+            sourceRelativePath: "skills",
+            targetRelativePath: "skills",
+            written,
+        });
+    }
+    else {
+        skipped.push("skills/");
+    }
+    skipped.push("examples/");
+    for (const [relativePath, content] of Object.entries(buildInitScriptFiles(governanceRoot))) {
+        await writeText({
+            repoRoot,
+            relativePath,
+            content,
+            merge: true,
+            written,
+            skipped,
+        });
+    }
+    await ensureHarnessDirs(repoRoot, written);
+    await writeCompatPrompts({ repoRoot, merge, written, skipped });
+    return { repoRoot, projectName, governanceRoot, profile, written, skipped };
+}
+export async function runInitDoctor(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const checks = [];
+    const add = (name, ok, message) => checks.push({ name, ok, message });
+    try {
+        const manifest = await loadHarnessManifest(repoRoot);
+        add("harness.json", manifest.adapter === "loop-agent" || manifest.project === "loop-agent", `project=${manifest.project}`);
+        add("governance root", await exists(path.join(repoRoot, manifest.governanceRoot, "README.md")), manifest.governanceRoot);
+    }
+    catch (error) {
+        add("harness.json", false, error instanceof Error ? error.message : String(error));
+    }
+    const agents = path.join(repoRoot, "AGENTS.md");
+    add("AGENTS.md loop-agent block", (await exists(agents)) && (await readFile(agents, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
+    const readme = path.join(repoRoot, "README.md");
+    add("README loop-agent block", (await exists(readme)) && (await readFile(readme, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
+    add("repo-local skills", await exists(path.join(repoRoot, "skills", "loop-agent", "SKILL.md")), "skills/loop-agent/SKILL.md");
+    const requiredScripts = Object.keys(INIT_SCRIPT_FILES);
+    const missingScripts = [];
+    for (const script of requiredScripts) {
+        if (!(await exists(path.join(repoRoot, script))))
+            missingScripts.push(script);
+    }
+    add("script matrix", missingScripts.length === 0, missingScripts.length === 0 ? `${requiredScripts.length} scripts` : `missing: ${missingScripts.join(", ")}`);
+    add("compat prompts", await exists(path.join(repoRoot, ".harness", "prompts", "analyze.md")) && await exists(path.join(repoRoot, ".harness", "prompts", "plan.md")), ".harness/prompts/analyze.md");
+    add("harness runtime dirs", await exists(path.join(repoRoot, ".harness", "dag-runs", "active")), ".harness/dag-runs/active");
+    return {
+        ok: checks.every((check) => check.ok),
+        repoRoot,
+        checks,
+    };
+}
+function parseInitArgs(repoRoot, args) {
+    let subcommand;
+    let projectName;
+    let governanceRoot = "docs";
+    let profile = "full";
+    let merge = true;
+    let provider;
+    let model;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if ((arg === "instructions" || arg === "doctor") && !subcommand) {
+            subcommand = arg;
+            continue;
+        }
+        if (arg === "--project-name")
+            projectName = args[++i];
+        else if (arg.startsWith("--project-name="))
+            projectName = arg.slice("--project-name=".length);
+        else if (arg === "--governance-root")
+            governanceRoot = args[++i] ?? governanceRoot;
+        else if (arg.startsWith("--governance-root="))
+            governanceRoot = arg.slice("--governance-root=".length);
+        else if (arg === "--profile")
+            profile = args[++i] ?? profile;
+        else if (arg.startsWith("--profile="))
+            profile = arg.slice("--profile=".length);
+        else if (arg === "--merge")
+            merge = true;
+        else if (arg === "--no-merge")
+            merge = false;
+        else if (arg === "--provider")
+            provider = args[++i];
+        else if (arg.startsWith("--provider="))
+            provider = arg.slice("--provider=".length);
+        else if (arg === "--model")
+            model = args[++i];
+        else if (arg.startsWith("--model="))
+            model = arg.slice("--model=".length);
+        else if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-"))
+            throw new Error(`unknown init flag: ${arg}`);
+        else
+            throw new Error(`unexpected init argument: ${arg}`);
+    }
+    if (profile !== "full" && profile !== "minimal")
+        throw new Error("init --profile must be full or minimal");
+    return { repoRoot, projectName, governanceRoot, profile, merge, provider, model, subcommand, json };
+}
+export async function runInit(repoRoot, rawArgs) {
+    const parsed = parseInitArgs(repoRoot, rawArgs);
+    if (parsed.subcommand === "instructions") {
+        console.log(buildInitInstructions(parsed));
+        return;
+    }
+    if (parsed.subcommand === "doctor") {
+        const report = await runInitDoctor({ repoRoot: parsed.repoRoot });
+        console.log(JSON.stringify(report, null, 2));
+        if (!report.ok)
+            process.exitCode = 1;
+        return;
+    }
+    const result = await initializeLoopAgentProject(parsed);
+    console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitResult(result));
+}
+function formatInitResult(result) {
+    return [
+        `Initialized loop-agent harness at ${result.repoRoot}`,
+        `project: ${result.projectName}`,
+        `governanceRoot: ${result.governanceRoot}`,
+        `profile: ${result.profile}`,
+        `written: ${result.written.length}`,
+        `skipped: ${result.skipped.length}`,
+        "next: loop-agent init doctor --repo-root <target>",
+        "model-executed init: continue automatically by inspecting the target project, adapting README.md, docs/verification-matrix.md, and scripts/ci-tests.sh when needed, then run inspect/docs audit/quick verification.",
+    ].join("\n");
+}
+export async function listInitializedFiles(repoRoot) {
+    const files = [];
+    async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else
+                files.push(repoRelative(repoRoot, full));
+        }
+    }
+    await access(repoRoot);
+    await walk(repoRoot);
+    return files.sort();
+}