@tea-agent/loop-agent 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 更新日志
 
+## [0.15.0] - 2026-07-18
+
+### 重点更新
+
+- 新增 Pull Request 的只读 AI 自动审查，自动检查代码缺陷与测试缺口并更新评论
+- 引入内部测试版本夜间自动发布工作流，主干达标后自动更新版本并发布
+- 收紧 npm 发布包范围，仅保留 init 与 runtime 必需的文档和脚本
+- 修复预发布版本被误发布至 latest 的风险，发布门禁改为按版本号状态严格限制
+
+### 新增
+
+- 新增 Pull Request 的只读 AI 自动审查：在创建、重新打开、转为 ready 或更新提交时检查 bug、测试缺口、runtime boundary 等，并更新单条 PR 评论
+- 新增内部测试版本夜间自动发布：达到提交门槛并通过发布检查后，自动更新版本、生成中文说明并发布 GitHub Release 与 npm
+- 新增面向内部研发人员的轻量 GitHub 协作指南和简短 Pull Request 模板，统一采用短分支与 Squash Merge 的最小协作闭环
+- 新增 `.editorconfig` 与 `.gitattributes`，统一常见文本文件的 UTF-8、LF、缩进和文件末尾换行约定
+
+### 改进
+
+- 收紧 npm 发布包中的 `docs/` 范围：只保留 init/runtime 所需的治理文档、architecture、skills 与 templates
+- 收紧 npm 发布包中的 `scripts/`：只保留知识库实际调用的脚本，不再打包源仓治理检查与 `.sh` 包装
+- 前端实现 DAG 的 `frontendMock.policy=auto` 不再因为目标项目缺少 Mock 能力而阻塞，无确认能力时自动跳过并保留真实请求默认路径
+- 文档基线全面校准至 0.14.0，修复了多处的文档索引遗漏与旧路径引用
+
+### 修复
+
+- 修复私有仓库 AI PR 审查因通过网页 `*.diff` 地址拉取差异导致 404 的问题，改为经 GitHub API 获取 diff
+- 修复预发布版本误发布到 `latest` 的问题：发布门禁改为按版本号的 prerelease 状态限制 dist-tag，beta prerelease 仅允许 `beta` tag
+- 修复网站更新日志（Changelog）的版本插入位置错误：新版本段落不再错误地插入到读者摘要之前，保持页面结构正常
+- 修复网站更新日志中残留的 `[Unreleased]` 块未随版本发布移除的问题
+
 ## [0.14.0] - 2026-07-18
 
 ### 重点更新
@@ -29,8 +59,17 @@
 
 ## [Unreleased]
 
+- 新增 Pull Request 的只读 AI 自动审查：在创建、重新打开、转为 ready 或更新提交时检查 bug、测试缺口、runtime boundary、command registry、初始化投影与文档收敛，并更新单条 PR 评论；Fork PR 无模型密钥时安全跳过。
+- 修复私有仓库 AI PR 审查因通过网页 `*.diff` 地址拉取差异导致 404 的问题，改为经 GitHub API 获取 diff。
+- 新增 `.editorconfig` 与 `.gitattributes`，统一常见文本文件的 UTF-8、LF、缩进和文件末尾换行约定，减少不同 IDE 与操作系统产生的无意义差异；本轮不引入 Git hooks 或格式化依赖。
+- 新增面向内部研发人员的轻量 GitHub 协作指南和简短 Pull Request 模板，统一采用短分支、CI 与 Squash Merge 的最小协作闭环，不改变现有 Agent DAG 和发布流程。
+- 收紧 npm 发布包中的 `docs/` 范围：只保留 init/runtime 所需的治理文档、architecture、skills 与 templates；源仓库专属说明与 progress/report/exec-plan 等目录契约不再打进包内。
+- 收紧 npm 发布包中的 `scripts/`：只保留 `loop-agent knowledge` 实际调用的知识库脚本；源仓治理检查与 `.sh` 薄包装不再打进包内。
 - 新增内部测试版本夜间自动发布：达到提交门槛并通过发布检查后，自动更新版本、生成中文说明并发布 GitHub Release 与 npm；手动运行默认只做 dry-run。
 - 发布说明支持 OpenAI-compatible 模型，模型不可用时自动使用保守摘要。
+- 修复 PR #34 发布风险：合并到 main 后包版本被错误提升为 `0.14.1-beta.0`，现已恢复为 `0.14.0`；发布门禁由仅按 frontend 分支判断改为按版本号的 prerelease 状态限制 dist-tag（beta prerelease 只允许 `beta` tag，使用 `latest`/空/默认 tag 时 fail-closed；非 beta prerelease 如 alpha/rc 全局拒绝），避免在 main 上执行默认 `npm publish` 时把 prerelease 误发布到 `latest`。
+- `frontend` 分支继续保留本地 npm beta 发布门禁，并在合入 main 0.14.0 后把测试版本线调整为 `0.14.1-beta.0`，避免误推正式版本或 `latest`。
+- 前端实现 DAG 的 `frontendMock.policy=auto` 不再因为目标项目缺少 Mock 能力而阻塞；无确认 Mock 能力时跳过 Mock、保留真实请求默认路径，并在未真实联调时记录 `Frontend status: locally-validated` 与 `Real integration: pending`。
 
 ## [0.13.0] - 2026-07-18
 
