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

package/AGENTS.md

@@ -0,0 +1,114 @@
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+如果仓库根目录存在 `.codegraph/`，在理解或定位代码前优先使用 CodeGraph，再考虑 rg/fd 或手动读文件。
+<!-- CODEGRAPH_END -->
+
+# AGENTS.md
+
+本仓库采用“人类掌舵，智能体执行”的工程方式。目标不是一次性写完所有代码，而是在一个可持续演进、可交接、可验证的系统里做小步增量。
+
+`AGENTS.md` 是地图，不是百科。顶层只保留开工协议、会话协议与文档导航；长期知识、方法论、决策、计划、报告和模板应进入 `docs/`。
+
+## 默认立场
+
+- 仓库是记录系统：决策、契约、计划、测试、报告优先落到仓库，而不是停留在聊天里。
+- 一次只推进一个清晰工作块；主会话按 Orient → Select → Contract → Implement → Verify → Handoff 治理，runtime 真实流程以 `src/workflows/` 为准。
+- 先验证基线，再叠加改动；完成定义必须可验证，不能靠删测试、降标准或模糊描述制造“完成”。
+- Do not consider backward compatibility. Ignore legacy code/libraries.
+- 搜索先于实现；受治理 Agent runtime 只有 Pi（`implement-pi` / `repair-pi`）；`cursor-prompt` 仅为显式手工 one-shot sidecar。
+- DAG 标准路径：Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
+- 机器校验契约真源：`docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/`、`scripts/check-*.sh`；本文件只指路。
+- 本仓库既是源项目也是 init 默认模板；新增能力必须判断 npm 内置 vs `loop-agent init` 投影。
+- 委托写入前必须结构化 `task.json.allowedPaths` / `forbiddenPaths`，并审查 DAG writer `writeSet`。
+- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本用 Git Bash / 兼容 Bash。
+- 用 loop-agent 迭代本仓库时，控制器必须来自已发布 npm 包（记录实际版本）；启动后不要中途升级；不要用工作区 `npm link` / `npm run dev` 控制可能改 CLI/runtime/package 的任务。
+- 反复出现的约束固化为文档、脚本、检查、测试或模板；禁止占位实现（除非 contract 标明脚手架）。
+- 非微小实现：`exec-plan` 不能替代 Agent DAG；除非用户要求 one-shot 或计划记录 escape hatch，否则改实现前完成 `task advance`（PRD + 结构化路径边界）与 writeSet gate 审查。长跑 DAG 启动一律走 `prepareDagExecution → runDag → operationId` 由 Console operation 后台持有；**禁止**在前台 Bash 直接执行 `task advance --approve-gate`（会阻塞会话且超时杀 runner）、禁止把长跑命令管道到 `tail`/`head`、禁止自行拼接 `nohup`/`Start-Process`/`start`。
+- **实现默认 DAG，主会话不直接改代码**：只要是实现/修复/行为或展示语义变更（含 observe 文案映射、runtime status、schema、executor、CLI 等），主会话只做 Orient / 建 task / dry-run / validate / writeSet 审查 / 执行与监视 DAG，**不得**自己改 `src/**`、`test/**` 等交付面。仅当用户**明确授权**主会话直接处理（例如「直接改」「主会话改」「one-shot」「不用 DAG」）时，才允许主会话写入；授权后仍须记录边界、allowedPaths 与验证证据。纯答疑、读代码、查状态、提交/推送已有 diff、或用户点名的文档微调（如本文件规则）不在此限。
+- 不要自行引入外部 SDD/spec-first 等强制平行治理树；以本文件与 `docs/` 为准（ADR 0006）。
+
+## 开始顺序
+
+改文件前必须先完成：
+
+1. `pwd` → 读 `README.md`、`harness.json`、`docs/README.md`；有 `CONTEXT.md` 则读术语表。
+2. 实现类工作继续读：`docs/governance/development-principles.md`、`docs/governance/feature-workflow.md`、`docs/governance/verification-matrix.md`。
+3. 涉及命令/executor/init/skills/发布包/治理检查时继续读：`docs/architecture/runtime-boundaries.md`、`docs/runtime/loop-agent-harness.md`。
+4. 涉及测试纪律/验证声明/调试时继续读：`docs/governance/harness-methodology-*.md`。
+5. 查看最近提交、相关 plan/progress/report；`git status --short --branch`；跑最小基线验证。
+6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
+7. 看板/observe → `agent-worker console`（默认 repo=当前目录、port=8790；listen 成功后默认打开系统浏览器，`--no-open` 禁止）（`/inspect/` 只读）；`observe serve` 已下线（`OBSERVE_SERVE_REMOVED` + exit 2）；`observe snapshot` 仍可用。
+8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
+9. 涉及版本发布、npm 渠道、release 分支、GitHub Actions 发布链或 dist-tag → 先读 `docs/operations/version-and-release-management.md`。
+
+## 会话协议
+
+1. Orient → 2. Select（一块）→ 3. Contract → 4. Implement → 5. Verify → 6. Converge Docs → 7. Handoff。
+
+这不是 DAG 节点序列。实现默认 Agent DAG；主 agent 拆任务、写 contract、结构化路径、审查 DAG/writeSet/profile/shell verification，**不自行 implement**。主会话 one-shot 仅在用户明确授权时可用，并记录边界与验证证据；「看起来很小」或「只是展示文案」不构成授权——若改动触及 runtime/status/映射语义，仍走 DAG。
+
+启动 loop-agent DAG 流程后，主 agent 应自主推进到整个流程结束，不要中途请求无谓的人工确认（如“要我现在执行 DAG 吗？”）。只要 dry-run / validate / writeSet 审查通过就应直接执行并跑完全部 ranks；遇到真问题（契约不一致、writeSet 越界、verify 失败且超出 maxFixLoops、用户明显未授权的高风险动作）才停。即便 profile 是 supervised/reviewed，也不默认在 review-gate 主动停下等人——控制器会在需要人工 approve 时自行提示，主 agent 的职责是推动流程跑完。
+
+DAG 执行期间主 agent 必须持续监督直到 run 结束（FINISHED / FAILED / 需要 approve），不能查一次就停下等用户。监督优先用 Console 的 `operationWait` 长轮询（只读、model-callable、无 Human Gate）：退避 60 → 90 → 120 → 180 秒，状态变化后重置 60 秒，疑似 stall 用 30–60 秒复查；heartbeat 不是 meaningful progress（默认 `operationWait` 已过滤），不得因 heartbeat 重置退避。无法走 Console 工具时（如本机 CLI 直接操作）才退回 bash 轮询：看 `state.json` 的 `runner.heartbeatAt` 是否持续刷新 + `session-events.jsonl` 是否在增长 + `dag doctor` 的 `liveness` 字段，不要只用 `tasklist /FI "PID eq X"` 这类过滤语法在 Git Bash 下会误报 DEAD，从而错判一个正常工作的 run 为 orphaned。遇到疑似 stall 先按 `docs/runtime/agent-dag-runner.md` 查 `lastMeaningfulProgressAt` / provider 活动，有真实进展就继续等，绝不盲目 supersede。持续监视过程中，主 agent 可在合适节点（例如 rank/节点状态变化、进入 verify/closeout、出现 stall 嫌疑或需要 approve 时）向用户做简短进度汇报（当前节点、状态、是否有风险），避免长时间静默；汇报是告知，不是请求确认，不得因此停下流程。
+
+DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件（包括 AGENTS.md、docs、根配置等）。bounded writer 节点的 write guard 用「节点运行期间的工作区 diff」作为越界证据，不区分改动来自 pi 还是主会话——主会话在 pi 节点跑的时候改了 writeSet 外文件，会让 write guard 把账算到 pi 头上、判节点 ERROR、下游 cascade skip。需要改文档/约束时，要么在 DAG 启动前改完，要么等 run 结束后改；务必与 DAG 写入节点在时间上互斥。排查任务路由问题时优先用 `resolveTaskDagTemplateSelection` / `classifyTaskDemand` 等纯函数探针或 `--output` 指定临时路径，不要反复 `dag execute --dry-run` / 无必要的 lifecycle 探测。dry-run 不执行节点；若确需预演，检查命令返回的 `.harness/dag-runs/dry-run/<runId>/` `runDir`，它不进入 active overview，也不能作为 `dag resume` 目标。优先用纯函数探针或 `task status`。
+
+失败恢复与契约漂移：run 失败后先 `dag report` / `dag doctor`，优先 `dag rerun --from-node`（含 unsafe shell 节点的子图会判不 eligible，属预期；此时改契约后同 task 重新 advance / `dag rerun-task`）。直接编辑 `source/需求.md` / `执行约束.md` 会使契约进入 `externally-modified`，后续 advance 会拒用新内容（DIRTY_SOURCE / hash 不一致）；合法收编用 `task contract adopt --task <id> --expected-revision <n> --expected-observed-hash <hash> --request-id <id> --request-payload-sha256 <sha>`（hash 从 `task status --json` 的 `contract.observedCanonicalHash` 取），或改 PRD 后重新 importPrd 走完整重投影；禁止手改 `lifecycle.json` / `.transactions/` 绕过。
+
+## 项目地图
+
+- `CONTEXT.md`：术语表
+- `src/`：运行时；`test/`：Vitest；`bin/loop-agent.js`：CLI
+- `skills/`：源仓库/npm 内置 skills；目标项目只生成 `.agents/skills/`
+- `.harness/`：运行态（tasks/dag-runs/runs 等；init 会 gitignore 运行事实，保留 prompts 与占位）
+- `docs/`：治理；`website/`：用户文档站；`scripts/`：检查与 CI
+- 版本发布链（next / release-x.y / latest 手工 promote）：`docs/operations/version-and-release-management.md`
+
+## 工作规则（增量约束）
+
+- 保留无关用户改动；优先沿用现有 helper/目录边界。
+- 长期决策写入 `docs/`；面向用户变更更新 `CHANGELOG.md`（结果导向中文）。
+- init/投影变更必须同步目标项目生成物与 package assets；init evolution 按 `docs/init-surface.manifest.json` 分级。
+- CLI/skill entry/runtime boundary/发布包变更同步 catalog、脚本与测试。
+- 明确的前端页面/UI/组件/交互实现需求必须设置 `taskKind: "frontend-implementation"`（不是 `--profile`），不得保留默认 `standard`；浏览器/UI 自动化测试继续使用 `taskKind: "frontend-test"`。
+- 没有新鲜验证证据时不声明完成；新债写入 plan/progress/report。
+
+## 验证
+
+权威源：`docs/governance/verification-matrix.md`。
+
+默认节奏：编辑中只跑矩阵「最低验证」（typecheck + 定向 Vitest）；`git commit` 的 `pre-commit` 只做 `check-repo`；`git push` 的 `pre-push` 经 `node scripts/pre-push-verify.mjs` 在 receipt 命中时复用、miss 时跑 full `bash scripts/ci.sh`（全量 typecheck + `npm test`）。每个 clone 安装一次 hooks：`bash scripts/install-git-hooks.sh`。
+
+连续 source→target 交付遵循**单一最终树全量验证**：同一 Git tree、相同环境与命令合同在 receipt TTL 内只选一个本地 full authority（有效 receipt / target pre-push / 可选 `npm run verify:tree`），不按分支名策略化，也不机械双跑 full CI。细节见 verification-matrix 与 branch-merge-guideline。
+
+常用：
+
+```bash
+# 编辑中
+npm run typecheck
+npx vitest run <相关测试路径>
+
+# 可选：提前验证当前 clean HEAD 并写 receipt（随后同 tree push 可复用）
+npm run verify:tree
+
+# push / 交付前（或依赖 pre-push；receipt miss 时安全回退 full）
+bash scripts/ci.sh
+npm run build
+node bin/loop-agent.js --help
+```
+
+- 改 `src/**` 后必须先 `npm run build` 再用 `bin/loop-agent.js`：bin 内置 stale-dist 守卫（src 比 dist 新即硬失败，`--ignore-stale-dist` 逃生），`--version` 会显示构建 git SHA，发布/自测前用它确认跑的是目标改动。
+
+文档站变更：`npm run docs:build`。init / architecture / skill entry / pack 定向验证见 verification-matrix。
+
+## 交接
+
+记录：改了什么、为什么、验证命令与结果、契约/文档/测试影响、剩余风险、后续工作。
+
+## 禁止事项
+
+- 未读相关文档就大改；一次混合无关重构/新功能/文档大迁移。
+- 把对话约束当长期知识；缺验证宣称完成；假设系统没有某能力（先搜索）。
+- stub/假数据通路替代交付；把本机绝对路径写入仓库级 AGENTS/README/模板/发布包。
+- 只更新本仓库体验而遗漏目标项目 init 体验。