@tea-agent/loop-agent 0.10.0-alpha.0 → 0.11.0

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

@@ -8,6 +8,7 @@ import { BASELINE_FORBIDDEN_PATHS } from "./governance-constants.js";
 import { resolveAdapter } from "../../adapters/index.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
 import { buildAuthoritySurfaceAuditNode, buildAuthoritySurfaceGateNode, resolveAuthoritySurfaceAudit, } from "./authority-surface.js";
+import { applySddEmbeddedEnhancements, probeRepoLocalSddSkills, } from "./sdd-embedded.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { materializeTaskReferenceDocs } from "../../task/source-references.js";
 import { resolveVerifyPreset } from "../../executors/shell-verification.js";
@@ -535,6 +536,7 @@ export async function loadTaskHybridSources(repoRoot, taskId) {
         enabledExecutors: resolveEnabledExecutors(manifest.executors),
         executorModelMatrix: resolveExecutorModelMatrices(manifest),
         verifyCommands,
+        sddEmbeddedSkills: await probeRepoLocalSddSkills(repoRoot),
     };
 }
 function mergeFinalVerifyCommands(repoRoot, taskConfig, adapterCommands) {
@@ -736,6 +738,7 @@ export function buildStandardHybridDagFromTask(sources) {
             },
         ],
     };
+    applySddEmbeddedEnhancements(spec, sources.sddEmbeddedSkills ?? new Set());
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;
@@ -1029,212 +1032,11 @@ function buildFrontendHybridDagFromTask(sources) {
     assertValidDagSpec(spec);
     return spec;
 }
