@tea-agent/loop-agent 0.13.0-beta.0 → 0.14.0

package/docs/feature-workflow.md

@@ -12,7 +12,7 @@
 3. **Contract**：写明交付物、非目标、完成标准、验证命令、失败条件
 4. **Implement**：做最小连贯变更，同步更新必要文档、脚本与测试
 5. **Verify**：按 `verification-matrix.md` 跑命令；完成声明用新鲜输出
-6. **Handoff**：在 `docs/progress/`、`docs/reports/`、exec plan 或 ADR 中记录证据
+6. **Handoff**：在 `ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、exec plan 或 ADR 中记录证据
 
 ## Orient
 
@@ -65,7 +65,7 @@ Bug 修复的 contract 应含复现路径，以及证明修复的回归测试或
 
 验证是完成权威。
 
-- 用 `docs/verification-matrix.md` 选最窄的证明命令
+- 用 `ai_workspace/loop-agent/verification-matrix.md` 选最窄的证明命令
 - 完整重跑命令
 - 读 exit code 与输出
 - 修失败或报告确切失败状态
@@ -145,16 +145,22 @@ frontend-contract-pi
   -> frontend-mock-assess-pi
   -> frontend-mock-contract-gate-shell
   -> frontend-plan-pi
-  -> frontend-design-gate-pi
-  -> frontend-first-design-gate-shell
-  -> frontend-plan-revision-pi
+  -> [frontend-design-gate-pi -> frontend-first-design-gate-shell -> frontend-plan-revision-pi]  # small risk 可裁剪
   -> [frontend-requirement-coverage-shell]
+  -> frontend-implementation-contract-shell
   -> frontend-final-design-review-pi
   -> frontend-final-design-gate-shell
   -> frontend-implement-pi
   -> [frontend-mock-verify-shell]
   -> frontend-static-verify-shell
   -> frontend-behavior-verify-shell
+  -> frontend-verification-trace-shell
+  -> frontend-failure-assess-shell
+  -> frontend-repair-contract-shell
+  -> frontend-repair-pi
+  -> frontend-static-reverify-shell
+  -> frontend-behavior-reverify-shell
+  -> frontend-verification-retrace-shell
   -> frontend-review-pi
   -> frontend-review-gate-shell
   -> frontend-closeout-pi
@@ -168,29 +174,46 @@ frontend-contract-pi
 
 这条链在实现前加入两阶段 design gate：首轮 design review 同时接受 `VERDICT: pass` 和 `VERDICT: request-revision`，request-revision 时由只读 `frontend-plan-revision-pi` 消费原计划与 design findings 完成修订，再经 `frontend-final-design-review-pi` 和 `frontend-final-design-gate-shell` 最终门禁；只有最终 `VERDICT: pass` 才授权写入。`MOCK_STRATEGY: blocked`、真实请求被注释、生产默认启用 Mock 或 Mock 与接口契约不一致都不得通过。design gate 失败路由为 `ContractMismatch` / `frontend-plan-revision-and-rerun`，不路由为 `ProductBug` / `dev-fix`。
 
-这条链还将前端静态验证与行为验证分开建模；Mock-backed 行为验证只证明页面状态和交互，不证明真实后端已就绪或接口已联通。后端未被实际调用时，closeout 必须写明 `Frontend status: mock-validated`、`Real integration: pending`，并列出 `<task-id>-real-api-integration-verify`。该 follow-up 不会自动创建或运行；后端就绪后需要显式创建/执行新的复验任务。当前 MVP 不包含独立 a11y、视觉回归或浏览器自动化 executor。
+这条链还将前端静态验证与行为验证分开建模，并在 verify 后增加 verification-trace 与单轮 bounded repair（失败可评估/修复/复验；contract/path/依赖/凭据等不可自动修）。Mock-backed 行为验证只证明页面状态和交互，不证明真实后端已就绪或接口已联通。后端未被实际调用时，closeout 必须写明 `Frontend status: mock-validated`、`Real integration: pending`，并列出 `<task-id>-real-api-integration-verify`。该 follow-up 不会自动创建或运行；后端就绪后需要显式创建/执行新的复验任务。生成期会注入确定性风险分级与 React/Next/Vue 等强证据 capability；a11y 仅在项目已有 lint/axe 类工具时声明 static/component 级证据。当前仍不包含浏览器自动化、视觉回归或 browser-level a11y executor。
 
 后端测试任务只有在显式声明 `task.json.taskKind = "backend-test"` 时才选择专用模板；它面向测试工程，不是普通后端实现模式，也不新增 governance profile：
 
 ```text
 analyze-inputs-pi
+  -> backend-test-analysis-contract-shell
+  -> backend-test-environment-scout-pi
+  -> backend-test-execution-contract-shell
   -> generate-backend-functional-cases-pi
+  -> emit-backend-case-manifest-pi
+  -> backend-test-case-manifest-shell
   -> review-backend-cases-pi
   -> review-backend-cases-gate-shell
   -> generate-backend-pytest-pi
+  -> backend-test-traceability-gate-shell
   -> execute-backend-pytest-shell
+  -> parse-backend-test-result-shell
+  -> classify-backend-test-result-pi
   -> test-retrospect-pi
