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

package/dist/workflows/loop/events.js

@@ -0,0 +1,26 @@
+import { readFile } from "node:fs/promises";
+import { appendLoopEventLine } from "../../infrastructure/harness/loop-store.js";
+import { getLoopPaths } from "./paths.js";
+export async function appendLoopEvent(repoRoot, taskId, input) {
+    const now = new Date().toISOString();
+    const entry = {
+        schemaVersion: 1,
+        id: `${now}-${input.type}`,
+        type: input.type,
+        taskId,
+        round: input.round ?? 0,
+        message: input.message,
+        refs: input.refs ?? [],
+        recordedAt: now,
+    };
+    await appendLoopEventLine(repoRoot, taskId, entry);
+    return entry;
+}
+export async function readLoopEvents(repoRoot, taskId) {
+    const raw = await readFile(getLoopPaths(repoRoot, taskId).eventsPath, "utf-8").catch(() => "");
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}

package/dist/workflows/loop/hash.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { listTaskSourceFiles } from "../../task/runtime.js";
+export function sha256Text(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+export async function hashFileIfPresent(filePath) {
+    try {
+        return sha256Text(await readFile(filePath, "utf-8"));
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return "";
+        }
+        throw error;
+    }
+}
+export async function hashTaskSource(repoRoot, taskId) {
+    const files = await listTaskSourceFiles(repoRoot, taskId);
+    const sourceDir = path.join(repoRoot, ".harness", "tasks", taskId, "source");
+    const chunks = [];
+    for (const file of files.sort()) {
+        const abs = path.isAbsolute(file) ? file : path.join(sourceDir, file);
+        const relative = path.relative(sourceDir, abs);
+        chunks.push(`${relative}\n${await readFile(abs, "utf-8")}`);
+    }
+    return sha256Text(chunks.join("\n--- source file ---\n"));
+}

package/dist/workflows/loop/index.js

@@ -0,0 +1,8 @@
+export { getLoopPaths } from "./paths.js";
+export { initializeLoop, loadLoopState, refreshLoopState, saveLoopState, } from "./state.js";
+export { appendLoopRound, readLoopRounds } from "./rounds.js";
+export { rewriteLoopContext } from "./context.js";
+export { appendLoopSignal, drainLoopSignals, parseLoopSignalType, pendingLoopSignals, readLoopSignals, } from "./signals.js";
+export { appendLoopEvent, readLoopEvents } from "./events.js";
+export { generateLoopCloseout } from "./closeout.js";
+export { buildLoopPiReviewPrompt, decideNextLoopAutoAction, resolveLoopShellVerifyCommands, runLoopAuto, runLoopDagAction, runLoopPiReview, runLoopShellVerification, runLoopWorkflowGateSignalAction, runLoopWorkflowAction, } from "./actions.js";

package/dist/workflows/loop/paths.js

@@ -0,0 +1,17 @@
+import path from "node:path";
+import { getTaskDir } from "../../task/runtime.js";
+export function getLoopPaths(repoRoot, taskId) {
+    const loopDir = path.join(getTaskDir(repoRoot, taskId), "loop");
+    return {
+        loopDir,
+        objectivePath: path.join(loopDir, "objective.md"),
+        contextPath: path.join(loopDir, "context.md"),
+        statePath: path.join(loopDir, "state.json"),
+        roundsPath: path.join(loopDir, "rounds.jsonl"),
+        signalsPath: path.join(loopDir, "signals.jsonl"),
+        closeoutPath: path.join(loopDir, "closeout.md"),
+        eventsPath: path.join(loopDir, "events.jsonl"),
+        verificationDir: path.join(loopDir, "verification"),
+        reviewDir: path.join(loopDir, "reviews"),
+    };
+}

package/dist/workflows/loop/policy/auto-policy.js