-// ---------------------------------------------------------------------------
-// Backend test DAG template
-// ---------------------------------------------------------------------------
-function buildAnalyzeInputsNode(sources) {
-    return {
-        id: "analyze-inputs-pi",
-        depends_on: [],
-        role: "planner",
-        executor: "pi",
-        complexity: "MED",
-        writePolicy: "read-only",
-        allowedPaths: commonReadOnlyPaths(sources),
-        forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Plain Markdown end-to-end test analysis contract (scope, risks, strategy highlights); no file writes.",
-        subtask_prompt: [
-            "Read the task source materials (需求.md, 开发详设.md and other references) and produce a concise end-to-end test analysis contract.",
-            "Cover: backend test scope, risk items, and strategy highlights. Identify key modules, integration points, and boundary conditions.",
-            "Read-only: do not modify code, docs, artifacts, or repository files.",
-            buildSourceContextBlock(sources),
-        ].join("\n\n"),
-    };
-}
-function buildGenerateBackendFunctionalCasesNode(sources) {
-    return {
-        id: "generate-backend-functional-cases-pi",
-        depends_on: ["analyze-inputs-pi"],
-        role: "implementer",
-        executor: "pi",
-        toolProfile: "write",
-        complexity: "MED",
-        writePolicy: "exclusive",
-        writeSet: ["testcase/md/**"],
-        allowedPaths: ["testcase/md/**"],
-        forbiddenPaths: commonForbiddenPaths(sources),
-        subtask_prompt: [
-            "Based on the upstream test analysis contract, generate structured backend functional test cases in Markdown.",
-            "Each test case ID must use the BE-<MODULE>-<NNN> format (e.g. BE-ORDER-001).",
-            "Write test case files under testcase/md/. Cover positive paths, negative paths, and boundary conditions.",
-            "Stay within writeSet. Do not write root artifacts/**.",
-            buildSourceContextBlock(sources),
-        ].join("\n\n"),
-    };
-}
-function buildReviewBackendCasesNode(sources) {
-    return {
-        id: "review-backend-cases-pi",
-        depends_on: ["generate-backend-functional-cases-pi"],
-        role: "reviewer",
-        executor: "pi",
-        complexity: "HIGH",
-        writePolicy: "read-only",
-        allowedPaths: commonReadOnlyPaths(sources),
-        forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision; followed by Findings and Coverage Assessment. No file writes.",
-        subtask_prompt: [
-            "Review the generated backend functional test cases for completeness and quality.",
-            "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
-            "Check: coverage of requirement acceptance criteria, case ID format (BE-<MODULE>-<NNN>), positive/negative/boundary coverage, and traceability to source requirements.",
-            "Any Critical/Important finding must force VERDICT: request-revision. Read-only: do not modify files.",
-            buildSourceContextBlock(sources),
-        ].join("\n\n"),
-    };
-}
-function buildGenerateBackendPytestNode(sources) {
-    return {
-        id: "generate-backend-pytest-pi",
-        depends_on: ["review-backend-cases-pi"],
-        role: "implementer",
-        executor: "pi",
-        toolProfile: "write",
-        complexity: "HIGH",
-        writePolicy: "exclusive",
-        writeSet: ["testcase/**"],
-        allowedPaths: ["testcase/**"],
-        forbiddenPaths: commonForbiddenPaths(sources),
-        subtask_prompt: [
-            "Convert the reviewed backend functional test cases into pytest automation code.",
-            "Write test files under testcase/. Each functional test case ID (BE-<MODULE>-<NNN>) must map 1:1 to an automated pytest function for traceability.",
-            "Every generated test file must start with test_ prefix (e.g. test_order.py) to comply with pytest discovery.",
-            "Identify the target project's pytest conventions (conftest.py, fixture patterns, pytest.ini/pyproject.toml config) by reading existing files, but do NOT modify any existing framework files.",
-            "Only create NEW test script files. Do NOT modify conftest.py, pytest.ini, pyproject.toml, setup.cfg, __init__.py, or any other existing file.",
-            "If a file with the target name already exists under testcase/, add a numeric suffix: test_order.py → test_order_01.py → test_order_02.py. Never overwrite or append to existing files. Each test script must be a standalone file.",
-            "Stay within writeSet. Do not write root artifacts/**.",
-            buildSourceContextBlock(sources),
-        ].join("\n\n"),
-    };
-}
-function buildExecuteBackendPytestNode(sources) {
-    return {
-        id: "execute-backend-pytest-shell",
-        depends_on: ["generate-backend-pytest-pi"],
-        role: "verifier",
-        executor: "shell",
-        complexity: "LOW",
-        writePolicy: "read-only",
-        allowedPaths: commonReadOnlyPaths(sources),
-        forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Archived pytest stdout/stderr with exit codes and HTML report path; no worktree writes.",
-        subtask_prompt: "Run pytest for the backend test suite and capture results.",
-        shell: {
-            commands: [
-                "python -m pytest testcase/ --html=reports/backend-test-report.html -v",
-            ],
-            verifyEvidence: buildVerifyEvidence({
-                phase: "final",
-                quota: "full",
-                commandSource: "inline",
-                fallbackCommands: [
-                    "python -m pytest testcase/ --html=reports/backend-test-report.html -v",
-                ],
-                finalFullRequired: true,
-            }),
-            cwd: ".",
-            timeoutMs: 300000,
-        },
-    };
-}
-function buildTestRetrospectNode(sources) {
-    return {
-        id: "test-retrospect-pi",
-        depends_on: ["execute-backend-pytest-shell"],
-        role: "closeout",
-        executor: "pi",
-        toolProfile: "write",
-        complexity: "MED",
-        writePolicy: "exclusive",
-        writeSet: ["docs/test-reports/**"],
-        allowedPaths: ["docs/test-reports/**"],
-        forbiddenPaths: commonForbiddenPaths(sources),
-        subtask_prompt: [
-            "Read upstream review-backend-cases-pi review report and execute-backend-pytest-shell pytest output, then generate a test retrospective report.",
-            "Write the report under docs/test-reports/ in Markdown. The report must include:",
-            "1) Test coverage summary (total cases, pass rate, failed case analysis)",
-            "2) Review findings and their resolution status",
-            "3) Maturity rating: A (100% coverage + 100% pass + no Critical findings), B (≥80% coverage + ≥90% pass + Low findings only), C (≥60% coverage + ≥70% pass), D (below C thresholds)",
-            "Stay within writeSet. Do not write root artifacts/**.",
-            buildSourceContextBlock(sources),
-        ].join("\n\n"),
-    };
-}
-const BACKEND_TEST_DEFAULTS = {
-    ...HYBRID_DEFAULTS,
-    writePolicy: "read-only",
-};
-const BACKEND_TEST_SKILLS_BY_ROLE = {
-    planner: ["loop-agent"],
-    scout: [],
-    implementer: ["test-driven-development", "verification-before-completion"],
-    reviewer: ["requesting-code-review", "code-review-core"],
-    verifier: ["verification-before-completion", "systematic-debugging"],
-    closeout: ["loop-agent", "verification-before-completion"],
-};
-function buildBackendTestHybridDag(sources) {
-    const { taskConfig } = sources;
-    const sourceContext = buildSourceContextBlock(sources);
-    const readOnlyPaths = commonReadOnlyPaths(sources);
-    const forbiddenPaths = commonForbiddenPaths(sources);
-    const globalConstraints = [
-        ...taskConfig.hardConstraints,
-        ...(sources.constraintMarkdown
-            ? [`See 执行约束.md in task source (${sources.taskId})`]
-            : []),
-        ...STANDARD_GLOBAL_CONSTRAINTS,
-        "backend-test-dag nodes must maintain traceability from requirements to functional cases to pytest automation.",
-        "Functional test case IDs must use BE-<MODULE>-<NNN> format.",
-        "pytest execution must produce HTML reports under reports/.",
-        "pytest automation scripts must use test_ filename prefix for pytest discovery.",
-        "generate-backend-pytest-pi must only create new test files under testcase/; modifying existing framework files (conftest.py, pytest.ini, pyproject.toml) is forbidden.",
-        "If a target test filename already exists under testcase/, add a numeric suffix (_01, _02, ...); never overwrite or append to existing files.",
-        "execute-backend-pytest-shell must not modify test assertions or production code to make tests pass; test failures indicate potential implementation issues and must be reported honestly.",
-    ];
-    const spec = {
-        version: 2,
-        title: `Backend test DAG: ${taskConfig.title}`,
-        outputLanguage: sources.outputLanguage ?? DEFAULT_DAG_OUTPUT_LANGUAGE,
-        objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
-        successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
-        globalConstraints,
-        defaults: {
-            ...BACKEND_TEST_DEFAULTS,
-            contextProfile: taskConfig.contextProfile,
-        },
-        skillsByRole: BACKEND_TEST_SKILLS_BY_ROLE,
-        executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
-        tasks: [
-            buildAnalyzeInputsNode(sources),
-            buildGenerateBackendFunctionalCasesNode(sources),
-            buildReviewBackendCasesNode(sources),
-            buildGenerateBackendPytestNode(sources),
-            buildExecuteBackendPytestNode(sources),
-            buildTestRetrospectNode(sources),
-        ],
-    };
-    parseDagSpec(spec);
-    assertValidDagSpec(spec);
-    return spec;
-}
 export function buildHybridDagFromTask(sources, options = {}) {
     if (sources.taskConfig.taskKind === "frontend-implementation" ||
         options.template === "frontend-implementation") {
         return buildFrontendHybridDagFromTask(sources);
     }
-    if (sources.taskConfig.taskKind === "backend-test" ||
-        options.template === "backend-test-dag") {
-        return buildBackendTestHybridDag(sources);
-    }
     const standard = buildStandardHybridDagFromTask(sources);
     const template = options.template ?? "standard-dag";
     if (template === "standard-dag")
@@ -1332,6 +1134,7 @@ function buildReviewGatedHybridDag(standard, sources) {
     const closeout = getTaskOrThrow(spec, "closeout-pi");
     replaceTask(spec, cloneTask(closeout, { depends_on: ["review-gate-shell"] }));
     spec.tasks.splice(spec.tasks.length - 1, 0, buildReviewNode(sources), buildReviewGateNode(sources));
+    applySddEmbeddedEnhancements(spec, sources.sddEmbeddedSkills ?? new Set());
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;
@@ -1601,6 +1404,7 @@ function buildSupervisedHybridDag(standard, sources) {
             cloneTask(closeout, { depends_on: ["decision-pi"] }),
         ],
     };
+    applySddEmbeddedEnhancements(spec, sources.sddEmbeddedSkills ?? new Set());
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;

package/dist/workflows/dag/sdd-embedded.js

@@ -0,0 +1,128 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+/**
+ * SDD embedded-mode optional enhancement.
+ *
+ * When the target project ships repo-local `SDD-*` skills (under
+ * `.agents/skills/<name>/SKILL.md`), loop-agent can
+ * reuse them as knowledge/method references inside individual DAG nodes. This
+ * module probes those repo-local paths and, on a hit, appends the matched skill
+ * name to the mapped node's `task.skills` (so it flows through the existing
+ * run-owned skill snapshot via `resolveDagNodeSkills`) plus a loop-agent-managed
+ * embedded-mode constraint block to the node prompt.
+ *
+ * loop-agent always owns process/state/verification/closeout. SDD state
+ * transitions, confirmation gates, and archival are explicitly forbidden inside
+ * the embedded-mode block.
+ */
+/** The three SDD skills that may be reused as repo-local knowledge. */
+export const SDD_SKILL_NAMES = [
+    "SDD-requirement-analysis",
+    "SDD-design-analysis",
+    "SDD-implementation-test-review",
+];
+/**
+ * DAG node id -> mapped SDD skill name. `verify-pi` is present in standard and
+ * review-gated templates; supervised verification stays shell-based. The init skills
+ * (`SDD-code-spec-init`, `SDD-project-how-to-spec-init`) are intentionally
+ * absent: they are never auto-executed inside a normal feature DAG.
+ */
+export const SDD_NODE_SKILL_MAP = {
+    "contract-pi": "SDD-requirement-analysis",
+    "plan-pi": "SDD-design-analysis",
+    "implement-pi": "SDD-implementation-test-review",
+    "repair-pi": "SDD-implementation-test-review",
+    "verify-pi": "SDD-implementation-test-review",
+    "review-pi": "SDD-implementation-test-review",
+};
+/** DAG node id -> SDD phase label injected into the constraint block. */
+export const SDD_NODE_PHASE_LABEL = {
+    "contract-pi": "需求",
+    "plan-pi": "设计",
+    "implement-pi": "实现",
+    "repair-pi": "修复",
+    "verify-pi": "验证",
+    "review-pi": "审查",
+};
+/** Fence tokens used to delimit the embedded-mode constraint block. */
+export const SDD_EMBEDDED_MODE_OPEN = "[SDD-EMBEDDED-MODE]";
+export const SDD_EMBEDDED_MODE_CLOSE = "[/SDD-EMBEDDED-MODE]";
+const SDD_SKILL_CANDIDATE_BASES = [".agents/skills"];
+/**
+     * Probe the target project repo for repo-local SDD skills. Only the canonical
+     * repo-relative `.agents/skills` base is checked; this deliberately does NOT reuse
+ * the skill loader candidate list (which also falls back to user-level and
+ * bundled package skills) so user-level/package skills never trigger
+ * auto-enhancement.
+ *
+ * Returns the set of SDD skill names whose `SKILL.md` exists under at least one
+ * repo-local base. Returns an empty set when `repoRoot` is absent so callers
+ * that do not pass a repo root preserve byte-level default output.
+ */
+export async function probeRepoLocalSddSkills(repoRoot) {
+    if (!repoRoot)
+        return new Set();
+    const hits = new Set();
+    for (const name of SDD_SKILL_NAMES) {
+        for (const base of SDD_SKILL_CANDIDATE_BASES) {
+            const candidate = path.join(repoRoot, base, name, "SKILL.md");
+            try {
+                await access(candidate);
+                hits.add(name);
+                break;
+            }
+            catch {
+                // not present at this candidate base; try the next
+            }
+        }
+    }
+    return hits;
+}
+/**
+ * Build the loop-agent-managed embedded-mode constraint block for a node. The
+ * block declares DAG-node-boundary priority and forbids SDD state transitions,
+ * confirmation gates, working_requirements_status updates, and archival.
+ *
+ * Returns `null` for unmapped node ids (e.g. scouts, shell gates, closeout).
+ */
+export function buildSddEmbeddedConstraintBlock(nodeId) {
+    const phase = SDD_NODE_PHASE_LABEL[nodeId];
+    if (!phase)
+        return null;
+    return [
+        SDD_EMBEDDED_MODE_OPEN,
+        `当前 DAG 节点: ${nodeId}，阶段: ${phase}`,
+        "loop-agent 拥有流程、状态、验证与收口控制权；SDD skill 仅作 repo-local 知识与方法参考。",
+        "禁止：更新 working_requirements_status.md；推进 SDD 阶段；触发 SDD 用户确认；执行归档。",
+        "优先级：本节点的读写边界、当前阶段与输出契约优先于任何 SDD 指令冲突。",
+        "implement/repair writer 仍必须服从当前 writeSet/allowedPaths/forbiddenPaths；不得把 ai_workspace 加入隐式写范围，也不得解析或写入 SDD 工作区状态机。",
+        SDD_EMBEDDED_MODE_CLOSE,
+    ].join("\n");
+}
+/**
+ * Apply SDD embedded-mode enhancements in place on a fully-constructed DAG spec.
+ *
+ * For each mapped task whose mapped skill is present in the hit set:
+ *  - append the skill name to `task.skills` (de-duplicated, order-preserving);
+ *  - append the constraint block to the end of `task.subtask_prompt` (once).
+ *
+ * When the hit set is empty this is a no-op, preserving the default DAG byte
+ * for byte. The function is idempotent.
+ */
+export function applySddEmbeddedEnhancements(spec, hitSkills) {
+    if (hitSkills.size === 0)
+        return;
+    for (const task of spec.tasks) {
+        const mapped = SDD_NODE_SKILL_MAP[task.id];
+        if (!mapped || !hitSkills.has(mapped))
+            continue;
+        const existing = task.skills ?? [];
+        if (!existing.includes(mapped)) {
+            task.skills = [...existing, mapped];
+        }
+        const block = buildSddEmbeddedConstraintBlock(task.id);
+        if (block && !task.subtask_prompt.includes(SDD_EMBEDDED_MODE_OPEN)) {
+            task.subtask_prompt = `${task.subtask_prompt}\n\n${block}`;
+        }
+    }
+}

package/dist/workflows/dag/skill-instructions.js

@@ -41,11 +41,12 @@ function buildSkillCandidatePaths(input) {
     }
     const piSkillsDir = path.join(input.homeDir, ".pi", "agent", "skills");
     candidates.push(normalizeCandidate(path.join(piSkillsDir, input.name, "SKILL.md")), normalizeCandidate(path.join(piSkillsDir, `${input.name}.md`)));
-    candidates.push(normalizeCandidate(path.join(input.cwd, "skills", input.name, "SKILL.md")));
-    // Agent-compatible project path (e.g. OpenCode). `skills/` stays the primary
-    // loop-agent repo-local path; `.agents/skills` is searched after it and before
-    // bundled skills so a project with only the mirror can still resolve.
+    // Canonical target-project repo-local skill path.
     candidates.push(normalizeCandidate(path.join(input.cwd, ".agents", "skills", input.name, "SKILL.md")));
+    // Source-repository compatibility: the loop-agent package itself still ships
+    // bundled skills under `skills/`, and local source development may resolve them
+    // before the package fallback is found.
+    candidates.push(normalizeCandidate(path.join(input.cwd, "skills", input.name, "SKILL.md")));
     if (input.name === "loop-agent") {
         candidates.push(normalizeCandidate(path.join(input.cwd, "skill", "SKILL.md")));
     }

package/docs/README.md

@@ -10,6 +10,7 @@
 
 ## 核心文档
 
+- `design/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计与实现依据
 - `development-principles.md` — 仓库开发原则
 - `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
 - `architecture/README.md` — 架构文档目录索引与阅读路径

package/docs/agent-dag-runner.md

@@ -21,11 +21,11 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 
 ## Skills
 
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `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。
 
-`loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
+目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
 
 ## Artifacts
 

package/docs/architecture/runtime-boundaries.md

@@ -161,10 +161,13 @@ 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-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`。
 
+`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 并存；两者均不删除或弱化。
+
 ### 验证命令
 
 ```bash

package/docs/design/README.md

@@ -25,6 +25,7 @@
 
 | 文档 | 用途 |
 |---|---|
+| `2026-07-14-loop-agent-self-update-notifier.md` | loop-agent CLI 自更新提醒设计（设计已确认，尚未实现；覆盖用户级状态、npm global 来源证明、精确安装与验证边界） |
 | `DESIGN-cursor.md` | Observe 暖白运行控制台采用的 Cursor 风格视觉参考与设计 token |
 | `DESIGN-lovable.md` | Lovable 风格的暖色视觉系统参考 |
 

package/docs/development-principles.md

@@ -31,7 +31,7 @@ loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而
 
 - 源码：`src/`
 - 测试：`test/`
-- Skill 指令：`skills/`
+- Skill 指令：源码仓库和 npm 包内置在 `skills/`，目标项目 repo-local skills 在 `.agents/skills/`
 - 验证与维护脚本：`scripts/`
 - 治理与交接产物：`docs/`
 

package/docs/exec-plans/active/README.md

@@ -6,6 +6,6 @@
 
 当前 active execution plan：
 
-- （无）
+- 暂无。
 
-- 已归档：`../completed/2026-07-12-observe-warm-console-redesign.md`、`../completed/2026-07-14-website-docs-ia-and-converge.md`、`../completed/2026-07-13-versioned-self-hosting-bootstrap.md`、`../completed/2026-07-12-pi-only-agent-runtime.md`、第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。
+- 已归档：`../completed/2026-07-14-init-canonical-layout.md`、`../completed/2026-07-12-observe-warm-console-redesign.md`、`../completed/2026-07-14-website-docs-ia-and-converge.md`、`../completed/2026-07-13-versioned-self-hosting-bootstrap.md`、`../completed/2026-07-12-pi-only-agent-runtime.md`、第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。

package/docs/exec-plans/completed/README.md

@@ -4,9 +4,13 @@
 
 npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
 
+- [`2026-07-14-init-canonical-layout.md`](2026-07-14-init-canonical-layout.md) — 目标项目治理资料统一到 `ai_workspace/loop-agent/` 与 `.agents/skills/`，并为旧布局提供保守安全迁移
+- [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md) — 实现 loop-agent CLI 自更新提醒，覆盖拒绝版本、精确安装、npm global 来源证明和验证收口
 - [`2026-07-12-observe-warm-console-redesign.md`](2026-07-12-observe-warm-console-redesign.md) — 以暖白、细边界和高密度信息架构重构 Observe Dashboard；多轮细节调整后按用户确认收口归档。
 - [`2026-07-14-website-docs-ia-and-converge.md`](2026-07-14-website-docs-ia-and-converge.md) — Website 文档信息架构、双树边界与 `docs-converge` 同步机制
 - [`2026-07-14-frontend-spec-source-fallback.md`](2026-07-14-frontend-spec-source-fallback.md) — 统一前端规范来源为知识库优先、失败后强制检索当前项目 `openSpec/`
+- [`2026-07-13-test-environment-stability.md`](2026-07-13-test-environment-stability.md) — 修复 Windows Git Bash、npm CLI 启动与 Git/Delivery 测试资源分类，避免验证节点反复失败并跳过 DAG 收口
+- [`2026-07-13-sdd-embedded-skills.md`](2026-07-13-sdd-embedded-skills.md) — 目标项目 repo-local SDD skills 的可选 DAG 节点嵌入增强，loop-agent 保持流程、状态与写边界控制
 - [`2026-07-13-frontend-skill-contracts.md`](2026-07-13-frontend-skill-contracts.md) — 补齐前端节点 Skill 的输入、输出、证据与阻断契约，并预留组件/设计知识库接入 TODO
 - [`2026-07-13-versioned-self-hosting-bootstrap.md`](2026-07-13-versioned-self-hosting-bootstrap.md) — 固定已发布 controller identity、冻结 run-owned skills，并由隔离候选包完成 deterministic self-hosting takeover canary
 - [`2026-07-12-pi-only-agent-runtime.md`](2026-07-12-pi-only-agent-runtime.md) — 将 DAG、Loop、Delegate 和 Worker 收敛为 Pi-only 受治理 runtime，仅保留独立的 one-shot `cursor-prompt` sidecar
@@ -54,3 +58,5 @@ npm 包携带本 README 作为目录契约。具体 completed plan 属于目标
 - [`2026-07-10-obs-009.md`](2026-07-10-obs-009.md) — stale、quiet 与 timeout-risk 诊断
 - [`2026-07-10-obs-010.md`](2026-07-10-obs-010.md) — Failure Inbox、文档、package surface 与 smoke 验证
 - [`2026-07-10-observe-ui-review-remediation.md`](2026-07-10-observe-ui-review-remediation.md) — 修复 Observe UI 事件链路、历史 run 投影、artifact 安全边界与失败状态展示
+
+- [`2026-07-13-exec-plan-lifecycle.md`](2026-07-13-exec-plan-lifecycle.md)

package/docs/feature-workflow.md

@@ -121,37 +121,27 @@ frontend-contract-pi
 ```
 
 这条链在实现前加入 design gate，并将前端静态验证与行为验证分开建模；当前 MVP 不包含独立 a11y、视觉回归或浏览器自动化 executor。
+前端 shell 验证优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，例如 `npm run typecheck`、`npm run build`、`npm test`；解析不到时再使用 adapter 验证命令和模板 fallback。
 
-后端测试任务可通过 `task.json.taskKind = "backend-test"` 或 `--profile backend-test` 选择专用模板：
+`verify-shell` 使用 adapter 根据 task verify preset/quota 解析出的最终验证命令，并把新鲜 exit code/stdout/stderr 交给后续只读 verifier。review-gated 模板继续插入：
 
 ```text
-analyze-inputs-pi
-  -> generate-backend-functional-cases-pi
-  -> review-backend-cases-pi
-  -> generate-backend-pytest-pi
-  -> execute-backend-pytest-shell
-  -> test-retrospect-pi
+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。
 
-1. **analyze-inputs-pi**：读取需求.md 和开发详设等参考文档，产出端到端测试分析契约（范围、风险、策略要点）
-2. **generate-backend-functional-cases-pi**：根据契约生成结构化后端功能测试用例（Markdown），用例 ID 带 `BE-` 前缀（如 `BE-ORDER-001`），写入 `test-cases/backend/`
-3. **review-backend-cases-pi**：评审后端功能测试用例，输出审查报告 + `VERDICT: pass` / `VERDICT: request-revision`
-4. **generate-backend-pytest-pi**：将后端功能用例转化为 pytest 自动化代码，写入 `tests/backend/`
-5. **execute-backend-pytest-shell**：执行 `pytest tests/backend/` 并生成 HTML 报告
-6. **test-retrospect-pi**：读取上游审查报告和测试报告，生成复盘报告 + 成熟度评级（A/B/C/D）
+### 可选 repo-local SDD skill 增强
 
-前端测试模板（`frontend-test-dag`）后续沿用对称命名即可接入。
-前端 shell 验证优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，例如 `npm run typecheck`、`npm run build`、`npm test`；解析不到时再使用 adapter 验证命令和模板 fallback。
+`dag run-task` 会在目标项目的 `.agents/skills/` 中探测三个可选 skill：
 
-`verify-shell` 使用 adapter 根据 task verify preset/quota 解析出的最终验证命令，并把新鲜 exit code/stdout/stderr 交给后续只读 verifier。review-gated 模板继续插入：
+- `SDD-requirement-analysis` → `contract-pi`
+- `SDD-design-analysis` → `plan-pi`
+- `SDD-implementation-test-review` → `implement-pi`、`repair-pi`、`verify-pi`、`review-pi`
 
-```text
-verify-shell -> verify-pi -> review-pi -> review-gate-shell -> closeout-pi
-```
+命中时，skill 通过节点 `skills` 进入现有 resolved instruction 和 run-owned snapshot 链路，并在节点任务中收到 embedded-mode 约束：只为当前 DAG 阶段提供知识、规范与方法，不得更新 `working_requirements_status.md`、推进 SDD 状态、触发 SDD 用户确认或执行归档。节点的读写边界、当前阶段与输出契约优先；writer 仍只允许写入显式 `writeSet`。`SDD-code-spec-init` 与 `SDD-project-how-to-spec-init` 不会在普通功能 DAG 中自动运行。
 
-supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
+探测不到这些 repo-local skills 时，DAG 不追加节点 skill 或约束块，保持当前默认流程。用户级或 npm 包内同名 skill 也不会作为自动启用信号。
 
 源码参考：
 
@@ -159,6 +149,7 @@ supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验
 - `src/commands/dag-validate.ts`
 - `src/commands/run-dag.ts`
 - `src/workflows/dag/init-hybrid.ts`
+- `src/workflows/dag/sdd-embedded.ts`
 - `src/workflows/dag/runner.ts`
 
 监督 agent 仍负责：
@@ -171,6 +162,21 @@ supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验
 
 声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
 
+## Exec-plan 生命周期
+
+exec-plan 不是手工文档；它有确定性 CLI 生命周期，并与 `dag run-task` 共享同一索引校验源。
+
+```bash
+loop-agent plan create <plan-id> "<title>"
+loop-agent plan complete <plan-id> --summary "<summary>"
+loop-agent plan check
+```
+
+- `new-task` 不自动绑定 exec-plan；微小任务仍可不创建计划。
+- `plan create` 优先读取目标项目 `<governanceRoot>/templates/exec-plan.md`，不存在时回退到发布包内置模板；create/complete 同步 active/completed 索引，拒绝重复 id、路径穿越与不安全文件名，多文件操作均具备回滚保护。
+- `dag run-task` 在生成 DAG 草稿前运行 `plan check` 同源校验，索引漂移立即失败；空仓库与索引一致的仓库不受影响。
+- `plan list`（只读）与 `docs archive`（兼容入口）保留；`scripts/check-exec-plan-index-sync.sh` 仍作为独立最终防线。
+
 ## 已移除的顺序工作流
 
 历史 Level 1 顺序 command surface 已从公开工作流移除。新工作不要用 `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study`。

package/docs/harness-methodology-debugging.md

@@ -88,7 +88,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 ### Phase 4：实现
 
-1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `docs/harness-methodology-tdd.md`）
+1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `harness-methodology-tdd.md`）
 2. **实现单一修复** — 解决已识别的根因，一次一个改动，不顺手重构
 3. **验证修复** — 测试通过？其他测试没坏？问题真的解决了？
 4. **如果修复无效**：

package/docs/harness-methodology-tdd.md

@@ -125,6 +125,6 @@ npm test path/to/test.test.ts
 
 ## 参考
 
-- Harness 工作流：`docs/feature-workflow.md`
-- 验证矩阵：`docs/verification-matrix.md`
-- Sprint Contract 模板：`docs/templates/sprint-contract.md`
+- Harness 工作流：`feature-workflow.md`
+- 验证矩阵：`verification-matrix.md`
+- Sprint Contract 模板：`templates/sprint-contract.md`