+  -> backend-test-outcome-gate-shell
 ```
 
 这条链覆盖后端功能测试从需求分析到复盘评级的全链路流程：
 
 - `analyze-inputs-pi`：只读输出严格的 Backend Test Analysis v1 JSON；`backend-test-analysis-contract-shell` 确定性校验 source binding、AC IDs、schema 与敏感值，并把规范化结果写入当前 run 的 `contracts/backend-test-analysis.json`。gate 节点记录 artifact path / SHA-256 / schema ID，随 lifecycle 目录整体迁移；非法或来源不一致时 fail-closed，后续 case/pytest writers 不执行。
-- `generate-backend-functional-cases-pi`：只消费已验证 analysis artifact，按契约字段生成结构化后端功能测试用例（Markdown），用例 ID 带 `BE-` 前缀（如 `BE-ORDER-001`），写入 `testcase/md/`
-3. **review-backend-cases-pi**：评审后端功能测试用例，输出审查报告 + `VERDICT: pass` / `VERDICT: request-revision`
-4. **review-backend-cases-gate-shell**：只有评审首条 verdict 为 `VERDICT: pass` 时才允许继续生成 pytest；`request-revision` 或其它结果 **fail-closed 即停**，**不会**自动回到 generate 节点修订（本模板不启用 convergence；修好用例或约束后重新 `dag run-task`）
-5. **generate-backend-pytest-pi**：将后端功能用例转化为 pytest 自动化代码；可写 `testcase/**/test_*.py` 与可选 `testcase/**/helpers/**`、`testcase/**/factories/**`，禁止改 conftest/配置与生产代码；数据构造 API 优先，DB 直写仅限已有安全测试库 fixture
-6. **execute-backend-pytest-shell**：执行 `pytest testcase/`；目标工作区保持 `writePolicy: read-only`，内置 `--junitxml` 将报告写入当前 `$HARNESS_DAG_RUN_DIR/reports/backend-test-junit.xml`（不依赖 `pytest-html`），报告随 run 从 active 归档到 completed/paused，禁止改测试源码或生产代码
-7. **test-retrospect-pi**：读取上游审查报告和测试报告，生成复盘报告 + 成熟度评级（A/B/C/D）
+- `backend-test-environment-scout-pi`（read-only）：发现 pytest 配置、test roots、已有 fixture/client、文档化命令与 env *名称*（禁止全仓搜 secrets）；输出 Backend Test Execution Contract v1 纯 JSON。
+- `backend-test-execution-contract-shell`：`jsonArtifactGate.schemaId=backend-test-execution-v1`，校验并 materialize 当前 run 的 `contracts/backend-test-execution.json`；unknown schemaId / path traversal / secret 值 fail-closed。
+- `emit-backend-case-manifest-pi`（read-only）：从 `testcase/md/**` + 已验证 analysis 产出 Backend Test Case Manifest v1 纯 JSON（模型不写 `.harness/**`）。
+- `backend-test-case-manifest-shell`：`jsonArtifactGate.schemaId=backend-test-case-manifest-v1` → `contracts/backend-test-case-manifest.json`；caseId 唯一/格式、显式 AC 覆盖或 evidenceGaps、未知 AC、skipped 无 gapReason fail-closed；`coverageSummary` 由 gate 确定性计算/核对。
+- `backend-test-traceability-gate-shell`：pytest 生成后、execute 前校验 `generated` 的 file/symbol 存在；skipped/unsupported 必须有 gapReason。
+- `generate-backend-functional-cases-pi`：在 execution gate 之后，只消费已验证 analysis/execution 证据，按契约字段生成结构化后端功能测试用例（Markdown），用例 ID 带 `BE-` 前缀（如 `BE-ORDER-001`），写入 `testcase/md/`
+- `review-backend-cases-pi`：评审后端功能测试用例，输出审查报告 + `VERDICT: pass` / `VERDICT: request-revision`
+- `review-backend-cases-gate-shell`：只有评审首条 verdict 为 `VERDICT: pass` 时才允许继续生成 pytest；`request-revision` 或其它结果 **fail-closed 即停**，**不会**自动回到 generate 节点修订（本模板不启用 convergence；修好用例或约束后重新 `dag run-task`）
+- `generate-backend-pytest-pi`：依赖 review gate **与** execution contract，将功能用例转化为 pytest；可写 `testcase/**/test_*.py` 与可选 `helpers/**`/`factories/**`；只使用已验证 fixture/env name/`testRoot`/API 字段；禁止改 conftest/配置与生产代码
+- `execute-backend-pytest-shell`：先对 `contracts/backend-test-execution.json` 做确定性 preflight（framework、`testRoot` 存在且与生成期冻结的 Adapter 路径一致、required env、external base URL env；`managed-command` 无 sourceRef 证据 fail-closed），再执行 `pytest testcase/`；JUnit 写入 `$HARNESS_DAG_RUN_DIR/reports/backend-test-junit.xml`，原始 `pytestExitCode` 写入 `reports/backend-test-pytest-exit.txt`。当 JUnit 非空且 exit 为 0/1 时节点 FINISHED（断言失败不跳过下游）；禁止改测试源码或生产代码
+- `parse-backend-test-result-shell`：确定性 materialize Backend Test Result v1 → `contracts/backend-test-result.json`（损坏/缺失 JUnit fail-closed）
+- `classify-backend-test-result-pi`：read-only 结构化分类（ProductBug|TestBug|EnvFailure|ContractMismatch|FlakyTest|Unknown）；单次失败不得 FlakyTest；collection/command/report-error 不得 ProductBug
+- `test-retrospect-pi`：在 pass 与 assertion-fail 路径均运行；通过率与失败列表只来自 Result v1；不得把失败改写成通过
+- `backend-test-outcome-gate-shell`：仅以 Result v1 `outcome`/counts 收口；全绿 exit 0，否则非零；忽略 retrospective Markdown
 
 最终验证后的知识库回写可通过 `task.json.taskKind = "knowledge-sync"` 选择专用模板（与 `backend-test` 一样走 taskKind 路由，不占用 governance `--profile`）。
 
@@ -221,38 +244,40 @@ knowledge-sync-collect-pi
 2. **knowledge-sync-draft-pi**：写入 `features/<featureId>/testing/sync/pending/knowledge-sync-draft.json`
 3. **knowledge-sync-validate-shell**：校验该路径 draft 的 schema、`featureId` 一致、operations 目标路径、finalVerification 门禁
 4. **多视角审查（并行）**：QA/验收、领域/产品、证据/审计 三个只读 reviewer；聚合门禁要求全部 `VERDICT: pass`
-5. **knowledge-sync-apply-pi**：仅在 `features/<featureId>/testing/**`（及该 Feature 的 `requirement-delta.md`、`docs/test-reports/**`）受控回写
+5. **knowledge-sync-apply-pi**：仅在 `features/<featureId>/testing/**`（及该 Feature 的 `requirement-delta.md`、`ai_workspace/loop-agent/test-reports/**`）受控回写
 6. **knowledge-sync-pointer-pi**：写 `features/<featureId>/testing/runs/latest.md` 与 `sync/applied/KS-*.json`
 
-设计说明见 `docs/design/full-chain-test-knowledge-base.md` §11；JSON 示例见 `docs/templates/knowledge-sync-dag.json`。
+设计说明见 `ai_workspace/loop-agent/design/full-chain-test-knowledge-base.md` §11；JSON 示例见 `ai_workspace/loop-agent/templates/knowledge-sync-dag.json`。
 
 业务知识图谱**初始化**可通过 `task.json.taskKind = "knowledge-graph-bootstrap"` 选择专用模板。跑前先落 B1 骨架：
 
 ```bash
-bash scripts/kb-bootstrap-init-skeleton.sh --root .
+loop-agent knowledge graph-init --product-name <name>
 # 编辑 knowledge/bootstrap/scope.yaml 后再 run-task
 ```
 
-（需有 `knowledge/bootstrap/scope.yaml` 与 `status.yaml`；脚本幂等，默认不覆盖已有 scope/status，可用 `--force`。）
+（需有 `knowledge/bootstrap/scope.yaml` 与 `status.yaml`；`graph-init` 幂等，默认不覆盖已有 scope/status，可用 `--force`。）
 
-图谱索引与 Phase A 查询（脚本，非 RAG）：
+图谱索引与 Phase A 查询（package-backed CLI，非 RAG）：
 
 ```bash
-bash scripts/kb-graph-materialize.sh --root .
-bash scripts/kb-query.sh --mode by_feature --feature F-2026-004 --json
-bash scripts/kb-query.sh --mode by_id --id SVC-order --json
-bash scripts/kb-query.sh --mode search --text "预占" --json
+loop-agent knowledge graph-materialize
+loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
+loop-agent knowledge query --mode by_id --id SVC-order --json
+loop-agent knowledge query --mode search --text "预占" --json
 ```
 
 **增量更新（非全量开荒）**：缩小 scope 后复用同一 `knowledge-graph-bootstrap` DAG（propose 仅针对 seeds/includes；promote 仍默认不覆盖已有正式文件）：
 
 ```bash
-bash scripts/kb-graph-incremental-prepare.sh --root . \
-  --feature F-2026-004 --service order [--reset-staging]
+loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service order
+# 可选：--reset-staging
 # 审阅 knowledge/bootstrap/scope.yaml（update_mode: incremental）
 # task.json.taskKind = "knowledge-graph-bootstrap"
 loop-agent dag run-task <id>
-bash scripts/kb-graph-materialize.sh --root .
+# 如需手工晋升已审阅的 staging，再按顺序执行：
+loop-agent knowledge graph-promote
+loop-agent knowledge graph-materialize
 ```
 
 测试知识日常写回仍用 `knowledge-sync`（`featureId` 必填），与图谱增量入口分离。
@@ -270,7 +295,7 @@ kg-bootstrap-preflight-shell
   -> kg-bootstrap-materialize-shell
 ```
 
-AI 只写 `knowledge/bootstrap/staging/**`；禁止 self-`asserted`；**结构 / 证据 / 边界安全** 三视角审查全部通过后才 promote（默认不覆盖已有正式文件）；materialize 写 `knowledge/graph/` 索引。设计见 `docs/design/knowledge-graph-ai-bootstrap.md`，示意 JSON 见 `docs/templates/knowledge-graph-bootstrap-dag.json`。
+AI 只写 `knowledge/bootstrap/staging/**`；禁止 self-`asserted`；**结构 / 证据 / 边界安全** 三视角审查全部通过后才 promote（默认不覆盖已有正式文件）；materialize 写 `knowledge/graph/` 索引。设计见 `ai_workspace/loop-agent/design/knowledge-graph-ai-bootstrap.md`，示意 JSON 见 `ai_workspace/loop-agent/templates/knowledge-graph-bootstrap-dag.json`。
 
 前端测试模板（`frontend-test-dag`）后续沿用对称命名即可接入。
 前端 shell 验证优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，例如 `npm run typecheck`、`npm run build`、`npm test`；解析不到时再使用 adapter 验证命令和模板 fallback。
@@ -281,11 +306,11 @@ AI 只写 `knowledge/bootstrap/staging/**`；禁止 self-`asserted`；**结构 /
 verify-shell -> verify-pi -> review-pi -> review-gate-shell -> closeout-pi
 ```
 
-supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
+supervised 模板在实现路径上增加 write-set audit、有界计划修订、只读 verdict 格式恢复、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。初审 `request-revision` 不再直接终止：只读 `plan-revision-pi` 最多修订一轮，再由终审和 pass-only gate 决定是否授权 writer。初审与终审遗漏 `VERDICT:` 时各允许一个只读格式修复节点；格式结论不明确时必须转为 `request-revision`，shell gate 不会从正文猜测 pass。
 
 ### 只读 Pi 节点安全重试
 
-所有生成模板都会为安全的只读 Pi 节点（planner/scout/reviewer/verifier/closeout，且 `writePolicy=read-only|none`、非 writer、非 dynamic、非 decision-gate）自动声明默认 `retryPolicy`（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不在资格范围。仅重试 `timeout`、`network`、`rate-limit`、`unavailable`；`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试。每次 attempt 保留独立证据，详见 [docs/agent-dag-runner.md](./agent-dag-runner.md#retry-read-only-pi-nodes)。
+所有生成模板都会为安全的只读 Pi 节点（planner/scout/reviewer/verifier/closeout，且 `writePolicy=read-only|none`、非 writer、非 dynamic、非 decision-gate）自动声明默认 `retryPolicy`（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不在资格范围。仅重试 `timeout`、`network`、`rate-limit`、`unavailable`；`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试。每次 attempt 保留独立证据，详见 [ai_workspace/loop-agent/agent-dag-runner.md](./agent-dag-runner.md#retry-read-only-pi-nodes)。
 
 ### 可选 repo-local SDD skill 增强
 
@@ -316,7 +341,7 @@ supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验
 - 选择验证命令
 - 记录 handoff 证据
 
-声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
+声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `ai_workspace/loop-agent/production-readiness.md` 与 `ai_workspace/loop-agent/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
 
 ## Exec-plan 生命周期
 
@@ -372,9 +397,9 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 
 任务需要时使用方法论文档：
 
-- 行为变更与 bug 修复：`docs/harness-methodology-tdd.md`
-- 完成或 handoff 声明：`docs/harness-methodology-verification.md`
-- 失败与意外行为：`docs/harness-methodology-debugging.md`
+- 行为变更与 bug 修复：`ai_workspace/loop-agent/harness-methodology-tdd.md`
+- 完成或 handoff 声明：`ai_workspace/loop-agent/harness-methodology-verification.md`
+- 失败与意外行为：`ai_workspace/loop-agent/harness-methodology-debugging.md`
 
 ## Handoff
 
@@ -386,4 +411,4 @@ Handoff 应说明：
 - 是否影响契约、文档、测试或脚本
 - 剩余风险或后续工作
 
-较大工作应更新 `docs/progress/`、`docs/reports/`、active exec plan 或 `docs/decisions/`，以便下一会话不依赖聊天历史。
+较大工作应更新 `ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、active exec plan 或 `ai_workspace/loop-agent/decisions/`，以便下一会话不依赖聊天历史。

package/docs/init-surface.manifest.json

@@ -40,6 +40,15 @@
     "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",
     "skills/agent-worker/SKILL.md",
@@ -68,7 +77,10 @@
     "skills/frontend-review/references/review-findings.md",
     "skills/frontend-verification/SKILL.md",
     "skills/frontend-verification/references/verification-checklist.md",
-    "docs/templates/backend-test-analysis.schema.json"
+    "docs/templates/backend-test-analysis.schema.json",
+    "docs/templates/backend-test-execution.schema.json",
+    "docs/templates/backend-test-result.schema.json",
+    "docs/templates/backend-test-case-manifest.schema.json"
   ],
   "initFullRequired": [
     "README.md",
@@ -134,7 +146,10 @@
     ".agents/skills/frontend-review/references/review-findings.md",
     ".agents/skills/frontend-verification/SKILL.md",
     ".agents/skills/frontend-verification/references/verification-checklist.md",
-    "docs/templates/backend-test-analysis.schema.json"
+    "docs/templates/backend-test-analysis.schema.json",
+    "docs/templates/backend-test-execution.schema.json",
+    "docs/templates/backend-test-result.schema.json",
+    "docs/templates/backend-test-case-manifest.schema.json"
   ],
   "initSurface": {
     "README.md": "managed-block",
@@ -201,7 +216,10 @@
     ".agents/skills/frontend-review/references/review-findings.md": "copied",
     ".agents/skills/frontend-verification/SKILL.md": "copied",
     ".agents/skills/frontend-verification/references/verification-checklist.md": "copied",
-    "docs/templates/backend-test-analysis.schema.json": "copied"
+    "docs/templates/backend-test-analysis.schema.json": "copied",
+    "docs/templates/backend-test-execution.schema.json": "copied",
+    "docs/templates/backend-test-result.schema.json": "copied",
+    "docs/templates/backend-test-case-manifest.schema.json": "copied"
   },
   "packageExcluded": [
     "docs/progress/20*.md",

package/docs/loop-agent-harness.md

@@ -16,26 +16,26 @@ loop-agent 提供结构化 agent 工作的本地 harness。
 
 ## Skill 指令
 
-- `skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
-- `skills/agent-worker/` — Feature Packet、TaskSpec、Task Pool、controller pinning、自举 candidate canary 与 Worker recovery 的可选 outer-loop operator skill；不是 DAG node skill
-- `.agents/skills/<skill-name>/` — 目标项目 repo-local skill 副本；`skills/<skill-name>/` 仍是 loop-agent 源仓库和 npm 包内置回退路径
+- `.agents/skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
+- `.agents/skills/agent-worker/` — Feature Packet、TaskSpec、Task Pool、controller pinning、自举 candidate canary 与 Worker recovery 的可选 outer-loop operator skill；不是 DAG node skill
+- `.agents/skills/<skill-name>/` — 目标项目 repo-local skill 副本；`.agents/skills/<skill-name>/` 仍是 loop-agent 源仓库和 npm 包内置回退路径
 - 历史 `skill/` 不再是必需仓库路径；runtime 查找仅为 `loop-agent` 保留兼容 fallback
 
 目标项目若在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，hybrid DAG 生成器会按节点追加对应 skill。该增强只复用 repo-local 知识与方法：loop-agent 仍拥有流程与状态控制权，embedded-mode 约束禁止 SDD 状态推进、确认门禁和归档；初始化/扫描类 SDD skill 不会自动执行。未命中时不会改变默认 DAG。命中的节点 skill 继续由同一 resolved instruction 和 run-owned snapshot 机制冻结，没有第二套 loader 或旁路。
 
 ## Package 资产
 
-npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与 `agent-worker`）、顶层 `docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
+npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`.agents/skills/`（包括 `loop-agent` 与 `agent-worker`）、顶层 `ai_workspace/loop-agent/*.md`、`ai_workspace/loop-agent/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
 
-生成或历史的 task facts 不是 package 资产。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
+生成或历史的 task facts 不是 package 资产。`ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
 
-从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标项目 `.agents/skills/` 解析（若存在），再回退到包内 `skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或根 `skills/` 目录即可使用默认 DAG 工作流。
+从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标项目 `.agents/skills/` 解析（若存在），再回退到包内 `.agents/skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或根 `.agents/skills/` 目录即可使用默认 DAG 工作流。
 
 `scripts/self-host-canary.mjs` 是源码仓库维护脚本，不进入 npm package `files`；安装后的 package 不把它作为用户命令 surface。
 
 ## harness.json Schema
 
-`docs/templates/harness.schema.json` 是面向 IDE 的 `harness.json` JSON Schema。它用于补全字段、提示枚举值、解释 executor/model routing 配置，并尽早暴露拼写错误。
+`ai_workspace/loop-agent/templates/harness.schema.json` 是面向 IDE 的 `harness.json` JSON Schema。它用于补全字段、提示枚举值、解释 executor/model routing 配置，并尽早暴露拼写错误。
 
 运行时事实源仍是 `src/governance/manifest-types.ts` 中的 Zod `harnessManifestSchema`；CLI 读取 `harness.json` 时继续通过 `loadHarnessManifest()` 解析。JSON Schema 不替代运行时校验，只服务编辑体验。
 
@@ -75,7 +75,7 @@ DAG agent 节点的输出语言由 `harness.json.workflowPolicy.dag.outputLangua
 - `handoff check`、`spine audit`、`knowledge curate`
 - `agent-worker feature review|run|verify-final|delivery|closeout|approve-followup`、`agent-worker task validate|explain-profile|retry|draft-followup`、`agent-worker batch run-ready`、`agent-worker pool doctor|migrate-state`、`agent-worker report morning|metrics`、`agent-worker observe serve|snapshot`
 
-`dag run-task` 在生成 DAG 草稿前会运行与 `plan check` 同源的 exec-plan 索引校验；active plan 与 `docs/exec-plans/active/README.md` 索引不一致时立即失败，避免运行昂贵节点后才在末端 shell verify 发现。`plan create` 优先复用目标项目模板并回退到发布包内置 `docs/templates/exec-plan.md`，`plan create`/`plan complete` 的多文件写入均有回滚保护；`new-task` 不自动绑定 exec-plan。
+`dag run-task` 在生成 DAG 草稿前会运行与 `plan check` 同源的 exec-plan 索引校验；active plan 与 `ai_workspace/loop-agent/exec-plans/active/README.md` 索引不一致时立即失败，避免运行昂贵节点后才在末端 shell verify 发现。`plan create` 优先复用目标项目模板并回退到发布包内置 `ai_workspace/loop-agent/templates/exec-plan.md`，`plan create`/`plan complete` 的多文件写入均有回滚保护；`new-task` 不自动绑定 exec-plan。
 
 ## Feature Review
 

package/docs/production-readiness.md

@@ -84,7 +84,7 @@ product_line_failure_category
 recommended_follow_up
 ```
 
-Product-line category 事实源：`docs/design/state-and-failure-taxonomy.md`。
+Product-line category 事实源：`ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
 
 ## Sprint Gate
 

package/docs/progress/README.md

@@ -2,11 +2,20 @@
 
 本目录存放应超越聊天上下文的简洁 handoff 日志。
 
-**索引职责**：本文件维护本目录**全量文件列表**。`docs/README.md` 只链到本 README。
+**索引职责**：本文件维护本目录**全量文件列表**。`ai_workspace/loop-agent/README.md` 只链到本 README。
 
 ## 近期要点（导读）
 
-- [`2026-07-17-frontend-beta-publish-guard.md`](2026-07-17-frontend-beta-publish-guard.md) — frontend 分支 npm beta 发布门禁：`prepublishOnly` 强制 beta SemVer + beta dist-tag（已验证）
+- [`2026-07-18-observe-ops-surface-and-rich-timeline.md`](2026-07-18-observe-ops-surface-and-rich-timeline.md) — Observe 运营面/执行面重排、检查器半屏与富过程时间线收口（已归档 completed）
+- [`2026-07-17-observe-dashboard-incremental-polling-handoff.md`](2026-07-17-observe-dashboard-incremental-polling-handoff.md) — Observe 总览重复 loading/全量 DOM 重建根因、DAG 契约和跨机器恢复步骤
+- [`2026-07-17-0.13.0-merge-handoff.md`](2026-07-17-0.13.0-merge-handoff.md) — 0.13.0 合并、修复、验证与 Windows 剩余问题跨机器交接
+- [`2026-07-17-source-target-structure-alignment.md`](2026-07-17-source-target-structure-alignment.md) — 源仓库 canonical layout 对齐 fresh init，并记录首轮 write-set audit 修订
+- [`2026-07-17-fe-test-dag-archive.md`](2026-07-17-fe-test-dag-archive.md) — FE-test RAG DAG MVP + PR #25 收口归档（residual：prompt 深度 / browser smoke / website）
+- [`2026-07-17-frontend-implementation-m4-m6.md`](2026-07-17-frontend-implementation-m4-m6.md) — frontend-implementation 风险路由、项目能力、修复合同与 package surface 收口
+- [`2026-07-17-frontend-implementation-m3-repair.md`](2026-07-17-frontend-implementation-m3-repair.md) — frontend-implementation repair contract 与验证闭环
+- [`2026-07-17-frontend-implementation-m2-writer-trace.md`](2026-07-17-frontend-implementation-m2-writer-trace.md) — frontend writer trace 与 verification trace 证据
+- [`2026-07-17-frontend-implementation-contract-v1.md`](2026-07-17-frontend-implementation-contract-v1.md) — frontend implementation contract v1
+- [`2026-07-17-frontend-implementation-m0-baseline.md`](2026-07-17-frontend-implementation-m0-baseline.md) — frontend-implementation M0 能力基线
 - [`2026-07-16-frontend-mock-node.md`](2026-07-16-frontend-mock-node.md) — 前端 DAG Mock 策略、生产安全与真实接口证据边界（已验证）
 - [`2026-07-16-frontend-demand-auto-routing.md`](2026-07-16-frontend-demand-auto-routing.md) — 默认前端需求自动进入前端专用 DAG，后端/混合/未知保守回退（已验证）
 - [`2026-07-16-ready-planner.md`](2026-07-16-ready-planner.md) — Priority-aware Ready Planner：M1 core + RP-02 Feature/report/Observe 同源投影（已验证）
@@ -32,7 +41,15 @@
 
 ## 全量列表（新→旧）
 
-- [`2026-07-17-frontend-beta-publish-guard.md`](2026-07-17-frontend-beta-publish-guard.md)
+- [`2026-07-17-observe-dashboard-incremental-polling-handoff.md`](2026-07-17-observe-dashboard-incremental-polling-handoff.md)
+- [`2026-07-17-0.13.0-merge-handoff.md`](2026-07-17-0.13.0-merge-handoff.md)
+- [`2026-07-17-source-target-structure-alignment.md`](2026-07-17-source-target-structure-alignment.md)
+- [`2026-07-17-fe-test-dag-archive.md`](2026-07-17-fe-test-dag-archive.md)
+- [`2026-07-17-frontend-implementation-m4-m6.md`](2026-07-17-frontend-implementation-m4-m6.md)
+- [`2026-07-17-frontend-implementation-m3-repair.md`](2026-07-17-frontend-implementation-m3-repair.md)
+- [`2026-07-17-frontend-implementation-m2-writer-trace.md`](2026-07-17-frontend-implementation-m2-writer-trace.md)
+- [`2026-07-17-frontend-implementation-contract-v1.md`](2026-07-17-frontend-implementation-contract-v1.md)
+- [`2026-07-17-frontend-implementation-m0-baseline.md`](2026-07-17-frontend-implementation-m0-baseline.md)
 - [`2026-07-16-frontend-mock-node.md`](2026-07-16-frontend-mock-node.md)
 - [`2026-07-16-frontend-demand-auto-routing.md`](2026-07-16-frontend-demand-auto-routing.md)
 - [`2026-07-16-ready-planner.md`](2026-07-16-ready-planner.md)

package/docs/reports/README.md

@@ -1,8 +1,19 @@
 # 报告
 
+## 合并报告命名
+
+跨分支合并报告使用 `YYYY-MM-DD-origin-<source>-into-<target>-<source-short-sha>.md`。同一天重复合并时由 source short SHA 唯一标识；报告应记录双方功能、冲突文件与解析、自动合并高风险点、初始化/发布面影响、验证证据及剩余风险。新报告从 [`../templates/branch-merge-report.md`](../templates/branch-merge-report.md) 创建。
+
+- [`2026-07-18-origin-0.13.0-into-main-7c1a139.md`](2026-07-18-origin-0.13.0-into-main-7c1a139.md) — 将已发布并验证的 0.13.0 显式回合 main，合并后运行时代码树与发布分支一致
+- [`2026-07-18-origin-0.13.0-into-main-7c1a139-init-evolution-review.md`](2026-07-18-origin-0.13.0-into-main-7c1a139-init-evolution-review.md) — 0.13.0 回合 main 的 init/package/update surface 审查
+- [`2026-07-18-origin-main-into-0.13.0-43e86ad.md`](2026-07-18-origin-main-into-0.13.0-43e86ad.md) — 合入 frontend implementation M0–M6 与 browser-tools，同时保留 Observe、init/update 和既有受治理 DAG 能力
+- [`2026-07-18-origin-main-43e86ad-init-evolution-review.md`](2026-07-18-origin-main-43e86ad-init-evolution-review.md) — 本次合并的 package/full-init/update surface 审查
+- [`2026-07-17-origin-main-into-0.13.0-c139cf5.md`](2026-07-17-origin-main-into-0.13.0-c139cf5.md) — 合并 backend-test M0–M4、frontend-test/Playwright CLI 与 Pi SDK 更新，同时保留 0.13.0 初始化、Observe 和 Windows 稳定性修复
+- [`2026-07-17-origin-main-c139cf5-init-evolution-review.md`](2026-07-17-origin-main-c139cf5-init-evolution-review.md) — 本次高影响 merge 的 init/package/full-init/update 审查
+
 本目录存放验证、审计、benchmark、init evolution 与 closeout 报告。
 
-**索引职责**：本文件维护本目录**全量文件列表**。`docs/README.md` 只链到本 README，不再精选单篇 report。
+**索引职责**：本文件维护本目录**全量文件列表**。`ai_workspace/loop-agent/README.md` 只链到本 README，不再精选单篇 report。
 
 查找约定：
 
@@ -12,15 +23,19 @@
 
 ## 近期要点（导读，非权威全集）
 
+- [`2026-07-17-origin-main-merge.md`](2026-07-17-origin-main-merge.md) — origin/main 合并、canonical 路径收敛与 partial_failed 闭环说明
+- [`2026-07-17-review-findings-remediation-init-evolution-review.md`](2026-07-17-review-findings-remediation-init-evolution-review.md) — 主干 review findings 初始化影响审查
+- [`2026-07-16-frontend-mock-node-init-evolution-review.md`](2026-07-16-frontend-mock-node-init-evolution-review.md) — 前端 Mock 节点初始化影响审查
+- [`2026-07-16-frontend-mock-data-workflow.md`](2026-07-16-frontend-mock-data-workflow.md) — 前端 Mock 数据工作流报告
+- [`2026-07-16-frontend-mock-data-workflow-init-evolution-review.md`](2026-07-16-frontend-mock-data-workflow-init-evolution-review.md) — 前端 Mock 数据工作流初始化影响审查
+- [`2026-07-16-frontend-demand-auto-routing-init-evolution-review.md`](2026-07-16-frontend-demand-auto-routing-init-evolution-review.md) — 前端需求自动路由初始化影响审查
+- [`2026-07-16-dag-source-binding-recovery-init-evolution-review.md`](2026-07-16-dag-source-binding-recovery-init-evolution-review.md) — DAG 任务源绑定初始化影响审查
+- [`2026-07-16-backend-test-run-owned-report-init-evolution-review.md`](2026-07-16-backend-test-run-owned-report-init-evolution-review.md) — backend-test run-owned 报告初始化影响审查
+- [`2026-07-17-source-target-structure-alignment-partial-failed.md`](2026-07-17-source-target-structure-alignment-partial-failed.md) — 首轮结构迁移在 writer 前被 write-set audit 正确阻断的原因与 r2 修订
 - [`2026-07-17-weekly-progress-summary-last-tue-to-today.md`](2026-07-17-weekly-progress-summary-last-tue-to-today.md) — 管理层阶段进展总结（07-07～07-17：0.6→0.12、Observe/Feature/Task Pool/Planner）
 - [`2026-07-17-backend-test-analysis-contract-init-evolution-review.md`](2026-07-17-backend-test-analysis-contract-init-evolution-review.md) — backend-test run-owned 结构化分析契约与 JSON Schema 初始化投影审查
-- [`2026-07-17-review-findings-remediation-init-evolution-review.md`](2026-07-17-review-findings-remediation-init-evolution-review.md) — knowledge graph promote、incremental scope 与 init run placeholder 修复的高影响审查
-- [`2026-07-16-dag-source-binding-recovery-init-evolution-review.md`](2026-07-16-dag-source-binding-recovery-init-evolution-review.md) — DAG 任务源绑定、前端需求覆盖门禁与中断恢复的 init surface 高影响审查
 - [`current-capability-summary.md`](current-capability-summary.md) — **活**能力摘要（新进展写这里 / CHANGELOG / 新 report）
-- [`2026-07-16-frontend-mock-node-init-evolution-review.md`](2026-07-16-frontend-mock-node-init-evolution-review.md) — 前端 Mock 策略节点、skill/init 投影与真实接口证据边界审查（init update required）
-- [`2026-07-16-frontend-demand-auto-routing-init-evolution-review.md`](2026-07-16-frontend-demand-auto-routing-init-evolution-review.md) — 前端需求自动路由与目标项目初始化投影审查（init update required）
-- [`2026-07-16-frontend-mock-data-workflow.md`](2026-07-16-frontend-mock-data-workflow.md) — 前端 DAG Mock 评估、门禁、专项验证与初始化投影实现报告
-- [`2026-07-16-frontend-mock-data-workflow-init-evolution-review.md`](2026-07-16-frontend-mock-data-workflow-init-evolution-review.md) — 前端 Mock 数据流程的 init surface 高影响审查
+- [`2026-07-16-0.13.0-init-evolution-review.md`](2026-07-16-0.13.0-init-evolution-review.md) — 0.12.0→0.13.0 init 更新连续性修复与 knowledge surface 审查（init update required）
 - [`2026-07-16-task-pool-priority-aware-ready-planner.md`](2026-07-16-task-pool-priority-aware-ready-planner.md) — Priority-aware Ready Planner 关闭报告
 - [`2026-07-15-task-pool-v2-feature-scoped-task-identity.md`](2026-07-15-task-pool-v2-feature-scoped-task-identity.md) — Task Pool v2 复合身份 M0–M4 最终报告
 - [`2026-07-15-task-pool-v2-init-evolution-review.md`](2026-07-15-task-pool-v2-init-evolution-review.md) — Task Pool v2 文档变更的 init surface 非影响审查
@@ -39,11 +54,36 @@
 
 ## 全量列表（新→旧）
 
+- [`2026-07-18-origin-0.13.0-into-main-7c1a139.md`](2026-07-18-origin-0.13.0-into-main-7c1a139.md)
+- [`2026-07-18-origin-0.13.0-into-main-7c1a139-init-evolution-review.md`](2026-07-18-origin-0.13.0-into-main-7c1a139-init-evolution-review.md)
+- [`2026-07-18-origin-main-into-0.13.0-43e86ad.md`](2026-07-18-origin-main-into-0.13.0-43e86ad.md)
+- [`2026-07-18-origin-main-43e86ad-init-evolution-review.md`](2026-07-18-origin-main-43e86ad-init-evolution-review.md)
+- [`2026-07-17-pi-sdk-0-80-10-init-evolution-review.md`](2026-07-17-pi-sdk-0-80-10-init-evolution-review.md)
+- [`2026-07-17-origin-main-merge.md`](2026-07-17-origin-main-merge.md)
+- [`2026-07-17-init-evolution-review.md`](2026-07-17-init-evolution-review.md)
+- [`2026-07-17-frontend-implementation-m4-m6.md`](2026-07-17-frontend-implementation-m4-m6.md)
+- [`2026-07-17-frontend-implementation-m3-repair.md`](2026-07-17-frontend-implementation-m3-repair.md)
+- [`2026-07-17-frontend-implementation-m2-writer-trace.md`](2026-07-17-frontend-implementation-m2-writer-trace.md)
+- [`2026-07-17-frontend-implementation-m0-baseline.md`](2026-07-17-frontend-implementation-m0-baseline.md)
+- [`2026-07-17-frontend-implementation-contract-v1.md`](2026-07-17-frontend-implementation-contract-v1.md)
+- [`2026-07-17-backend-test-result-classification-m2.md`](2026-07-17-backend-test-result-classification-m2.md)
+- [`2026-07-17-backend-test-m4-converge-smoke.md`](2026-07-17-backend-test-m4-converge-smoke.md)
+- [`2026-07-17-backend-test-m0-template-runtime-drift.md`](2026-07-17-backend-test-m0-template-runtime-drift.md)
+- [`2026-07-17-backend-test-init-evolution-review.md`](2026-07-17-backend-test-init-evolution-review.md)
+- [`2026-07-17-backend-test-execution-contract-m1.md`](2026-07-17-backend-test-execution-contract-m1.md)
+- [`2026-07-17-backend-test-case-manifest-m3.md`](2026-07-17-backend-test-case-manifest-m3.md)
+- [`2026-07-17-source-target-structure-alignment-partial-failed.md`](2026-07-17-source-target-structure-alignment-partial-failed.md)
+- [`2026-07-16-0.13.0-init-evolution-review.md`](2026-07-16-0.13.0-init-evolution-review.md)
 - [`2026-07-17-weekly-progress-summary-last-tue-to-today.md`](2026-07-17-weekly-progress-summary-last-tue-to-today.md)
 - [`2026-07-17-backend-test-analysis-contract-artifact.md`](2026-07-17-backend-test-analysis-contract-artifact.md)
 - [`2026-07-17-backend-test-analysis-contract-init-evolution-review.md`](2026-07-17-backend-test-analysis-contract-init-evolution-review.md)
 - [`2026-07-17-review-findings-remediation-init-evolution-review.md`](2026-07-17-review-findings-remediation-init-evolution-review.md)
 - [`2026-07-16-dag-source-binding-recovery-init-evolution-review.md`](2026-07-16-dag-source-binding-recovery-init-evolution-review.md)
+- [`2026-07-16-repair-artifact-pass-normalization.md`](2026-07-16-repair-artifact-pass-normalization.md)
+- [`2026-07-16-observe-inspector-node-consistency.md`](2026-07-16-observe-inspector-node-consistency.md)
+- [`2026-07-16-init-natural-language-routing-init-evolution-review.md`](2026-07-16-init-natural-language-routing-init-evolution-review.md)
+- [`2026-07-16-decision-envelope-prompt-contract.md`](2026-07-16-decision-envelope-prompt-contract.md)
+- [`2026-07-16-decision-envelope-fence-tolerance.md`](2026-07-16-decision-envelope-fence-tolerance.md)
 - [`2026-07-16-frontend-mock-node-init-evolution-review.md`](2026-07-16-frontend-mock-node-init-evolution-review.md)
 - [`2026-07-16-frontend-demand-auto-routing-init-evolution-review.md`](2026-07-16-frontend-demand-auto-routing-init-evolution-review.md)
 - [`2026-07-16-frontend-mock-data-workflow.md`](2026-07-16-frontend-mock-data-workflow.md)
@@ -58,6 +98,12 @@
 - [`dogfood-preflight-static-20260709090443.md`](dogfood-preflight-static-20260709090443.md)
 - [`current-capability-summary.md`](current-capability-summary.md)
 - [`2026-07-14-website-docs-ia-init-evolution-review.md`](2026-07-14-website-docs-ia-init-evolution-review.md)
+- [`2026-07-14-observe-ui-r5.md`](2026-07-14-observe-ui-r5.md)
+- [`2026-07-14-observe-ui-r4.md`](2026-07-14-observe-ui-r4.md)
+- [`2026-07-14-observe-ui-r3.md`](2026-07-14-observe-ui-r3.md)
+- [`2026-07-14-observe-ui-r2.md`](2026-07-14-observe-ui-r2.md)
+- [`2026-07-14-observe-ui-r1.md`](2026-07-14-observe-ui-r1.md)
+- [`2026-07-14-architecture-docs-init-evolution-review.md`](2026-07-14-architecture-docs-init-evolution-review.md)
 - [`2026-07-14-website-docs-ia-and-converge.md`](2026-07-14-website-docs-ia-and-converge.md)
 - [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md)
 - [`2026-07-14-docs-living-docs-calibration.md`](2026-07-14-docs-living-docs-calibration.md)