@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0

package/dist/workflows/dag/types.js

@@ -2,13 +2,9 @@ import { z } from "zod";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
 import { dagRetryPolicySchema } from "./retry-policy.js";
 export const dagComplexitySchema = z.enum(["HIGH", "MED", "LOW"]);
-export const dagNodeExecutorSchema = z.enum([
-    "pi",
-    "shell",
-    "static",
-]);
+export const dagNodeExecutorSchema = z.enum(["pi", "shell", "static"]);
 export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
-export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = 'executorModels.cursor is no longer supported; use executorModels.pi only';
+export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = "executorModels.cursor is no longer supported; use executorModels.pi only";
 export const dagToolProfileSchema = z.enum(["read-only", "write"]);
 export const dagShellPresetSchema = z.enum(["loop-agent-standard-verify"]);
 export const dagVerifyQuotaSchema = z.enum(["1", "3", "full"]);
@@ -16,10 +12,7 @@ export const dagVerifyStrategySchema = z
     .object({
     intermediateQuota: dagVerifyQuotaSchema.optional(),
     finalQuota: z.literal("full").optional().default("full"),
-    focusedCommandSource: z
-        .literal("adapter")
-        .optional()
-        .default("adapter"),
+    focusedCommandSource: z.literal("adapter").optional().default("adapter"),
 })
     .optional();
 export const dagShellVerifyEvidenceSchema = z.object({
@@ -69,6 +62,30 @@ export const dagVerdictGateSchema = z.object({
     lineMode: z.enum(["first-non-empty", "first-verdict-line"]).optional(),
     label: z.string().min(1).optional(),
 });
+export const dagRequirementCoverageGateSchema = z.object({
+    fromNodeIds: z
+        .array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fromNodeIds must be kebab-case"))
+        .min(1),
+    requiredIds: z
+        .array(z
+        .string()
+        .regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/, "requiredIds must use REQ-*, BR-*, or AC-* identifiers"))
+        .min(1),
+    label: z.string().min(1).optional(),
+});
+export const dagJsonArtifactSchemaIdSchema = z.enum([
+    "backend-test-analysis-v1",
+    "backend-test-execution-v1",
+    "backend-test-result-v1",
+    "backend-test-case-manifest-v1",
+    "frontend-implementation-contract-v1",
+]);
+export const dagJsonArtifactGateSchema = z.object({
+    fromNodeId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    schemaId: dagJsonArtifactSchemaIdSchema,
+    artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
+    outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
+});
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
     .union([z.literal(1), z.literal(2), z.literal(3)])
@@ -109,8 +126,12 @@ export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),
     preset: dagShellPresetSchema.optional(),
     verdictGate: dagVerdictGateSchema.optional(),
+    requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
+    jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),
+    /** fail (default): any nonzero command fails the node. record: finish node FINISHED with failure facts for downstream assess/repair. */
+    nonZeroExitPolicy: z.enum(["fail", "record"]).optional(),
     envAllowlist: z.array(z.string()).optional(),
     timeoutMs: z.number().optional(),
     cwd: z.string().optional(),