@@ -47,21 +86,21 @@
 
 ## [0.12.0] - 2026-07-16
 
-- **只读 Pi 节点安全重试**：opt-in `retryPolicy`（network / rate-limit / unavailable / timeout）；writer / shell 等声明策略会校验失败。见 [Agent DAG](./guides/agent-dag.md)。
+- **只读 Pi 节点安全重试**：opt-in `retryPolicy`（network / rate-limit / unavailable / timeout）；writer / shell 等声明策略会校验失败。见 [Agent DAG](./website/docs/guides/agent-dag.md)。
 - **`taskKind: backend-test`**：需求分析 → 功能用例 → pytest → 复盘。
 - **知识同步与业务图谱 MVP**：`taskKind: knowledge-sync`（须 `featureId`）/ `knowledge-graph-bootstrap`；`loop-agent knowledge query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare`（`knowledge curate` 仍只负责 repair guidance 提案）。
 - **init surface 全量跟踪**：`check-update` / `update --apply-safe` 覆盖包内全部 `docs/templates/**` 与 `skills/**` 到目标目录的投影。
-- 详见根 `CHANGELOG.md [0.12.0]`；站上 [当前规划](./overview/roadmap.md) 与 [功能导览](./overview/feature-map.md)。
+- 详见根 `CHANGELOG.md [0.12.0]`；站上 [当前规划](./website/docs/overview/roadmap.md) 与 [功能导览](./website/docs/overview/feature-map.md)。
 
 ## [0.11.0] - 2026-07-15
 
-- **Observe 本地运营面 R1–R5**：资源池 / Task 下钻、Batch·Run 三层事实、Feature 决策详情与对象关系条、有界事件历史、ES modules 前端模块化；`observe serve` keep-alive / SSE keepalive，可选非 loopback 绑定（默认仍 `127.0.0.1`）。见 [Observe](./guides/observe-ui.md)。
+- **Observe 本地运营面 R1–R5**：资源池 / Task 下钻、Batch·Run 三层事实、Feature 决策详情与对象关系条、有界事件历史、ES modules 前端模块化；`observe serve` keep-alive / SSE keepalive，可选非 loopback 绑定（默认仍 `127.0.0.1`）。见 [Observe](./website/docs/guides/observe-ui.md)。
 - **版本化自举**：controller identity / package fingerprint / expected gate、run-owned skill snapshot、deterministic `self-host:canary`、`skills/agent-worker` 及目标镜像；dogfood Feature `F-2026-004`。
 - **DagSpec v3 + repair 契约**：新 DAG 携带 `runtimeContract`；supervised `repairNodeId`；run-owned controller identity pin。
-- **`plan create` / `plan complete` / `plan check`**：exec-plan 生命周期与 DAG 前置索引校验。见 [CLI 参考](./reference/cli.md)。
-- **CLI 自更新提醒**：交互式成功命令后检查 npm 新版本；`LOOP_AGENT_DISABLE_UPDATE_CHECK=1` 可关。见 [安装](./quick-start/installation.md)。
+- **`plan create` / `plan complete` / `plan check`**：exec-plan 生命周期与 DAG 前置索引校验。见 [CLI 参考](./website/docs/reference/cli.md)。
+- **CLI 自更新提醒**：交互式成功命令后检查 npm 新版本；`LOOP_AGENT_DISABLE_UPDATE_CHECK=1` 可关。见 [安装](./website/docs/quick-start/installation.md)。
 - **init 布局收敛**：目标项目默认 `ai_workspace/loop-agent/` + `.agents/skills/`；`init update --apply-safe` 可安全迁移旧根 `docs/` / `skills/`。
-- **文档站 IA**：intro 概念地图与 30 分钟路径；[功能导览](./overview/feature-map.md)、[架构导读](./overview/architecture.md)、[当前规划](./overview/roadmap.md)；Markdown 断链构建失败；`skills/loop-agent/references/docs-converge.md` 固化文档收敛检查表。
+- **文档站 IA**：intro 概念地图与 30 分钟路径；[功能导览](./website/docs/overview/feature-map.md)、[架构导读](./website/docs/overview/architecture.md)、[当前规划](./website/docs/overview/roadmap.md)；Markdown 断链构建失败；`skills/loop-agent/references/docs-converge.md` 固化文档收敛检查表。
 - 可选 repo-local SDD skill 嵌入；前端 DAG skill 契约与验证命令安全解析。
 
 ## [0.10.0] - 2026-07-12
@@ -73,17 +112,17 @@
 
 ## [0.9.0] - 2026-07-12
 
-- Observe 看板重设计为暖白运行控制台：统一信息层级、依赖图 + 节点表、右侧节点检查器、安全 Markdown；本机资源 guardrail。见 [Observe](./guides/observe-ui.md)。
+- Observe 看板重设计为暖白运行控制台：统一信息层级、依赖图 + 节点表、右侧节点检查器、安全 Markdown；本机资源 guardrail。见 [Observe](./website/docs/guides/observe-ui.md)。
 
 ## [0.8.0] 及更早
 