@@ -0,0 +1,112 @@
+import { pendingLoopSignals } from "../signals.js";
+export function decideNextLoopAutoAction(state, signals = [], options = {}) {
+    const pendingSignals = pendingLoopSignals(signals);
+    const urgent = pendingSignals.find((signal) => signal.urgent);
+    if (urgent) {
+        return {
+            action: "pause",
+            reason: `urgent ${urgent.type} signal: ${urgent.message}`,
+            decision: "pause",
+        };
+    }
+    const scopeChanged = pendingSignals.find((signal) => signal.type === "scope_changed");
+    if (scopeChanged) {
+        return {
+            action: "pause",
+            reason: `scope changed signal requires objective/context review: ${scopeChanged.message}`,
+            decision: "pause",
+        };
+    }
+    const reviewSignal = pendingSignals.find((signal) => signal.type === "review_feedback" || signal.type === "human_followup");
+    if (reviewSignal) {
+        return {
+            action: "pi-review",
+            reason: `${reviewSignal.type} signal requires read-only review: ${reviewSignal.message}`,
+            decision: "continue",
+        };
+    }
+    if (state.round >= state.maxRounds) {
+        return {
+            action: "blocked",
+            reason: `loop maxRounds reached (${state.round}/${state.maxRounds})`,
+            decision: "blocked",
+        };
+    }
+    if (state.failureStreak.category && state.failureStreak.count >= 2) {
+        return {
+            action: "blocked",
+            reason: `repeated failure category ${state.failureStreak.category} x${state.failureStreak.count}`,
+            decision: "blocked",
+        };
+    }
+    if (state.freshness.sourceStale) {
+        return {
+            action: "pause",
+            reason: "task source changed; rebuild or review action prompt before continuing",
+            decision: "pause",
+        };
+    }
+    if (state.lastAction === "shell-verify") {
+        return {
+            action: "pi-review",
+            reason: "shell verification already ran; request read-only review before next implementation decision",
+            decision: "continue",
+        };
+    }
+    if (state.lastAction === "pi-review") {
+        if (options.latestPiReview?.recommendedAction === "implement_fix") {
+            const policy = options.loopAutoExecutionPolicy ?? "off";
+            const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
+            const approved = Boolean(options.approvalGranted) || Boolean(approvalSignal);
+            if (policy === "off") {
+                return {
+                    action: "dag",
+                    dagMode: "review",
+                    reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=off (DAG review only)`,
+                    decision: "continue",
+                };
+            }
+            if (policy === "approval-required" && !approved) {
+                return {
+                    action: "pause",
+                    reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=approval-required without approval`,
+                    decision: "pause",
+                };
+            }
+            return {
+                action: "dag",
+                dagMode: "execute",
+                reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=${policy}`,
+                decision: "continue",
+            };
+        }
+        return {
+            action: "dag",
+            dagMode: "review",
+            reason: "read-only review produced next action; generate a governed DAG review packet",
+            decision: "continue",
+        };
+    }
+    const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
+    if (approvalSignal) {
+        return {
+            action: "dag",
+            dagMode: "review",
+            reason: `approval signal received; generate next governed DAG packet: ${approvalSignal.message}`,
+            decision: "continue",
+        };
+    }
+    if (state.lastAction === "dag") {
+        return {
+            action: "shell-verify",
+            reason: "dag round must be followed by deterministic shell verification",
+            decision: "continue",
+        };
+    }
+    return {
+        action: "dag",
+        dagMode: "review",
+        reason: "default to DAG governed review packet for the next bounded round",
+        decision: "continue",
+    };
+}

package/dist/workflows/loop/policy/path-patterns.js

@@ -0,0 +1,13 @@
+import { pathMatchesPattern } from "../../../shared/git-progress.js";
+export function normalizePattern(pattern) {
+    return pattern.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/\*\*$/, "");
+}
+export function patternsOverlap(allowed, forbidden) {
+    const a = normalizePattern(allowed);
+    const f = normalizePattern(forbidden);
+    return (a === f ||
+        a.startsWith(`${f}/`) ||
+        f.startsWith(`${a}/`) ||
+        pathMatchesPattern(a, forbidden) ||
+        pathMatchesPattern(f, allowed));
+}

package/dist/workflows/loop/rounds.js

@@ -0,0 +1,81 @@
+import { readFile } from "node:fs/promises";
+import { writeLoopRounds } from "../../infrastructure/harness/loop-store.js";
+import { getLoopPaths } from "./paths.js";
+import { refreshLoopState } from "./state.js";
+import { appendLoopEvent } from "./events.js";
+function statusForDecision(decision) {
+    if (decision === "continue")
+        return "running";
+    if (decision === "pause")
+        return "paused";
+    return decision;
+}
+export async function readLoopRounds(repoRoot, taskId) {
+    const raw = await readFile(getLoopPaths(repoRoot, taskId).roundsPath, "utf-8");
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export async function appendLoopRound(repoRoot, taskId, input) {
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const entry = {
+        schemaVersion: 1,
+        round: rounds.length + 1,
+        recordedAt: new Date().toISOString(),
+        action: input.action,
+        refs: input.refs ?? [],
+        result: input.result,
+        verification: input.verification ?? "",
+        lesson: input.lesson,
+        next: input.next,
+        decision: input.decision,
+        failureCategory: input.failureCategory ?? "",
+        completedCriteria: input.completedCriteria ?? [],
+    };
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "round_start",
+        round: entry.round,
+        message: `recording round ${entry.round} action ${entry.action}`,
+        refs: entry.refs,
+    });
+    await writeLoopRounds(repoRoot, taskId, [...rounds, entry]);
+    const previousState = await refreshLoopState(repoRoot, taskId, {
+        status: statusForDecision(entry.decision),
+        round: entry.round,
+        lastDecision: entry.decision,
+        lastAction: entry.action,
+        lastExecutorRef: entry.refs[0] ?? "",
+        openFrontier: entry.next ? [entry.next] : [],
+        completedCriteria: entry.completedCriteria,
+    });
+    if (entry.failureCategory) {
+        await refreshLoopState(repoRoot, taskId, {
+            failureStreak: {
+                category: entry.failureCategory,
+                count: previousState.failureStreak.category === entry.failureCategory
+                    ? previousState.failureStreak.count + 1
+                    : 1,
+            },
+        });
+    }
+    else if (previousState.failureStreak.category) {
+        await refreshLoopState(repoRoot, taskId, {
+            failureStreak: { category: "", count: 0 },
+        });
+    }
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "action_finish",
+        round: entry.round,
+        message: `${entry.action}: ${entry.result}`,
+        refs: entry.refs,
+    });
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "decision",
+        round: entry.round,
+        message: `decision=${entry.decision}; next=${entry.next}`,
+        refs: entry.refs,
+    });
+    return entry;
+}

package/dist/workflows/loop/signals.js

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+import { writeLoopSignals as persistLoopSignals } from "../../infrastructure/harness/loop-store.js";
+import { getLoopPaths } from "./paths.js";
+import { LOOP_SIGNAL_TYPES, } from "./types.js";
+export function parseLoopSignalType(value) {
+    if (LOOP_SIGNAL_TYPES.includes(value)) {
+        return value;
+    }
+    throw new Error(`invalid loop signal type: ${value} (expected ${LOOP_SIGNAL_TYPES.join("|")})`);
+}
+export async function readLoopSignals(repoRoot, taskId) {
+    const raw = await readFile(getLoopPaths(repoRoot, taskId).signalsPath, "utf-8").catch(() => "");
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export async function appendLoopSignal(repoRoot, taskId, input) {
+    const signals = await readLoopSignals(repoRoot, taskId);
+    const now = new Date().toISOString();
+    const entry = {
+        schemaVersion: 1,
+        id: `${now}-${signals.length + 1}`,
+        type: input.type,
+        message: input.message.trim(),
+        urgent: input.urgent ?? false,
+        refs: input.refs ?? [],
+        createdAt: now,
+        drainedAt: "",
+    };
+    if (!entry.message) {
+        throw new Error("loop signal message cannot be empty");
+    }
+    await persistLoopSignals(repoRoot, taskId, [...signals, entry]);
+    return entry;
+}
+export function pendingLoopSignals(signals) {
+    return signals.filter((signal) => !signal.drainedAt);
+}
+export async function drainLoopSignals(repoRoot, taskId, ids) {
+    if (ids.length === 0)
+        return readLoopSignals(repoRoot, taskId);
+    const idSet = new Set(ids);
+    const now = new Date().toISOString();
+    const signals = await readLoopSignals(repoRoot, taskId);
+    const drained = signals.map((signal) => idSet.has(signal.id) && !signal.drainedAt
+        ? { ...signal, drainedAt: now }
+        : signal);
+    await persistLoopSignals(repoRoot, taskId, drained);
+    return drained;
+}

package/dist/workflows/loop/state.js

@@ -0,0 +1,116 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureLoopDir, writeLoopContext, writeLoopObjective, writeLoopRounds, writeLoopSignals, writeLoopEvents, writeLoopState, } from "../../infrastructure/harness/loop-store.js";
+import { getTaskDir } from "../../task/runtime.js";
+import { hashFileIfPresent, hashTaskSource } from "./hash.js";
+import { getLoopPaths } from "./paths.js";
+import { defaultContext, defaultObjective } from "./templates.js";
+import { appendLoopEvent } from "./events.js";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+function rel(repoRoot, filePath) {
+    return path.relative(repoRoot, filePath);
+}
+export async function buildLoopState(repoRoot, taskId, paths = getLoopPaths(repoRoot, taskId), previous) {
+    const now = new Date().toISOString();
+    const objectiveHash = await hashFileIfPresent(paths.objectivePath);
+    const contextHash = await hashFileIfPresent(paths.contextPath);
+    const sourceHash = await hashTaskSource(repoRoot, taskId);
+    const previousSourceHash = previous?.sourceHash ?? sourceHash;
+    return {
+        schemaVersion: 1,
+        taskId,
+        status: previous?.status ?? "draft",
+        round: previous?.round ?? 0,
+        maxRounds: previous?.maxRounds ?? 8,
+        objectivePath: rel(repoRoot, paths.objectivePath),
+        contextPath: rel(repoRoot, paths.contextPath),
+        roundsPath: rel(repoRoot, paths.roundsPath),
+        objectiveHash,
+        contextHash,
+        sourceHash,
+        freshness: {
+            objectiveHash,
+            contextHash,
+            sourceHash,
+            sourceStale: sourceHash !== previousSourceHash,
+            lastCheckedAt: now,
+        },
+        lastDecision: previous?.lastDecision ?? "init",
+        lastAction: previous?.lastAction ?? "init",
+        lastExecutorRef: previous?.lastExecutorRef ?? "",
+        openFrontier: previous?.openFrontier ?? ["choose the next bounded action"],
+        completedCriteria: previous?.completedCriteria ?? [],
+        failureStreak: previous?.failureStreak ?? { category: "", count: 0 },
+        createdAt: previous?.createdAt ?? now,
+        updatedAt: now,
+    };
+}
+export async function saveLoopState(repoRoot, taskId, state) {
+    await writeLoopState(repoRoot, taskId, state);
+}
+export async function loadLoopState(repoRoot, taskId) {
+    const paths = getLoopPaths(repoRoot, taskId);
+    const raw = await readFile(paths.statePath, "utf-8");
+    return JSON.parse(raw);
+}
+export async function refreshLoopState(repoRoot, taskId, patch = {}) {
+    const previous = await loadLoopState(repoRoot, taskId);
+    const state = await buildLoopState(repoRoot, taskId, undefined, {
+        ...previous,
+        ...patch,
+    });
+    await saveLoopState(repoRoot, taskId, state);
+    return state;
+}
+export async function initializeLoop(repoRoot, taskId, options = {}) {
+    const taskDir = getTaskDir(repoRoot, taskId);
+    if (!(await exists(taskDir))) {
+        throw new Error(`task does not exist: ${taskId}`);
+    }
+    const paths = getLoopPaths(repoRoot, taskId);
+    const stateExists = await exists(paths.statePath);
+    if (stateExists && !options.recover) {
+        throw new Error(`loop already initialized for task: ${taskId}`);
+    }
+    await ensureLoopDir(repoRoot, taskId);
+    if (!(await exists(paths.objectivePath))) {
+        await writeLoopObjective(repoRoot, taskId, defaultObjective(taskId));
+    }
+    if (!(await exists(paths.contextPath))) {
+        await writeLoopContext(repoRoot, taskId, defaultContext());
+    }
+    if (!(await exists(paths.roundsPath))) {
+        await writeLoopRounds(repoRoot, taskId, []);
+    }
+    if (!(await exists(paths.signalsPath))) {
+        await writeLoopSignals(repoRoot, taskId, []);
+    }
+    if (!(await exists(paths.eventsPath))) {
+        await writeLoopEvents(repoRoot, taskId, []);
+    }
+    const previous = stateExists ? await loadLoopState(repoRoot, taskId) : undefined;
+    const state = await buildLoopState(repoRoot, taskId, paths, {
+        ...previous,
+        maxRounds: options.maxRounds ?? previous?.maxRounds ?? 8,
+    });
+    await saveLoopState(repoRoot, taskId, state);
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "loop_start",
+        message: stateExists ? "loop recovered" : "loop initialized",
+    });
+    return { created: !stateExists, paths, state };
+}

package/dist/workflows/loop/templates.js

@@ -0,0 +1,54 @@
+export function defaultObjective(taskId) {
+    return [
+        "# Objective",
+        "",
+        "## Goal",
+        `- Complete the long-running task ${taskId}.`,
+        "",
+        "## Success Criteria",
+        "- Loop success criteria are copied or summarized from source/需求.md.",
+        "- Completion requires current shell verification evidence.",
+        "",
+        "## Scope",
+        "- In: work described by the task source materials.",
+        "- Out: unrelated repository changes.",
+        "",
+        "## Constraints",
+        "- Allowed paths: see source/执行约束.md.",
+        "- Forbidden paths: see source/执行约束.md.",
+        "- Verification: see source/执行约束.md.",
+        "",
+        "## Completion Policy",
+        "- Required evidence: shell verification output and referenced executor facts.",
+        "- Required review: as specified by the task source or DAG gates.",
+        "- Stop conditions: complete, paused, blocked, or max rounds reached.",
+        "",
+    ].join("\n");
+}
+export function defaultContext() {
+    return [
+        "# Loop Context",
+        "",
+        "## Current State",
+        "- Completed: none recorded yet.",
+        "- Open frontier: initialize loop and choose the next bounded action.",
+        "- Current hypothesis: storage state must be established before executor integration.",
+        "",
+        "## Verified Facts",
+        "- No loop rounds have been recorded yet.",
+        "",
+        "## Last Round Lessons",
+        "- What worked: none yet.",
+        "- What failed: none yet.",
+        "- Avoid next round: do not treat chat history as durable state.",
+        "",
+        "## Next Suggested Action",
+        "- Action: record a bounded round with canonical evidence refs.",
+        "- Why: loop context should be derived from durable facts.",
+        "- Expected evidence: rounds.jsonl entry and rewritten context.md.",
+        "",
+        "## Risk Notes",
+        "- Completion still requires deterministic verification.",
+        "",
+    ].join("\n");
+}

package/dist/workflows/loop/types.js

@@ -0,0 +1,28 @@
+export const LOOP_STATUSES = [
+    "draft",
+    "running",
+    "paused",
+    "blocked",
+    "complete",
+];
+export const LOOP_DECISIONS = [
+    "continue",
+    "pause",
+    "blocked",
+    "complete",
+];
+export const LOOP_EVENT_TYPES = [
+    "loop_start",
+    "round_start",
+    "action_start",
+    "action_finish",
+    "context_rewrite",
+    "decision",
+    "loop_finish",
+];
+export const LOOP_SIGNAL_TYPES = [
+    "human_followup",
+    "approval",
+    "scope_changed",
+    "review_feedback",
+];

package/docs/README.md

@@ -0,0 +1,82 @@
+# Start Here：文档怎么读
+
+`docs/` 是 loop-agent 源仓的治理文档根目录。新读者不需要先浏览所有文件，先按任务选择入口，再由目录 README 或 `docs/document-catalog.json` 判断文档身份。
+
+**维护日：2026-08-16** — 对齐 `@tea-agent/loop-agent@0.35.3`。版本事实以根 `CHANGELOG.md` 与 `package.json` 为准；能力短摘要见 `reports/current-capability-summary.md`。
+
+## 我现在要做什么？
+
+| 任务 | 先读 | 继续读 |
+| --- | --- | --- |
+| 理解当前能力与边界 | `reports/current-capability-summary.md` | `architecture/README.md`、`website/docs/overview/roadmap.md` |
+| 开始一个受治理功能变更 | `governance/feature-workflow.md` | `governance/verification-matrix.md`、`templates/exec-plan.md` |
+| 跑或恢复 Agent DAG | `runtime/agent-dag-runner.md` | `runtime/agent-dag-recovery-playbook.md`、`runtime/loop-agent-harness.md`；Operator Chat Phase 1/P0 的 meaningful wait 与安全 terminal summary 已实现，Phase 2/3 仍见 active design |
+| 判断架构边界 | `architecture/README.md` | `architecture/runtime-boundaries.md` |
+| 查设计输入而非实现证明 | `design/README.md` | 对应设计文档；视觉参考见 `design/visual-references/README.md`，归档设计见 `design/archive/README.md` |
+| 接手进行中任务 | `exec-plans/active/README.md` | 对应 active plan，再读 `progress/README.md` |
+| 查已完成依据 | `exec-plans/completed/README.md` | `reports/README.md` 与对应报告分类 |
+| 初始化或升级目标项目 | `init-surface.manifest.json` | `templates/README.md`、`reports/init-evolution/README.md` |
+| 管理文档 freshness | `governance/document-review-policy.md` | `document-catalog.json`、`scripts/check-doc-governance.mjs` |
+
+## 按问题找专题
+
+| 你要解决的问题 | 文档 |
+| --- | --- |
+| 先确认仓库的基本工程原则 | `governance/development-principles.md` |
+| 选择 taskKind、治理 profile 和 Agent DAG 路径 | `governance/feature-workflow.md` |
+| 选择快速、标准或完整验证命令 | `governance/verification-matrix.md` |
+| 理解 CLI、runtime 和初始化能力边界 | `runtime/loop-agent-harness.md` |
+| 运行 DAG、查看报告或处理失败 | `runtime/agent-dag-runner.md`、`runtime/agent-dag-recovery-playbook.md`；Operator Chat P0 closeout 见 `reports/feature/2026-08-14-operator-chat-dag-recovery-p0.md` |
+| 按 TDD、验证和调试纪律推进修复 | `governance/harness-methodology-tdd.md`、`governance/harness-methodology-verification.md`、`governance/harness-methodology-debugging.md` |
+| 执行真实 backend-test provider 验证 | `runtime/backend-test-live-campaign.md` |
+| 判断单任务 loop-agent Production Readiness | `operations/production-readiness.md` |
+| 判断 agent-worker Feature/Attempt Production Readiness v1 | `operations/agent-worker-production-readiness.md`、`templates/agent-worker-production-readiness-checklist.md` |
+| 分阶段推进 agent-worker Production Readiness v1 | `exec-plans/active/2026-08-09-agent-worker-production-readiness-v1-program.md`、`exec-plans/active/README.md` |
+| 合并分支并留下 source-SHA 报告 | `operations/branch-merge-guideline.md` |
+| 使用仓库内 GitHub 协作方式 | `operations/github-collaboration.md` |
+| 发布版本、npm 渠道、release 分支或手工 latest promotion | `operations/version-and-release-management.md` |
+| 版本发布、npm 渠道、release 分支与 latest promote | `operations/version-and-release-management.md` |
+| 排查本机开发环境问题 | `operations/local-development-environment.md` |
+| 使用明确的 Cursor one-shot sidecar | `runtime/cursor-prompt-sidecar.md` |
+| 审查 npm 包与目标项目初始化文件面 | `init-surface.manifest.json` |
+| 判断文档何时需要重新复核 | `governance/document-review-policy.md` |
+
+## 文档身份规则
+
+- **当前优先检索（current-first）**：判断当前能力、状态或下一步时，先读 `CHANGELOG.md`、`reports/current-capability-summary.md`、`exec-plans/active/README.md` 和 `document-catalog.json`；命中 `design/archive/`、`exec-plans/completed/`、`reports/` 或 `reports/handoffs/` 时，必须先按 catalog 中该历史证据根的 `currentFirst` 跳转当前入口，再回看历史证据的时间点和范围。
+- **当前真源**：`document-catalog.json` 中 `status` 为 `当前有效` 且带唯一 `topic` 的条目为该主题的唯一权威入口；同一 `topic` 只能有一个当前真源。
+- **复核 freshness**：catalog 声明 `reviewPolicy.updateRule=verified-content-only`；每个登记文档必须引用有效 `reviewTier`。只有逐项对照 `sourceOfTruth` 并留下证据后才能更新 `lastReviewed`，tier/owner/category/格式修改不得刷新日期；具体规则见 `governance/document-review-policy.md`。
+- **已被替代**：`status` 为 `已被替代` 的条目必须通过 `supersededBy` 指向 catalog 中另一个不同 `path`；目标必须与原条目 `topic` 相同，且状态只能是 `当前有效` 或 `正在推进`。读取时不要继续引用原条目作为事实，应跳转到 `supersededBy` 指向的当前入口或正在推进合同。
+- **内容有误，已撤回**：`status` 为 `内容有误，已撤回` 的条目必须提供非空 `withdrawalReason`。这是撤回声明，不是替代关系；读取时只能保留其撤回原因和历史审计价值，不应把原文当作可信事实。
+- **关系字段**：`supersededBy` 与 `withdrawalReason` 互斥，且不得出现在其他状态条目上。
+- **当前契约 / 手册**：`governance/`、`runtime/`、`operations/` 与 `architecture/`，分别回答怎么推进、怎么运行、怎么维护和边界是什么。
+- **设计输入**：`design/active/`，用于说明仍会影响后续决策的方案、路线和背景；除非有代码、CHANGELOG 或 completed plan 旁证，否则不是已实现证明。
+- **视觉参考**：`design/visual-references/`，用于长期保留产品、交互或界面方向的视觉参考；它不表达实现状态，也不等同于 active 设计输入或 archive 历史证据。
+- **进行中合同**：`exec-plans/active/`。
+- **已完成证据**：`exec-plans/completed/`、`reports/`。
+- **当前交接**：`progress/`，只回答下一会话怎么接；结束后的交接归入 `reports/handoffs/`。
+- **历史资料**：`design/archive/`，保留历史或已被替代的设计上下文，不代表当前能力。
+- **模板库**：`templates/`，随 npm 包与 full init surface 投影。
+
+机器检查：`node scripts/check-doc-governance.mjs --repo-root .`。该检查枚举磁盘文件，不依赖“共 N 篇”这类手工计数。
+
+## 目录职责
+
+| 目录 | 职责 |
+| --- | --- |
+| `governance/` | 开发原则、功能工作流、验证矩阵与工程方法 |
+| `runtime/` | loop-agent harness、DAG 运行/恢复和专用 runtime 手册 |
+| `operations/` | 本地环境、分支合并、GitHub 协作与生产就绪操作 |
+| `architecture/` | 当前架构入口、runtime 边界、DAG 执行与状态事实 |
+| `decisions/` | ADR；决策是否仍有效以 ADR 正文和后续 ADR 为准 |
+| `design/active/` | 仍会影响后续决策的设计输入、路线与契约 |
+| `design/visual-references/` | 长期视觉参考，不表达实现状态 |
+| `design/archive/` | 历史设计和已被实现/替代的阶段性设计 |
+| `exec-plans/active/` | 仍需推进或明确保持 open 的任务合同 |
+| `exec-plans/completed/` | 已完成任务合同归档 |
+| `progress/` | 仍需下一次会话接手的当前 handoff 入口 |
+| `reports/` | 验证、dogfood、merge、init evolution 与历史 handoff 证据 |
+| `skills/` | repo-local skill registry |
+| `templates/` | 可复用任务、报告、DAG 和 init 模板 |
+
+站上使用者文档在 `../website/docs/`；源仓治理事实以本目录、`AGENTS.md`、`harness.json`、`CHANGELOG.md` 和检查脚本为准。