@@ -147,6 +168,12 @@ export const dagDynamicExpansionSchema = z.object({
         .string()
         .regex(/^[a-z][a-z0-9-]*$/, "childIdPrefix must be kebab-case"),
     childTask: dagDynamicExpansionChildTaskSchema,
+    tokenBudget: z
+        .object({
+        maxTokensPerCase: z.number().int().positive().optional(),
+        maxTotalTokens: z.number().int().positive().optional(),
+    })
+        .optional(),
 });
 export const dagDynamicReductionSchema = z.object({
     type: z.literal("verified_findings_report"),
@@ -176,9 +203,7 @@ export const dagDynamicConditionSchema = z.object({
         .optional(),
 });
 export const dagDynamicLoopBodyTaskSchema = z.object({
-    id: z
-        .string()
-        .regex(/^[a-z][a-z0-9-]*$/, "body task id must be kebab-case"),
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/, "body task id must be kebab-case"),
     dependsOn: z.array(z.string()).default([]),
     executor: dagNodeExecutorSchema.default("pi"),
     role: dagRoleSchema.optional(),
@@ -265,11 +290,37 @@ export const dagExecutorModelsSchema = z
     .strict();
 export const dagOutputLanguageSchema = z.enum(["zh-CN", "en"]);
 export const DEFAULT_DAG_OUTPUT_LANGUAGE = "zh-CN";
+export const dagEvaluationBindingSchema = z
+    .object({
+    campaignId: z.string().min(1),
+    candidateId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
+    bundleHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    seed: z.number().int().nonnegative(),
+    split: z.enum(["public", "private", "held_out"]).optional(),
+    taskRef: z.string().min(1).optional(),
+})
+    .strict();
+export const dagSourceBindingSchema = z.object({
+    schemaVersion: z.literal(1),
+    taskId: z.string().min(1),
+    sources: z
+        .array(z.object({
+        kind: z.enum(["requirement", "constraint", "reference"]),
+        path: z.string().min(1),
+        sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
+    }))
+        .min(1),
+    requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
+});
 export const dagSpecSchema = z
     .object({
     version: dagVersionSchema,
     title: z.string().min(1),
     runtimeContract: dagRuntimeContractSchema.optional(),
+    evaluation: dagEvaluationBindingSchema.optional(),
+    sourceBinding: dagSourceBindingSchema.optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
     successCriteria: z.array(z.string()).optional(),
@@ -282,6 +333,13 @@ export const dagSpecSchema = z
     tasks: z.array(dagTaskSchema).min(1),
 })
     .superRefine((spec, ctx) => {
+    if (spec.evaluation && spec.version !== 3) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "evaluation requires DagSpec version 3",
+            path: ["evaluation"],
+        });
+    }
     if (spec.runtimeContract && spec.version !== 3) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,

package/dist/workflows/dag/upstream-artifacts.js

@@ -37,6 +37,7 @@ export function relocateNodeArtifactPaths(node, oldRunDir, newRunDir) {
     };
     node.stdoutArtifactPath = rewrite(node.stdoutArtifactPath);
     node.assistantArtifactPath = rewrite(node.assistantArtifactPath);
+    node.structuredArtifactPath = rewrite(node.structuredArtifactPath);
     node.nodeRecordPath = rewrite(node.nodeRecordPath);
 }
 export function relocateConvergenceArtifactPaths(convergence, oldRunDir, newRunDir) {

package/dist/workflows/dag/validate.js

@@ -12,6 +12,7 @@ const GOVERNANCE_WARNING_TYPES = new Set([
     "shell-verdict-gate-grep-pattern",
     "shell-verdict-gate-multi-command-state",
     "shell-verdict-gate-handwritten-inline",
+    "orphan-writer-source-binding",
 ]);
 const ROOT_ARTIFACT_PATH_PROBES = [
     "artifacts/修改记录.md",
@@ -238,6 +239,25 @@ function validateRepairArtifactGateConfig(task, spec, issues) {
         });
     }
 }