-- 0.8.0：[CLI 参考](./reference/cli.md) 补充 `task validate-feature`、`task retry`、`scripts/worker-nightly.sh` + GitHub Actions、`capabilities: [interactive-ui]`，Task Pool 唯一根 `.harness/task-pool/`。
+- 0.8.0：[CLI 参考](./website/docs/reference/cli.md) 补充 `task validate-feature`、`task retry`、`scripts/worker-nightly.sh` + GitHub Actions、`capabilities: [interactive-ui]`，Task Pool 唯一根 `.harness/task-pool/`。
 - 0.7.5：Observe 新增 DAG 依赖图可视化。
 - 0.7.0：interactive-ui writer-only HIGH 路由与 UI 交付契约。
 - 更早条目见根目录 `CHANGELOG.md`。
 
 ## 文档站点同步说明
 
-- 站上 guide / reference 与根 `docs/` 双树边界见 [架构导读 · 双树边界](./overview/architecture.md#双树边界)。
+- 站上 guide / reference 与根 `docs/` 双树边界见 [架构导读 · 双树边界](./website/docs/overview/architecture.md#双树边界)。
 - 活能力短摘要：[`docs/reports/current-capability-summary.md`](https://github.com/tea-agent/loop-agent/blob/main/docs/reports/current-capability-summary.md)。
 - 冻结基线长文：[`docs/reports/2026-07-02-repository-analysis.md`](https://github.com/tea-agent/loop-agent/blob/main/docs/reports/2026-07-02-repository-analysis.md)（2026-07-16 再采样对齐 0.12.0 + 主干 Unreleased；勿当第二 CHANGELOG）。

package/README.md

@@ -45,7 +45,7 @@ loop-agent inspect
 
 ## 自动发布
 
-仓库通过 GitHub Actions 定时检查 `main`，达到提交门槛并通过发布检查后，自动更新版本、生成 Release 说明并发布 GitHub Release 与 npm。手动触发默认只执行 dry-run，不产生远端发布副作用；具体配置、版本规则和恢复步骤见 [`docs/exec-plans/active/2026-07-18-nightly-auto-release.md`](docs/exec-plans/active/2026-07-18-nightly-auto-release.md)。
+仓库通过 GitHub Actions 定时检查 `main`，达到提交门槛并通过发布检查后，自动更新版本、生成 Release 说明并发布 GitHub Release 与 npm。手动触发默认只执行 dry-run，不产生远端发布副作用；具体配置、版本规则和恢复步骤见 [`docs/exec-plans/completed/2026-07-18-nightly-auto-release.md`](docs/exec-plans/completed/2026-07-18-nightly-auto-release.md)。
 
 ## 初始化目标项目
 
@@ -105,7 +105,7 @@ loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --st
 loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 ```
 
-`dag run-task` 会先尊重显式声明的专用 `taskKind`。对于默认 `standard` 任务，它会根据任务标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类；只有高置信的前端实现需求才会自动进入前端专用节点链。只读 `frontend-mock-assess-pi` 在计划前读取 Mock/API/schema 证据，并通过确定性 contract gate 选择原生 Mock、浏览器拦截、请求适配层、`not-needed` 或明确阻塞；它只能使用 DAG 生成时已固化的验证入口。可选 `task.json.frontendMock` 可设置 `auto|required|disabled`、既有服务目录和专项验证命令；不安全或不完整的显式 required 合同不会生成 writer。真实请求始终是默认路径，唯一写节点仍是 `frontend-implement-pi`。自动分类不会覆盖显式 profile、`workflowPolicy` 或 supervised quality gate。后端、混合或证据不足的需求继续使用通用模板，也不会自动进入 `backend-test`。Mock 验证只证明前端状态与交互；未实际请求后端时，收尾保留 `Frontend status: mock-validated`、`Real integration: pending`，并给出 `<task-id>-real-api-integration-verify`。该复验任务不会自动创建或执行，需要在后端就绪后显式运行。
+`dag run-task` 会先尊重显式声明的专用 `taskKind`。对于默认 `standard` 任务，它会根据任务标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类；只有高置信的前端实现需求才会自动进入前端专用节点链。只读 `frontend-mock-assess-pi` 在计划前读取 Mock/API/schema 证据，并通过确定性 contract gate 选择原生 Mock、浏览器拦截、请求适配层、`not-needed` 或明确阻塞；它只能使用 DAG 生成时已固化的验证入口。可选 `task.json.frontendMock` 可设置 `auto|required|disabled`、既有服务目录和专项验证命令；默认 `auto` 下没有已确认 Mock 能力时会跳过 Mock 继续前端实现，并保留真实联调缺口，不会因为缺 Mock 本身阻塞。不安全或不完整的显式 required 合同仍不会生成 writer。真实请求始终是默认路径，唯一写节点仍是 `frontend-implement-pi`。自动分类不会覆盖显式 profile、`workflowPolicy` 或 supervised quality gate。后端、混合或证据不足的需求继续使用通用模板，也不会自动进入 `backend-test`。Mock 验证只证明前端状态与交互；未实际请求后端时，收尾保留 `Real integration: pending`，并给出 `<task-id>-real-api-integration-verify`。该复验任务不会自动创建或执行，需要在后端就绪后显式运行。
 
 测试结论写回与业务知识图谱（结构化 Git，非 RAG）：
 
@@ -281,6 +281,7 @@ npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <
 | 路径 | 用途 |
 |---|---|
 | `AGENTS.md` | 本仓库的 agent 开工协议、会话协议和长期工作规则 |
+| `docs/github-collaboration.md` | 内部贡献者的轻量 GitHub 协作指南：短分支、PR、CI 与 Squash Merge |
 | `harness.json` | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 |
 | `docs/README.md` | 治理文档索引 |
 | `docs/verification-matrix.md` | 不同变更类型对应的验证命令 |
@@ -293,6 +294,8 @@ npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <
 
 ## 本仓库开发
 
+内部贡献代码时，先阅读 [`docs/github-collaboration.md`](docs/github-collaboration.md)。当前采用轻量协作方式：一个小工作块使用一个短分支，通过简短 Pull Request、CI 和同事确认后，默认 Squash Merge 到 `main`。
+
 本地源码开发：
 
 ```bash
@@ -318,9 +321,9 @@ Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash
 
 ## 发布包内容
 
-发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与可选的 `agent-worker` operator skill）、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
+发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与可选的 `agent-worker` operator skill）、必要的治理文档（`docs/README.md`、三份 methodology、显式列出的 `docs/architecture/*.md`）、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、知识库运行脚本（`scripts/kb-*.mjs` 与 `kb-bootstrap-init-skeleton.sh`）、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
 
-`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
+`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/`、`docs/design/` 的任务正文与目录 README 不随包发布；`loop-agent init` 会在目标项目生成空目录契约，具体 plan/progress/report/decision 由后续真实任务写入。源仓库专属说明（如 agent-dag playbook、sidecar 说明）也不再打进 npm 包。
 
 DAG skill 指令优先从用户配置目录和目标项目 `.agents/skills/` 解析；目标项目未提供本地 skill 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或根 `skills/` 目录才可获得默认 DAG 能力。
 
@@ -336,4 +339,20 @@ node bin/loop-agent.js --help
 npm pack --dry-run
 ```
 
+`npm publish` 时会通过 `prepublishOnly` 依次执行：
+
+1. `node scripts/check-npm-publish-policy.mjs` — 发布策略门禁
+2. `npm run typecheck`
+3. `npm test`
+4. `npm run build`
+
+### frontend 分支发布限制
+
+在 `frontend` 分支执行 `npm publish` 时，必须同时满足：
+
+- `package.json` 版本为合法的 SemVer **beta** 预发布版本（例如 `0.13.0-beta.1`）
+- 必须显式指定 `--tag beta`（即 `npm publish --tag beta`）
+
+任一条件不满足时，`prepublishOnly` 会在上传 npm registry 前失败并给出中文错误提示。其他分支不受此限制。
+
 发布入口 `bin/loop-agent.js` 只加载 `dist/cli.js`；`npm run dev -- <args>` 只用于源码开发和定位问题。

package/dist/workflows/dag/init-hybrid.js

@@ -555,7 +555,7 @@ export function hasApiDependency(sources) {
  * |---|---|---|---|
  * | 无 | 任意 | auto | not-required |
  * | 有 | present | auto | required |
- * | 有 | present/absent/ambiguous | auto | required (strategy chooses a safe mechanism) |
+ * | 有 | absent/ambiguous | auto | not-required (skip Mock, preserve integration gap) |
  * | 任意 | present | required | required |
  * | 任意 | absent/ambiguous | required | blocked |
  * | 任意 | 任意 | disabled | not-required (if spec allows) else blocked |
@@ -587,12 +587,12 @@ export function resolveFrontendMockMode(capability, taskConfig, hasApiDep) {
     if (!hasApiDep) {
         return "not-required";
     }
-    // In auto mode, capability discovery is evidence for the strategy node, not
-    // a final mechanism decision. Projects without a native Mock service may use
-    // an existing browser interception harness or a reversible request adapter.
-    // The deterministic strategy gate blocks before the writer when none can be
-    // verified by the DAG's frozen static/behavior entrypoints.
-    return "required";
+    // In auto mode, frontend Mock is optional. Only require Mock-backed strategy
+    // assessment when a native project Mock capability is actually present.
+    // Projects without confirmed Mock support continue through the normal
+    // frontend writer and must preserve the real integration gap instead of
+    // inventing a temporary Mock framework or blocking solely for missing Mock.
+    return capability.status === "present" ? "required" : "not-required";
 }
 function mapTaskComplexity(complexity) {
     if (complexity === "small")
@@ -1322,6 +1322,12 @@ export function buildStandardHybridDagFromTask(sources) {
     return spec;
 }
 function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, fixedVerificationContext, readOnlyPaths, forbiddenPaths) {
+    const configuredPolicy = sources.taskConfig.frontendMock?.policy ?? "auto";
+    const mockMode = sources.frontendMockMode ?? "not-required";
+    const capabilityStatus = sources.frontendMockCapability?.status;
+    const autoMaySkipMissingMock = configuredPolicy === "auto" &&
+        mockMode === "not-required" &&
+        (capabilityStatus === "absent" || capabilityStatus === "ambiguous");
     return {
         id: "frontend-mock-assess-pi",
         depends_on: ["frontend-contract-pi", "frontend-scout-pi"],
@@ -1337,7 +1343,9 @@ function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, f
             "Perform read-only Mock assessment and select one safe frontend data strategy.",
             "The first non-empty line must be exactly one of: MOCK_STRATEGY: native, MOCK_STRATEGY: browser-intercept, MOCK_STRATEGY: request-adapter, MOCK_STRATEGY: not-needed, or MOCK_STRATEGY: blocked.",
             "Prefer an existing native Mock facility. Use browser-intercept only with an existing browser/e2e harness. When no Mock exists but the API layer is writable, use request-adapter by adding a minimal reversible adapter/DI seam within the approved writeSet; the real adapter must remain the production default.",
-            "Select not-needed only with positive evidence that no remote API is involved, a stable real backend will be exercised, or existing fixtures already cover the contract without changes. not-needed still requires the fixed behavior entrypoint to exercise applicable real or no-remote behavior verification. When configured policy is required, not-needed is forbidden.",
+            autoMaySkipMissingMock
+                ? "Auto mode may skip Mock when no project Mock capability is confirmed. Select not-needed with positive evidence from contract/scout that no project Mock capability is confirmed, continue without adding Mock files or dependencies, run the fixed verification entrypoints, and record any unproved real API behavior in Real Integration Gap. Do not block solely because no project Mock capability, browser interception harness, or request adapter exists."
+                : "Select not-needed only with positive evidence that no remote API is involved, a stable real backend will be exercised, or existing fixtures already cover the contract without changes. not-needed still requires the fixed behavior entrypoint to exercise applicable real or no-remote behavior verification. When configured policy is required, not-needed is forbidden.",
             "Configured policy disabled requests no Mock but cannot override project specifications; if an actually-read project rule requires Mock, select blocked.",
             "",
             "## Required Output Sections:",
@@ -1356,6 +1364,9 @@ function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, f
             "- Read project Mock/API/schema specifications before making any judgment.",
             "- Do not infer Mock service from lockfile-only or transitive dependency evidence.",
             "- Output MOCK_STRATEGY: blocked if capability evidence conflicts, contract fields are missing/conflicting, paths or dependencies are unauthorized, specs were not actually read, sources conflict, production-default-off cannot be proven, the API layer is not writable for a new adapter, or the frozen entrypoints cannot verify the selected strategy.",
+            ...(autoMaySkipMissingMock
+                ? ["- In auto mode with no confirmed project Mock capability, do not block solely because Mock is unavailable or Mock-specific verification is absent; choose not-needed and make the Real Integration Gap explicit unless project specs require Mock or another safety rule is violated."]
+                : []),
             "- Never comment out or replace the real request with inline data, hard-code Mock enablement, import test mocks from a production entrypoint, invent API fields, or place secrets/real user data in fixtures.",
             "- Mock-backed behavior evidence proves the documented frontend contract only; it never proves real API integration.",
             "",
@@ -1564,7 +1575,11 @@ function resolveFrontendMockContextBlock(sources) {
         parts.push("Mock-backed frontend verification is required. Prefer the detected native service; otherwise the assessment may select an existing browser interception harness or reversible request adapter. Any handler, fixture, adapter, and UI changes stay in the single frontend-implement-pi writeSet.");
     }
     if (mode === "not-required") {
-        parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed only positively, or select a safe Mock strategy if an API dependency is confirmed.");
+        parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed when Mock is intentionally skipped, or select a safe Mock strategy if project evidence supports one.");
+        if ((sources.taskConfig.frontendMock?.policy ?? "auto") === "auto" &&
+            (capability.status === "absent" || capability.status === "ambiguous")) {
+            parts.push("Auto mode may skip Mock when no project Mock capability is confirmed. Do not block solely for missing Mock; keep the real request path as default and record any unproved backend behavior as Real Integration Gap.");
+        }
     }
     if (mode === "blocked") {
         parts.push("Mock contract is blocked. The DAG must stop before any write node executes.");
@@ -1900,7 +1915,7 @@ function buildFrontendHybridDagFromTask(sources) {
                 subtask_prompt: [
                     "Audit the frontend plan before implementation.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
-                    "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for the selected strategy. Mock strategies require Mock-backed evidence; not-needed requires applicable real or no-remote behavior evidence.",
+                    "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for the selected strategy. Mock strategies require Mock-backed evidence. not-needed requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case the plan must preserve the real request path and record the Real Integration Gap.",
                     "Also request revision for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, inline fake data, schema drift, or missing deterministic verification commands.",
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
@@ -2330,7 +2345,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     "Read the validated frontend-implementation-contract, frontend-verification-trace evidence, static/behavior shell facts, and actual diff. Trace proves command/file/symbol binding only—not semantic correctness.",
                     "Flag .skip/.only, deleted or weakened tests, unauthorized config changes, Mock-only evidence claimed as real integration, and Browser/visual claims (always not-run in this workflow).",
                     "Use the direct contract, original plan, revision/no-op result, and final design review to reconstruct the approved plan and design verdict; do not infer them from the implementation summary.",
-                    "Treat a commented-out real request, default-enabled Mock, production entrypoint importing test mocks, API/fixture contract drift, unauthorized Mock dependency/path, or missing behavior evidence for the selected strategy as at least Important. Mock strategies require Mock-backed evidence; not-needed requires applicable real or no-remote behavior evidence. Verify that the real request remains the default when Mock activation is absent.",
+                    "Treat a commented-out real request, default-enabled Mock, production entrypoint importing test mocks, API/fixture contract drift, unauthorized Mock dependency/path, or missing behavior evidence for the selected strategy as at least Important. Mock strategies require Mock-backed evidence. not-needed requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case verify that the real request remains the default and the Real Integration Gap is preserved.",
                     "Inspect the production/default-real-path static evidence directly and require Mock activation to be off for that check.",
                     "Distinguish Mock-backed evidence from real API integration evidence and preserve the Real Integration Gap when the backend was not exercised.",
                     "Review implementation quality, behavior/state coverage, verification evidence, and maintainability. Read-only: do not modify files.",
@@ -2391,6 +2406,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     "Return a frontend closeout summary covering Mock decision/strategy/files/verification/production boundary, changes, verification evidence, review result, known risks, and follow-up.",
                     "Include a coverage matrix for each requirement id, applicable UI state, and verification target/check with status passed|failed|not-run|blocked|unavailable. Always state Browser accessibility verification: not-run and Visual regression: not-run. Use frontend-verification-trace facts; do not invent Browser evidence from component tests.",
                     `When only Mock-backed evidence passed, state exactly Frontend status: mock-validated and Real integration: pending, summarize the Real Integration Gap, and name ${taskConfig.taskId}-real-api-integration-verify as the explicit follow-up task to create/run after backend readiness. This follow-up is not auto-created or auto-executed. Never describe Mock evidence as real API integration.`,
+                    `When Mock was skipped in auto mode and no real API evidence passed, state exactly Frontend status: locally-validated and Real integration: pending, summarize the Real Integration Gap, and name ${taskConfig.taskId}-real-api-integration-verify as the explicit follow-up task when backend readiness matters.`,
                     "Read-only: do not modify code, docs, artifacts, or .harness/dag-runs/.",
                     sourceContext,
                     mockContextBlock,

package/docs/README.md

@@ -12,6 +12,7 @@
 
 - `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
 - `development-principles.md` — 仓库开发原则
+- `github-collaboration.md` — 内部研发人员的轻量 GitHub 协作指南：短分支、简短 PR、CI 与 Squash Merge
 - `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
 - `architecture/README.md` — 架构文档目录索引与阅读路径
 - `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景

package/docs/init-surface.manifest.json

@@ -8,6 +8,9 @@
     "harness.json",
     "bin/loop-agent.js",
     "docs/README.md",
+    "docs/harness-methodology-tdd.md",
+    "docs/harness-methodology-verification.md",
+    "docs/harness-methodology-debugging.md",
     "docs/init-surface.manifest.json",
     "docs/architecture/runtime-boundaries.md",
     "docs/architecture/README.md",
@@ -38,16 +41,10 @@
     "docs/templates/product-line/task.yaml",
     "docs/templates/product-line/closeout.yaml",
     "docs/templates/product-line/links.md",
-    "scripts/check-product-line-docs.sh",
-    "scripts/check-task-pool-root.sh",
     "scripts/kb-bootstrap-init-skeleton.sh",
-    "scripts/kb-query.sh",
     "scripts/kb-query.mjs",
-    "scripts/kb-graph-materialize.sh",
     "scripts/kb-graph-materialize.mjs",
-    "scripts/kb-graph-promote.sh",
     "scripts/kb-graph-promote.mjs",
-    "scripts/kb-graph-incremental-prepare.sh",
     "scripts/kb-graph-incremental-prepare.mjs",
     "docs/templates/agent-dag.schema.json",
     "examples/example-dag.json",
@@ -181,7 +178,7 @@
     "docs/templates/product-line/closeout.yaml": "copied",
     "docs/templates/product-line/links.md": "copied",
     "scripts/check-skill-entry.sh": "generated",
-    "scripts/check-product-line-docs.sh": "copied",
+    "scripts/check-product-line-docs.sh": "generated",
     "scripts/check-repo.sh": "generated",
     "scripts/ci-governance.sh": "generated",
     "scripts/ci-tests.sh": "generated",

package/docs/templates/branch-merge-report.md

@@ -90,4 +90,3 @@ Add focused tests and real init/update/browser/CLI smokes required by the merged
 - Conflict files: `<paths>`.
 - First tests to run if a feature appears missing: `<commands>`.
 - Safe rollback strategy: prefer `git revert -m 1 <merge-commit>` after review; do not use destructive reset on shared work.
-

package/harness.json

@@ -59,7 +59,7 @@
     "pi": {
       "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "grok-4.5",
+      "MED": "glm-5.2",
       "HIGH": "gpt-5.6-sol"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -10,7 +10,10 @@
     "AGENTS.md",
     "bin/",
     "dist/",
-    "docs/*.md",
+    "docs/README.md",
+    "docs/harness-methodology-tdd.md",
+    "docs/harness-methodology-verification.md",
+    "docs/harness-methodology-debugging.md",
     "docs/architecture/runtime-boundaries.md",
     "docs/architecture/README.md",
     "docs/architecture/system-overview.md",
@@ -18,29 +21,16 @@
     "docs/architecture/worker-and-feature.md",
     "docs/architecture/facts-and-state.md",
     "docs/architecture/evolution.md",
-    "docs/decisions/README.md",
-    "docs/design/README.md",
-    "docs/exec-plans/README.md",
-    "docs/exec-plans/active/README.md",
-    "docs/exec-plans/completed/README.md",
     "docs/init-surface.manifest.json",
-    "docs/progress/README.md",
-    "docs/reports/README.md",
     "docs/skills/",
     "docs/templates/",
     "examples/",
     "harness.json",
     "skills/",
-    "scripts/check-product-line-docs.sh",
-    "scripts/check-task-pool-root.sh",
     "scripts/kb-bootstrap-init-skeleton.sh",
-    "scripts/kb-query.sh",
     "scripts/kb-query.mjs",
-    "scripts/kb-graph-materialize.sh",
     "scripts/kb-graph-materialize.mjs",
-    "scripts/kb-graph-promote.sh",
     "scripts/kb-graph-promote.mjs",
-    "scripts/kb-graph-incremental-prepare.sh",
     "scripts/kb-graph-incremental-prepare.mjs",
     "README.md",
     "CHANGELOG.md"
@@ -55,7 +45,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');const p='dist/worker/observe/static';fs.mkdirSync(p,{recursive:true});fs.cpSync('src/worker/observe/static',p,{recursive:true});\"",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "node scripts/check-npm-publish-policy.mjs && npm run typecheck && npm test && npm run build",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "test": "node scripts/run-tests.mjs",

package/skills/browser-tools/SKILL.md

@@ -117,10 +117,10 @@ Wrap everything in an IIFE to run multi-statement code:
   // Multiple operations
   const data = document.querySelector('#target').textContent;
   const buttons = document.querySelectorAll('button');
-  
+
   // Interactions
   buttons[0].click();
-  
+
   // Return results
   return JSON.stringify({ data, buttonCount: buttons.length });
 })()

package/skills/frontend-design-review/references/review-checklist.md

@@ -1,58 +1,40 @@
 # Frontend Design Review Checklist
 
-## Requirement And State Coverage
+## Coverage
 
-- Target route/page/component and non-goals are clear.
-- Every acceptance criterion maps to steps, files, UI behavior, and verification.
-- Assumptions and unresolved ambiguity are explicit.
-- Applicable success, error, loading, empty, disabled, permission, retry, stale-response, and boundary states are handled or marked N/A.
+- Route/component, non-goals, assumptions, and unresolved ambiguity are explicit.
+- Each acceptance criterion maps to steps, files, UI behavior, states, and verification.
+- Success/error/loading/empty/disabled/permission/retry/stale/boundary states are handled or N/A.
 
-## Project And Knowledge Fit
+## Project Fit
 
-- Existing components, hooks, API helpers, mocks, schemas, router patterns, templates, tokens, and theme rules were considered.
-- Component/design choices cite knowledge-base or `openSpec/`; failed/empty knowledge-base queries recurse through `<repoRoot>/openSpec/**` first.
-- Evidence records source status, query terms, paths/headings, and conflicts.
-- Dependencies are authorized; paths fit allowed/write scope and avoid forbidden/generated files.
-- A required Mock-backed strategy reuses native support when proven, otherwise an
-  existing browser-intercept/request-adapter seam; it maps endpoint/states to fixtures,
-  stays in writer scope, and is off in production. `not-needed` adds none.
+- Reuse components, hooks, API helpers, mocks, schemas, router patterns, tokens, and theme rules.
+- Cite knowledge-base or `openSpec/`; failed/empty knowledge queries must search `<repoRoot>/openSpec/**`.
+- Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths.
 
-## Interaction And Quality
+## Interaction / Quality
 
-- Actions, feedback, validation timing, navigation, persistence, and recovery are unambiguous.
-- Responsive and overflow behavior covers target environments.
-- Keyboard, focus, semantics, contrast, reduced motion, data lifecycle, cancellation, and error recovery are addressed when applicable.
+- Actions, feedback, validation timing, navigation, persistence, recovery, responsive/overflow, focus/keyboard/semantics/contrast/reduced motion, cancellation, and data lifecycle are covered when applicable.
 
 ## Verification
 
-- Static and behavior commands are exact, discoverable, and deterministic.
-- Tests prove changed state logic and flows at repository-supported levels.
-- Browser/visual checks are required only by task intent or existing gates.
-- Every missing verification path is a blocker or disclosed risk.
-- Verification entrypoints are frozen; any Mock-specific command is generated only
-  from trusted sources, and behavior separately proves page consumption.
-
-## Mock Strategy Safety
-
-- The strategy protocol is valid and not `MOCK_STRATEGY: blocked`.
-- For Mock strategies, API fields and fixture states trace to contract evidence; gaps are explicit.
-- Selection follows repository capability: native mock first, browser interception
-  for existing e2e, request adapter/injection for local preview.
-- The real request remains enabled by default; activation is explicit, reversible,
-  local/test-only, and excluded from production behavior.
-- Verification uses only shell entrypoints fixed when the DAG was generated; the
-  plan does not invent commands that shell nodes cannot execute.
-- Mock strategies include a production/default-real-path build with Mock off and
-  Mock-backed behavior evidence. `not-needed` instead needs applicable real or
-  no-remote behavior evidence.
-- Mock-backed checks prove frontend states only. Real integration remains pending
-  until the actual backend path has fresh evidence.
+- Static/behavior commands are exact, frozen, discoverable, and deterministic.
+- Tests prove changed state and flows at supported levels; browser/visual only when task/gate requires.
+- Missing required verification is a blocker; optional gaps are disclosed risks.
+
+## Mock Safety
+
+- Strategy line is valid and not `MOCK_STRATEGY: blocked`.
+- Mock API fields/states trace to contract evidence; gaps are explicit.
+- Prefer native mock; browser intercept only for existing e2e; request adapter only for reversible local preview.
+- Real request stays default; activation is explicit, reversible, local/test-only, and production-off.
+- Plans use only DAG-frozen shell entrypoints.
+- Mock strategies need default-real-path build with Mock off plus Mock-backed behavior evidence.
+- `not-needed` needs real/no-remote evidence, or default-auto skipped-Mock rationale with Real Integration Gap preserved when no project Mock capability exists.
+- Mock-backed checks prove frontend states only; real integration remains pending until actual backend evidence exists.
 
 ## Verdict Matrix
 
-- Coverage gap, unsafe scope, unauthorized dependency, unresolved required interaction, or missing required verification: request revision.
-- Missing knowledge-base evidence and skipped `openSpec/` fallback: request revision.
-- No relevant knowledge-base or `openSpec/` rule for a required decision: request revision.
-- Unsafe/missing mock strategy or mock evidence presented as real integration: request revision.
-- Knowledge-base unavailable but relevant `openSpec/` rules were applied: advisory connection gap, not a specification gap.
-- Optional cleanup that cannot affect acceptance: advisory.
+- Request revision for coverage gaps, unsafe scope, unauthorized deps, unresolved required interaction, missing required verification, skipped `openSpec/` fallback, unsafe/missing Mock strategy, or Mock evidence presented as real integration.
+- Knowledge-base unavailable but relevant `openSpec/` rules applied is advisory only.
+- Optional cleanup that cannot affect acceptance is advisory.

package/skills/frontend-implementation/references/node-contracts.md

@@ -6,11 +6,11 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
 - **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Knowledge base first; else search+read `<repoRoot>/openSpec/**` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-mock-assess-pi` + gate**: first non-empty line  
-  `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`  
-  Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. `not-needed` needs positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
+- **`frontend-mock-assess-pi` + gate**: first non-empty line
+  `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
+  Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
 - **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix).
-- **`frontend-implement-pi`**: sole exclusive writer. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption.
+- **`frontend-implement-pi`**: sole exclusive writer. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. Skipped-Mock `not-needed` keeps real integration pending unless the real backend path has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)
 

package/skills/frontend-review/SKILL.md

@@ -30,7 +30,9 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
 - Inspect static, behavior, and available Mock-specific artifacts directly. For Mock
   strategies, compare the endpoint matrix, handler/fixture/adapter and consumer diff;
   require the real request as default, contract-aligned fixtures, production isolation,
-  and no false real-integration claim. `not-needed` needs applicable real/no-remote evidence.
+  and no false real-integration claim. `not-needed` needs applicable real/no-remote
+  evidence, or an explicit default-auto skipped-Mock rationale with the Real
+  Integration Gap preserved when no project Mock capability is confirmed.
 - Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openSpec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence. Execute explicit `grep`/`find` to locate spec files and `read` to load them before referencing their rules. Only successful `read` tool calls are observable as "已读取规范文件" in the spec-evidence inspector.
 - Treat shell exit status as authoritative. Do not edit files.
 

package/skills/frontend-review/references/review-findings.md

@@ -43,5 +43,6 @@ Avoid vague advice. When no source location exists, cite the command or artifact
 - Changed files are authorized.
 - Criteria and applicable states have implementation and evidence.
 - Required Mock-backed behavior passed; any generated Mock-specific verification also
-  passed; Mock is not enabled by default in production.
+  passed; Mock is not enabled by default in production. For default-auto skipped
+  Mock, the real request remains default and the Real Integration Gap is preserved.
 - Optional unavailable knowledge-base, browser, visual, or manual checks remain explicit risks.

package/skills/frontend-verification/SKILL.md

@@ -45,7 +45,9 @@ Return Markdown headings:
 - `Follow-up`: concrete work or `None`.
 
 When the backend remains unavailable but required mock-backed checks pass, state
-`Frontend status: mock-validated` and `Real integration: pending`. Use a completed
+`Frontend status: mock-validated` and `Real integration: pending`. When default
+`auto` skipped Mock and no real API evidence passed, state
+`Frontend status: locally-validated` and `Real integration: pending`. Use a completed
 `<task-id>-real-api-integration-verify` task before changing the latter to complete;
 the follow-up is explicit, not auto-created or auto-executed.