+function validateRequirementCoverageGateConfig(task, spec, issues) {
+    const gate = task.shell?.requirementCoverageGate;
+    if (!gate)
+        return;
+    if (task.executor !== "shell") {
+        issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate requires executor=shell` });
+        return;
+    }
+    const dependencyIds = new Set(task.depends_on);
+    for (const fromNodeId of gate.fromNodeIds) {
+        if (!dependencyIds.has(fromNodeId)) {
+            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate.fromNodeIds entry "${fromNodeId}" must appear in depends_on` });
+        }
+        const upstream = spec.tasks.find((candidate) => candidate.id === fromNodeId);
+        if (upstream?.executor === "shell") {
+            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate source "${fromNodeId}" must be a non-shell node` });
+        }
+    }
+}
 function validateShellVerdictGateGovernance(task, commands, issues) {
     if (task.executor !== "shell") {
         return;
@@ -406,7 +426,7 @@ function validateShellTaskConfig(task, spec, issues) {
         return;
     }
     const commands = resolveShellCommands(shell);
-    if (commands.length === 0) {
+    if (commands.length === 0 && !shell.jsonArtifactGate) {
         issues.push({
             type: "missing-shell-commands",
             message: `shell task ${task.id} requires shell.preset, shell.verdictGate, and/or non-empty shell.commands`,
@@ -452,9 +472,46 @@ function validateShellTaskConfig(task, spec, issues) {
         });
     }
     validateVerdictGateConfig(task, spec, issues);
+    validateRequirementCoverageGateConfig(task, spec, issues);
+    if (shell.jsonArtifactGate && !task.depends_on.includes(shell.jsonArtifactGate.fromNodeId)) {
+        issues.push({
+            type: "missing-dependency",
+            message: `shell task ${task.id} jsonArtifactGate source ${shell.jsonArtifactGate.fromNodeId} must be a direct dependency`,
+        });
+    }
     validateRepairArtifactGateConfig(task, spec, issues);
     validateShellVerdictGateGovernance(task, commands, issues);
 }
+function hasReadOnlyPlannerAncestor(spec, writer) {
+    const taskById = new Map(spec.tasks.map((task) => [task.id, task]));
+    const pending = [...writer.depends_on];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const id = pending.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const task = taskById.get(id);
+        if (!task)
+            continue;
+        if (task.executor === "pi" && task.role === "planner" && resolveWritePolicy(task, spec) === "read-only")
+            return true;
+        pending.push(...task.depends_on);
+    }
+    return false;
+}
+function validateWriterSourceBinding(spec, issues) {
+    if (spec.version < 3 || spec.sourceBinding)
+        return;
+    for (const task of spec.tasks) {
+        if (resolveWritePolicy(task, spec) !== "exclusive" || hasReadOnlyPlannerAncestor(spec, task))
+            continue;
+        issues.push({
+            type: "orphan-writer-source-binding",
+            message: `task ${task.id} is an exclusive writer without source binding or a read-only planner ancestor; recovery/partial writer DAGs must bind authoritative task sources`,
+        });
+    }
+}
 function validateStaticTaskConfig(task, issues) {
     if (task.executor !== "static") {
         return;
@@ -579,6 +636,7 @@ export function validateDagSpec(spec) {
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);
+    validateWriterSourceBinding(spec, issues);
     return issues;
 }
 export function assertValidDagSpec(spec, options = {}) {

package/docs/README.md

@@ -10,7 +10,7 @@
 
 ## 核心文档
 
-- `design/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计与实现依据
+- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
 - `development-principles.md` — 仓库开发原则
 - `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
 - `architecture/README.md` — 架构文档目录索引与阅读路径
@@ -25,6 +25,8 @@
 - `loop-agent-harness.md` — runtime 与 command surface 概览
 - `agent-dag-runner.md` — Agent DAG runner 指南
 - `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
+- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
+- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
 - `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
 - `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
 
@@ -79,8 +81,9 @@
 - `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
 - `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
 - `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
-- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
-- `templates/adr.md` — 架构决策记录（ADR）
+- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
+- `templates/branch-merge-report.md` — 跨分支合并的功能保留、冲突解析、init/update 与 package surface 审计模板
+- `templates/adr.md` — 架构决策记录（ADR）
 
 ## 维护
 

package/docs/agent-dag-recovery-playbook.md

@@ -6,6 +6,8 @@
 
 Agent DAG **recovery planning 是只读、派生、advisory** 的。`dag report` 与 `buildDagDecisionGateEvidence()` 从 `.harness/dag-runs/` 的 canonical facts 聚合 `normalizedFailureCategory` → `recoveryRecommendation`，供人工或 Decision Gate prompt 消费。
 
+中断后不要从上游摘要手工生成 impl-only DAG。先修复 `.harness/tasks/<task-id>/source/` 或计划，再对同一 task 重新执行 `dag run-task`、严格 `dag validate` 和新的 `run-dag`。新生成的完整 DAG 会重新冻结 `sourceBinding` 并经过 contract/scout/plan/gate；v3 孤立 writer 如果既无来源绑定、也无只读 planner 上游，会被 strict governance 拒绝。完整规则见 [`design/dag-source-binding-and-recovery.md`](design/dag-source-binding-and-recovery.md)。
+
 Production Readiness v0.1 在 normalized DAG category 之上增加 product-line routing。Report 与 doctor 输出应保留 raw DAG fact 并派生，不重写已完成 facts：
 
 ```text
@@ -15,7 +17,7 @@ product_line_failure_category
 recommended_follow_up
 ```
 
-Product-line taxonomy 定义见 `docs/design/state-and-failure-taxonomy.md`。
+Product-line taxonomy 定义见 `ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
 
 ### 前端设计门禁专用恢复路径
 
@@ -80,7 +82,7 @@ Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-de
 
 ## `dag report --json` schema 锁定
 
-- **Schema 文件**：`docs/templates/agent-dag-report.schema.json`
+- **Schema 文件**：`ai_workspace/loop-agent/templates/agent-dag-report.schema.json`
 - **Envelope**：`{ schemaVersion: 1, runs: DagRunReportEntry[] }`
 - **稳定消费字段**（Decision Gate / tooling 应依赖）：`primaryFailure`、`primaryRecovery`、`downstreamSkippedNodes`、`recoveryRecommendation`、`normalizedFailureCategory`；node 级 `decisionEnvelope`、`artifacts`；paused 级 `pausedByNodeId`、`pauseReason`
 - **测试**：`./test/dag-report.test.ts` §`dag report JSON schema contract` 对 fixture run 做 schema 校验
@@ -144,7 +146,7 @@ Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-de
 3. **Blocked Downstream / Skipped Nodes** — `downstreamSkippedNodes`
 4. **Recommended Operator Action** — 面向 operator 的步骤摘要
 
-保存 handoff 时重定向到平台临时目录或 `docs/reports/`，不要写入 `.harness/dag-runs/`。
+保存 handoff 时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`，不要写入 `.harness/dag-runs/`。
 
 ## Decision Gate 消费约定
 

package/docs/agent-dag-runner.md

@@ -46,11 +46,11 @@ planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-
 
 ## Skills
 
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `.agents/skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
 
-执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `docs/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
+执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `ai_workspace/loop-agent/.agents/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
 
-目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
+目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `.agents/skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
 
 ## Artifacts
 

package/docs/architecture/README.md

@@ -15,12 +15,12 @@
 
 ## 事实与规划的区分
 
-- **当前事实源**：`src/` 源码、发布 CLI、`docs/exec-plans/completed/`、`docs/reports/current-capability-summary.md`、ADR 0001–0003。
-- **规划/设计输入**：`docs/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
+- **当前事实源**：`src/` 源码、发布 CLI、`ai_workspace/loop-agent/exec-plans/completed/`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0003。
+- **规划/设计输入**：`ai_workspace/loop-agent/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
 - 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
 
 ## 与其他文档的分工
 
 - 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
 - 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
-- 本目录文档随发布包发布（npm `files` 显式条目 + `docs/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `ai_workspace/loop-agent/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。

package/docs/architecture/dag-execution.md

@@ -137,4 +137,4 @@ WorkflowSpec (src/workflows/dynamic/spec.ts workflowSpecSchema)
 
 - 动态语义：`map_agent` / `verify_agent` / `reduce_agent` / `condition` / `loop_until` / `human_gate` / `command` / `artifact_transform`。
 - agent-like 节点 executor 仅 `pi` | `static`（schema 已不含 `cursor`）。
-- 未完全兑现的 runtime limits 强执法、更广 profile、Loop 原生 `workflow` action 深度编排等仍是**设计输入**，见 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。
+- 未完全兑现的 runtime limits 强执法、更广 profile、Loop 原生 `workflow` action 深度编排等仍是**设计输入**，见 `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。

package/docs/architecture/evolution.md

@@ -1,6 +1,6 @@
 # 架构演进：当前 vs 未来
 
-本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0004、`docs/exec-plans/completed/` 与 active identity plan 的 progress。
+本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0004、`ai_workspace/loop-agent/exec-plans/completed/` 与 active identity plan 的 progress。
 
 ## 当前已实现（0.11.0）
 
@@ -9,14 +9,14 @@
 | 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
 | Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
 | Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/{spec,validate,compile}.ts`、`website/docs/guides/dynamic-workflow.md` |
-| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
-| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/2026-07-12-m2-completion-audit.md` |
+| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `ai_workspace/loop-agent/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
+| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `ai_workspace/loop-agent/reports/2026-07-12-m2-completion-audit.md` |
 | Task Pool | 唯一根 `.harness/task-pool/`；**feature-scoped** state v2（`TaskPoolTaskRef`） | ADR 0002、ADR 0004 |
-| 本地多 Feature 运营 | 同仓库多 Feature 可共用 Task ID；Ready / retry / Delivery / Observe 按 Feature 隔离 | ADR 0004、`docs/progress/2026-07-15-task-pool-v2-feature-scoped-task-identity.md` |
+| 本地多 Feature 运营 | 同仓库多 Feature 可共用 Task ID；Ready / retry / Delivery / Observe 按 Feature 隔离 | ADR 0004、`ai_workspace/loop-agent/progress/2026-07-15-task-pool-v2-feature-scoped-task-identity.md` |
 | Observe | 本地只读暖白运营控制台 R1–R5（derived）；canonical Task route 为 feature-scoped | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]`、ADR 0004 |
 | DagSpec / repair | v3 + `runtimeContract`；显式 `repairNodeId` | `CHANGELOG.md [0.11.0]`、`dag-execution.md` |
-| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
-| 文档治理 | `docs/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |
+| 文档双树 | `website/docs/` 用法 vs `ai_workspace/loop-agent/` 治理；docs-converge | ADR 0003 |
+| 文档治理 | `ai_workspace/loop-agent/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |
 
 ### 受治理 runtime 的边界（已实现、不变式）
 
@@ -26,26 +26,26 @@
 
 ## 未来规划（第 3–6 月，**未实现**）
 
-以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
+以下能力来自 `ai_workspace/loop-agent/design/六个月规划.md` 与 `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
 
 | 未来方向 | 状态 | 规划来源 |
 | --- | --- | --- |
-| 远程 PR / CI | 规划 / 未实现 | `docs/design/六个月规划.md`（第 3 个月起） |
+| 远程 PR / CI | 规划 / 未实现 | `ai_workspace/loop-agent/design/六个月规划.md`（第 3 个月起） |
 | 线上 / 云 Worker | 规划 / 未实现 | 同上 |
 | 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
 | 多仓库平台 | 规划 / 未实现 | 同上 |
 | 组织级服务 | 规划 / 未实现 | 同上 |
 | Web Console（远端） | 规划 / 未实现 | 同上 |
-| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
 | Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
 
-> 注意：`docs/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
+> 注意：`ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
 
 ## 已收敛为 archive / 历史基线（非未来）
 
-- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
-- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
-- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
+- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`ai_workspace/loop-agent/design/archive/2026-07-12-第二月规划.md`。
+- `ai_workspace/loop-agent/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
+- 活能力短摘要在 `ai_workspace/loop-agent/reports/current-capability-summary.md`。
 
 ## 文档本体的演进边界
 

package/docs/architecture/facts-and-state.md

@@ -68,4 +68,4 @@
 
 ## init 投影的 `.harness` 入口
 
-`init --profile full` 在目标项目创建 `.harness/tasks`（directory）、`.harness/dag-runs/active`（directory）、`.harness/prompts/analyze.md`（generated）、`.harness/init-surface.json`（state）。这些是 init surface，不在 `packageExcluded`/`initExcluded` 范围；详见 `docs/init-surface.manifest.json`。
+`init --profile full` 在目标项目创建 `.harness/tasks`（directory）、`.harness/dag-runs/active`（directory）、`.harness/prompts/analyze.md`（generated）、`.harness/init-surface.json`（state）。这些是 init surface，不在 `packageExcluded`/`initExcluded` 范围；详见 `ai_workspace/loop-agent/init-surface.manifest.json`。

package/docs/architecture/runtime-boundaries.md

@@ -6,8 +6,8 @@
 
 ```text
 Skill layer
-  ├─ DAG/runtime 入口策略（skills/loop-agent/）
-  └─ Feature/Task Pool 外层 operator 路由（skills/agent-worker/）
+  ├─ DAG/runtime 入口策略（.agents/skills/loop-agent/）
+  └─ Feature/Task Pool 外层 operator 路由（.agents/skills/agent-worker/）
 
 CLI layer (src/cli/)
   └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
@@ -39,7 +39,7 @@ Governance (scripts/check-*.sh, src/governance/)
 
 ### Skill layer
 
-- **位置**：`skills/loop-agent/**` 与 `skills/agent-worker/**`
+- **位置**：`.agents/skills/loop-agent/**` 与 `.agents/skills/agent-worker/**`
 - **职责**：`loop-agent` skill 定义单个 DAG/runtime 工作的入口、硬规则与 reference 路由；`agent-worker` skill 只定义 Feature Packet、TaskSpec、Task Pool、controller pinning、自举 release train 与失败恢复的外层 operator 路由。
 - **路由边界**：DAG leaf node 不得递归启动 `agent-worker`；`agent-worker` 不得加入 `DEFAULT_SKILLS_BY_ROLE`，也不实现 executor、scheduler、prompt 或 write guard。
 - **禁止**：在入口 skill 中重复维护 CLI command 列表或与 `src/cli/catalog.ts` 冲突的事实源。
@@ -83,7 +83,7 @@ Governance (scripts/check-*.sh, src/governance/)
 
 - **位置**：`src/worker/**`，独立 `agent-worker` CLI 为 `src/worker/cli.ts`。
 - **职责**：TaskSpec 校验与物化、Task Pool batch/retry/morning report under `.harness/task-pool/`、失败路由，以及只读 Observe 事件/快照/UI；实际 DAG 执行通过 `LoopAgentClient` 启动已发布的 `loop-agent` 子进程。自 0.8.0 起该目录是唯一受支持的 Task Pool runtime root，旧路径不读取、不迁移、不合并、不重映射。
-- **controller identity**：写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前解析并冻结 schemaVersion 1 identity，包括 package name/version、绝对 entry/real entry、直接可执行 launch spec、binary SHA-256 和覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable fingerprint。expected version/fingerprint 不匹配时 fail-fast；后续 spawn 不重新查询 PATH。
+- **controller identity**：写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前解析并冻结 schemaVersion 1 identity，包括 package name/version、绝对 entry/real entry、直接可执行 launch spec、binary SHA-256 和覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint。expected version/fingerprint 不匹配时 fail-fast；后续 spawn 不重新查询 PATH。
 - **证据传播**：canonical Worker record、Task Pool run、batch/Feature、QA/final evidence 可选携带同一 identity；只有所有相关层都省略 identity 时才按 legacy evidence 接受，部分缺失或锚点不一致会拒绝。
 - **允许依赖**：TaskSpec、Task Pool、observability、Node filesystem/path 与明确的 shared/task contract；它不是第二套 executor 或 DAG kernel。
 - **禁止**：in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`。
@@ -145,7 +145,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 | `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
 | `src/worker/**` | worker-local modules, task contracts, shared, Node APIs | `src/commands/**`, `src/cli/**`, `src/application/**` |
 | `src/cli/**` | commands, adapters, shared, application（目标） | — |
-| `skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
+| `.agents/skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
 
 ## 已知过渡耦合
 
@@ -161,10 +161,10 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 |--------|----------|----------|
 | `scripts/check-architecture-boundaries.sh` | workflow/executor forbidden import，及 Worker → CLI/commands/application import | 新的未 allowlist violation |
 | `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
-| `scripts/check-exec-plan-index-sync.sh` | `docs/exec-plans/{active,completed}` 目录文件 vs 对应 `README.md` 索引 | 任一 plan 文件未在索引登记 |
+| `scripts/check-exec-plan-index-sync.sh` | `ai_workspace/loop-agent/exec-plans/{active,completed}` 目录文件 vs 对应 `README.md` 索引 | 任一 plan 文件未在索引登记 |
 | `scripts/check-skill-entry.sh` | `loop-agent` / `agent-worker` 的 frontmatter、required references、入口行数与 operator trigger vocabulary | 任一公共 skill 缺失、reference/trigger 漂移或入口超过 hard limit |
 
-版本化自举相关 exec plan：`docs/exec-plans/active/2026-07-13-versioned-self-hosting-bootstrap.md`。
+版本化自举相关 exec plan：`ai_workspace/loop-agent/exec-plans/active/2026-07-13-versioned-self-hosting-bootstrap.md`。
 
 `src/governance/exec-plans.ts` 是 exec-plan 创建、完成与索引校验的共享 TypeScript 事实源：`plan create`/`plan complete`/`plan check` 与 `dag run-task` 前置校验都调用它。`scripts/check-exec-plan-index-sync.sh` 是独立的 shell 最终防线，与 TypeScript checker 并存；两者均不删除或弱化。
 

package/docs/architecture/system-overview.md

@@ -18,7 +18,7 @@
 完整分层图、各层职责、允许/禁止的 import 方向见 `runtime-boundaries.md` §分层概览 与 §各层职责。一句话摘要：
 
 ```text
-Skill layer      skills/loop-agent、skills/agent-worker（Markdown，非 TS import）
+Skill layer      .agents/skills/loop-agent、.agents/skills/agent-worker（Markdown，非 TS import）
 CLI layer        src/cli/ — argv 解析、调用 application/handler、格式化输出
 Application      src/application/ — typed use-case（validate/run/generate DAG 等）
 Workflow runtime src/workflows/ — DAG / Dynamic / Loop 核心执行规则
@@ -86,8 +86,8 @@ workflow runtime（调度 Pi / shell / static 节点）
 | 位置 | 内容 | 权威性质 |
 | --- | --- | --- |
 | `.harness/` | 任务、DAG run、one-shot run、Task Pool、live state | 运行态事实（canonical + derived） |
-| 根目录 `docs/` | 原则、边界、计划、报告、模板 | 治理权威 |
+| 根目录 `ai_workspace/loop-agent/` | 原则、边界、计划、报告、模板 | 治理权威 |
 | `website/docs/` | 使用者/贡献者导读与操作说明 | 用法双树 |
-| `skills/` | agent 可加载的入口与 reference | 运行时可加载 |
+| `.agents/skills/` | agent 可加载的入口与 reference | 运行时可加载 |
 
 `.harness/` 内部哪些可写、哪些只读、哪些是 derived，详见 `facts-and-state.md`。

package/docs/architecture/worker-and-feature.md

@@ -27,7 +27,7 @@
 | `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
 | `binarySha256` | `actualEntry` 二进制 hash |
 | `packageVersion` | `package.json` version |
-| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
+| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
 
 关键方法：
 
@@ -66,7 +66,7 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 - review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
 - Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
 - Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
-- 权威证据：`CHANGELOG.md [0.10.0]`、`docs/reports/2026-07-12-m2-completion-audit.md`。
+- 权威证据：`CHANGELOG.md [0.10.0]`、`ai_workspace/loop-agent/reports/2026-07-12-m2-completion-audit.md`。
 
 ### Observe（只读 read model）
 
@@ -82,4 +82,4 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 
 - Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
 - Worker 不实现 executor、scheduler、prompt 或 write guard。
-- `agent-worker` skill（`skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。
+- `agent-worker` skill（`.agents/skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。