@tea-agent/loop-agent 0.33.5 → 0.33.6

package/dist/worker/delivery/package.js

@@ -1,8 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { execFile } from "node:child_process";
 import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { promisify } from "node:util";
+import { isResilientGitCommandError, runResilientGitCommand } from "../../shared/resilient-git.js";
 import YAML from "yaml";
 import { z } from "zod";
 import { controllerIdentitiesMatch, LOOP_AGENT_PACKAGE_NAME, } from "../loop-agent/loop-agent-client.js";
@@ -13,7 +12,6 @@ import { validateFeatureTaskGraph } from "../task-graph/validate.js";
 import { taskSpecSchema } from "../task-spec/schema.js";
 import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
 import { readVerifiedBundle, verifyBundleCurrentStateBindings, verifyBundleOutcomes, verifyBundleTaskSpecBindings } from "./verification-bundle.js";
-const execFileAsync = promisify(execFile);
 const hashedRefSchema = z.object({ path: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
 export const acceptanceCoverageArtifactSchema = z.object({
     schemaVersion: z.literal(1),
@@ -91,9 +89,9 @@ export async function prepareFeatureDelivery(input) {
     const now = input.now ?? new Date();
     const record = await readTransaction(repoRoot, featureId, blockers);
     if (record) {
-        const branch = await git(repoRoot, ["branch", "--show-current"]).catch(() => "");
-        const head = await git(repoRoot, ["rev-parse", "HEAD"]).catch(() => "");
-        const status = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]).catch(() => "git-error");
+        const branch = await git(repoRoot, ["branch", "--show-current"]).catch(rethrowInfrastructureOr(""));
+        const head = await git(repoRoot, ["rev-parse", "HEAD"]).catch(rethrowInfrastructureOr(""));
+        const status = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]).catch(rethrowInfrastructureOr("git-error"));
         if (branch !== record.branch)
             blockers.push(`current branch must be ${record.branch}`);
         if (head !== record.lastCheckpoint)
@@ -202,11 +200,11 @@ export async function validateDeliveryPackage(input) {
         blockers.push("Delivery Feature ownership mismatch");
     if (manifest.branch !== record.branch || manifest.baseBranch !== record.baseBranch || manifest.baseSha !== record.baseCommit || manifest.headSha !== record.lastCheckpoint)
         blockers.push("Delivery manifest does not match the Git transaction");
-    const branch = await git(repoRoot, ["branch", "--show-current"]).catch(() => "");
-    const head = await git(repoRoot, ["rev-parse", "HEAD"]).catch(() => "");
+    const branch = await git(repoRoot, ["branch", "--show-current"]).catch(rethrowInfrastructureOr(""));
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]).catch(rethrowInfrastructureOr(""));
     if (branch !== record.branch || head !== record.lastCheckpoint)
         blockers.push("current Git position does not match Delivery");
-    const rawCloseoutStatus = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]).catch(() => "git-error");
+    const rawCloseoutStatus = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]).catch(rethrowInfrastructureOr("git-error"));
     const allowedDirtyPaths = new Set((input.allowedDirtyPaths ?? []).map((item) => item.replace(/\\/g, "/")));
     const closeoutStatus = rawCloseoutStatus.split("\n").filter(Boolean).filter((line) => !allowedDirtyPaths.has(line.slice(3).replace(/\\/g, "/"))).join("\n").trim();
     if (closeoutStatus)
@@ -495,23 +493,37 @@ async function writeDeliveryArtifacts(artifacts, coverage, manifest) {
     }
 }
 function renderPr(manifest) { return `# Summary\n\nFeature ${manifest.featureId} local Delivery Package.\n\n## Feature/base/head\n\n- Branch: ${manifest.branch}\n- Base: ${manifest.baseBranch} @ ${manifest.baseSha}\n- Head: ${manifest.headSha}\n\n## Completed Tasks\n\n${manifest.tasks.map((task) => `- ${task.taskId}: ${task.commit} (${task.changedFiles.join(", ")})`).join("\n")}\n\n## Acceptance Coverage\n\n- Required: ${manifest.acceptanceCoverage.requiredTotal}\n- Covered: ${manifest.acceptanceCoverage.covered}\n- Waived: ${manifest.acceptanceCoverage.waived}\n- Blocked: ${manifest.acceptanceCoverage.blocked}\n\n## Verification\n\n- QA: ${manifest.qa.evidence.path}\n- Final: ${manifest.finalVerification.path}\n\n## Changed Files\n\n${[...new Set(manifest.tasks.flatMap((task) => task.changedFiles))].map((file) => `- ${file}`).join("\n")}\n\n## Risks\n\n- high=${manifest.riskSummary.high}, medium=${manifest.riskSummary.medium}, low=${manifest.riskSummary.low}\n\n## Human Review Checklist\n\n- [ ] Review diff and commits\n- [ ] Confirm required AC coverage and waivers\n- [ ] Confirm QA and final verification evidence\n- [ ] Review risks\n- [ ] Decide whether to push or create a remote PR manually\n`; }
-async function git(repoRoot, args) { const result = await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" }); return result.stdout.trim(); }
-async function gitRaw(repoRoot, args) { const result = await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" }); return result.stdout; }
-async function gitOk(repoRoot, args) { try {
-    await git(repoRoot, args);
-    return true;
+async function git(repoRoot, args) {
+    const result = await runResilientGitCommand({ cwd: repoRoot, args, readOnly: true });
+    if (result.code !== 0)
+        throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
+    return result.stdout.trim();
+}
+async function gitRaw(repoRoot, args) {
+    const result = await runResilientGitCommand({ cwd: repoRoot, args, readOnly: true });
+    if (result.code !== 0)
+        throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
+    return result.stdout;
+}
+async function gitOk(repoRoot, args) {
+    const result = await runResilientGitCommand({ cwd: repoRoot, args, readOnly: true });
+    return result.code === 0;
+}
+function rethrowInfrastructureOr(fallback) {
+    return (error) => {
+        if (isResilientGitCommandError(error))
+            throw error;
+        return fallback;
+    };
 }
-catch {
-    return false;
-} }
 async function checkpointMatches(repoRoot, head, checkpoint, spec) {
     if (!await gitOk(repoRoot, ["merge-base", "--is-ancestor", checkpoint.commit, head]))
         return false;
-    const messageText = await gitRaw(repoRoot, ["show", "-s", "--format=%B", checkpoint.commit]).catch(() => "");
+    const messageText = await gitRaw(repoRoot, ["show", "-s", "--format=%B", checkpoint.commit]).catch(rethrowInfrastructureOr(""));
     for (const trailer of [`Feature: ${spec.feature_id}`, `Task: ${spec.id}`, `Acceptance: ${spec.acceptance_refs.join(", ")}`, `Worker-Run: ${checkpoint.workerRunId}`])
         if (!messageText.split(/\r?\n/).includes(trailer))
             return false;
-    const actual = (await gitRaw(repoRoot, ["diff-tree", "--no-commit-id", "--name-only", "-r", checkpoint.commit]).catch(() => "")).split(/\r?\n/).filter(Boolean).sort();
+    const actual = (await gitRaw(repoRoot, ["diff-tree", "--no-commit-id", "--name-only", "-r", checkpoint.commit]).catch(rethrowInfrastructureOr(""))).split(/\r?\n/).filter(Boolean).sort();
     return JSON.stringify(actual) === JSON.stringify([...checkpoint.changedFiles].sort());
 }
 async function hashedRefValid(repoRoot, ref) { try {

package/dist/worker/delivery/verification-bundle.js

@@ -7,6 +7,7 @@ import { artifactMatchesEvidenceToken, isShellVerificationToken, } from "../outc
 import { readVerifiedOutcome } from "../outcomes/store.js";
 import { getTaskPoolRoot, readFeatureTaskPoolStates } from "../pool/run-store.js";
 import { workflowSchema } from "../task-spec/workflow-routing.js";
+import { runResilientGitCommand } from "../../shared/resilient-git.js";
 import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
 /**
  * Feature Verification Bundle v1 — a hash-bound aggregate of completed typed
@@ -533,10 +534,11 @@ async function readGitRecord(repoRoot, featureId) {
     }
 }
 async function defaultGit(repoRoot, args) {
-    const { execFile } = await import("node:child_process");
-    const { promisify } = await import("node:util");
-    const execFileAsync = promisify(execFile);
-    return (await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" })).stdout.trim();
+    const result = await runResilientGitCommand({ cwd: repoRoot, args, readOnly: true });
+    if (result.code !== 0) {
+        throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
+    }
+    return result.stdout.trim();
 }
 // Re-export the workflow schema so consumers can validate typed workflows.
 export { workflowSchema };

package/dist/worker/observe/static/operator-chrome.css

@@ -71,8 +71,11 @@
 	text-decoration: none;
 	white-space: nowrap;
 }
-.och-brand svg {
-	color: var(--och-orange);
+.och-brand-mark {
+	display: block;
+	width: 32px;
+	height: 32px;
+	object-fit: contain;
 	flex-shrink: 0;
 }
 .och-brand:hover {

package/dist/worker/observe/static/operator-chrome.js

@@ -353,7 +353,12 @@ export function mountOperatorChrome(root, config = {}) {
 
 		const brand = el("a", "och-brand");
 		brand.href = model.homeHref;
-		icon(brand, "radar");
+		brand.setAttribute("aria-label", `${model.brand} 首页`);
+		const brandMark = el("img", "och-brand-mark");
+		brandMark.src = "/inspect/favicon.svg";
+		brandMark.alt = "";
+		brandMark.setAttribute("aria-hidden", "true");
+		brand.appendChild(brandMark);
 		brand.appendChild(el("span", null, model.brand));
 		global.appendChild(brand);
 

package/dist/worker/observe/static/styles.css

@@ -1617,7 +1617,11 @@ body.is-resizing-dag-graph {
 /* 历史失败已恢复/已覆盖：独立中性样式（不占用当前终态失败红色，不洗白事实）。 */
 .dag-trajectory-occurrence.is-recovered {
 	border-color: color-mix(in srgb, var(--amber, #b58900) 55%, var(--hairline));
-	background: color-mix(in srgb, var(--amber-soft, #fff7d6) 55%, var(--surface));
+	background: color-mix(
+		in srgb,
+		var(--amber-soft, #fff7d6) 55%,
+		var(--surface)
+	);
 }
 .dag-trajectory-recovered {
 	font-size: 11px;
@@ -1647,9 +1651,14 @@ body.is-resizing-dag-graph {
 }
 .dag-trajectory-banner {
 	padding: 8px 12px;
-	border: 1px solid color-mix(in srgb, var(--amber, #b58900) 50%, var(--hairline));
+	border: 1px solid
+		color-mix(in srgb, var(--amber, #b58900) 50%, var(--hairline));
 	border-radius: var(--radius-lg);
-	background: color-mix(in srgb, var(--amber-soft, #fff7d6) 60%, var(--surface));
+	background: color-mix(
+		in srgb,
+		var(--amber-soft, #fff7d6) 60%,
+		var(--surface)
+	);
 	color: var(--body);
 	font-size: 12px;
 }
@@ -3050,7 +3059,11 @@ button.copy-command:focus-visible {
 }
 .dags-copy-btn:active {
 	border-color: var(--hairline-strong, #cfcdc4);
-	background: color-mix(in srgb, var(--surface-muted, #f0efe9) 80%, var(--hairline, #e6e5e0));
+	background: color-mix(
+		in srgb,
+		var(--surface-muted, #f0efe9) 80%,
+		var(--hairline, #e6e5e0)
+	);
 }
 /* Mouse focus must not leave residual orange chrome; orange is :focus-visible only. */
 .dags-copy-btn:focus:not(:focus-visible) {
@@ -3201,12 +3214,20 @@ button.copy-command:focus-visible {
 }
 .dags-page-num:hover:not(:disabled),
 .dags-page-nav:hover:not(:disabled) {
-	background: color-mix(in srgb, var(--orange-soft, #fff1ea) 70%, var(--surface-muted, #f0efe9));
+	background: color-mix(
+		in srgb,
+		var(--orange-soft, #fff1ea) 70%,
+		var(--surface-muted, #f0efe9)
+	);
 	color: var(--ink, #26251e);
 }
 .dags-page-num:active:not(:disabled),
 .dags-page-nav:active:not(:disabled) {
-	background: color-mix(in srgb, var(--orange, #f54e00) 14%, var(--surface-muted, #f0efe9));
+	background: color-mix(
+		in srgb,
+		var(--orange, #f54e00) 14%,
+		var(--surface-muted, #f0efe9)
+	);
 }
 .dags-page-num:focus-visible,
 .dags-page-nav:focus-visible,
@@ -3224,7 +3245,8 @@ button.copy-command:focus-visible {
 	border-color: var(--orange, #f54e00);
 	color: #fff;
 	opacity: 1;
-	box-shadow: 0 2px 8px color-mix(in srgb, var(--orange, #f54e00) 35%, transparent);
+	box-shadow: 0 2px 8px
+		color-mix(in srgb, var(--orange, #f54e00) 35%, transparent);
 	cursor: default;
 }
 .dags-page-nav:disabled,
@@ -3320,7 +3342,11 @@ button.copy-command:focus-visible {
 	background: var(--surface-muted, #f0efe9);
 }
 .dags-refresh-btn:active:not(:disabled) {
-	background: color-mix(in srgb, var(--surface-muted, #f0efe9) 80%, var(--hairline, #e6e5e0));
+	background: color-mix(
+		in srgb,
+		var(--surface-muted, #f0efe9) 80%,
+		var(--hairline, #e6e5e0)
+	);
 }
 .dags-pagination.is-busy {
 	opacity: 0.92;
@@ -3516,7 +3542,11 @@ button.copy-command:focus-visible {
 }
 .custom-select-option.is-selected.is-active,
 .custom-select-option.is-selected:hover {
-	background: color-mix(in srgb, var(--orange-soft, #fff1ea) 70%, var(--surface-muted, #f0efe9));
+	background: color-mix(
+		in srgb,
+		var(--orange-soft, #fff1ea) 70%,
+		var(--surface-muted, #f0efe9)
+	);
 }
 .custom-select-option-label {
 	flex: 1 1 auto;

package/dist/workflows/dag/frontend-worktree-diff.js

@@ -1,31 +1,14 @@
 import { createHash } from "node:crypto";
-import { spawn } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { runResilientGitCommand } from "../../shared/resilient-git.js";
 import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 export const FRONTEND_WORKTREE_DIFF_SCHEMA_ID = "frontend-worktree-diff-v1";
 export const FRONTEND_WORKTREE_BASELINE_SCHEMA_ID = "frontend-worktree-baseline-v1";
-function runGit(cwd, args) {
-    return new Promise((resolve, reject) => {
-        const child = spawn("git", args, {
-            cwd,
-            env: process.env,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        let stdout = "";
-        let stderr = "";
-        child.stdout.on("data", (chunk) => {
-            stdout += String(chunk);
-        });
-        child.stderr.on("data", (chunk) => {
-            stderr += String(chunk);
-        });
-        child.on("error", reject);
-        child.on("close", (code) => {
-            resolve({ code: code ?? 1, stdout, stderr });
-        });
-    });
+async function runGit(cwd, args) {
+    const result = await runResilientGitCommand({ cwd, args, readOnly: true });
+    return { code: result.code, stdout: result.stdout, stderr: result.stderr };
 }
 function splitLines(text) {
     return text
@@ -52,8 +35,9 @@ async function sha256File(filePath) {
     }
 }
 export async function captureFrontendWorktreeBaseline(input) {
+    const run = input.dependencies?.runGit ?? runGit;
     const root = path.resolve(input.workspaceRoot);
-    const status = await runGit(root, [
+    const status = await run(root, [
         "status",
         "--porcelain=v1",
         "--untracked-files=all",
@@ -84,6 +68,7 @@ export async function captureFrontendWorktreeBaseline(input) {
  * patch + inventory under the current run directory before review runs.
  */
 export async function runFrontendWorktreeDiffGate(input) {
+    const run = input.dependencies?.runGit ?? runGit;
     const root = path.resolve(input.workspaceRoot);
     let baseline;
     try {
@@ -101,16 +86,16 @@ export async function runFrontendWorktreeDiffGate(input) {
     if (input.requireBaseline && !baseline) {
         throw new Error("frontend worktree baseline is required for this review context");
     }
-    const revParse = await runGit(root, ["rev-parse", "--is-inside-work-tree"]);
+    const revParse = await run(root, ["rev-parse", "--is-inside-work-tree"]);
     if (revParse.code !== 0 || revParse.stdout.trim() !== "true") {
         throw new Error(`frontend worktree diff gate requires a git worktree: ${revParse.stderr.trim() || revParse.stdout.trim() || "not a git repository"}`);
     }
     // Match failure capture semantics: binary-capable tracked diff vs HEAD.
-    const diff = await runGit(root, ["diff", "--binary", "HEAD"]);
+    const diff = await run(root, ["diff", "--binary", "HEAD"]);
     if (diff.code !== 0) {
         throw new Error(`frontend worktree diff gate git diff failed: ${diff.stderr.trim() || diff.stdout.trim()}`);
     }
-    const nameOnly = await runGit(root, [
+    const nameOnly = await run(root, [
         "diff",
         "--name-only",
         "--diff-filter=ACDMRTUXB",
@@ -119,7 +104,7 @@ export async function runFrontendWorktreeDiffGate(input) {
     if (nameOnly.code !== 0) {
         throw new Error(`frontend worktree diff gate git name-only failed: ${nameOnly.stderr.trim() || nameOnly.stdout.trim()}`);
     }
-    const untracked = await runGit(root, [
+    const untracked = await run(root, [
         "ls-files",
         "--others",
         "--exclude-standard",
@@ -152,7 +137,7 @@ export async function runFrontendWorktreeDiffGate(input) {
     });
     const patchSource = baseline
         ? changedFiles.length > 0
-            ? await runGit(root, ["diff", "--binary", "HEAD", "--", ...changedFiles])
+            ? await run(root, ["diff", "--binary", "HEAD", "--", ...changedFiles])
             : { code: 0, stdout: "", stderr: "" }
         : diff;
     if (patchSource.code !== 0) {

package/dist/workflows/dag/workspace-checkpoint.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { spawn } from "node:child_process";
 import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
+import { runResilientGitCommand } from "../../shared/resilient-git.js";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 /**
  * Workspace checkpoint for DAG continuation safety.
@@ -13,30 +13,10 @@ function sha256Hex(input) {
     return createHash("sha256").update(input).digest("hex");
 }
 async function runGit(cwd, args) {
-    return new Promise((resolve, reject) => {
-        const child = spawn("git", args, {
-            cwd,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        let stdout = "";
-        let stderr = "";
-        child.stdout.setEncoding("utf-8");
-        child.stderr.setEncoding("utf-8");
-        child.stdout.on("data", (chunk) => {
-            stdout += chunk;
-        });
-        child.stderr.on("data", (chunk) => {
-            stderr += chunk;
-        });
-        child.on("error", reject);
-        child.on("close", (code) => {
-            if (code === 0) {
-                resolve(stdout);
-                return;
-            }
-            reject(new Error(`git ${args.join(" ")} failed: ${stderr.trim() || stdout.trim()}`));
-        });
-    });
+    const result = await runResilientGitCommand({ cwd, args, readOnly: true });
+    if (result.code === 0)
+        return result.stdout;
+    throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
 }
 function normalizeGitPath(value) {
     const target = value.includes(" -> ")
@@ -137,9 +117,10 @@ async function hashStableGovernanceInputs(repoRoot, taskId) {
  * When `taskId` is provided, fingerprint includes stable ignored Task Contract inputs.
  */
 export async function captureWorkspaceCheckpoint(repoRoot, options) {
+    const run = options?.dependencies?.runGit ?? runGit;
     const capturedAt = (options?.now ?? new Date()).toISOString();
-    const gitHeadSha = (await runGit(repoRoot, ["rev-parse", "HEAD"])).trim();
-    const porcelain = await runGit(repoRoot, [
+    const gitHeadSha = (await run(repoRoot, ["rev-parse", "HEAD"])).trim();
+    const porcelain = await run(repoRoot, [
         "status",
         "--porcelain=v1",
         "--untracked-files=all",

package/harness.json

@@ -81,7 +81,7 @@
     "pi": {
       "description": "Pi 负责规划、评审、诊断；当 DAG toolProfile=write 时也可做有界写入。模型按复杂度三档配置，格式为 provider/model 字符串（例：wizard-local/grok-4.5）；斜杠前为 Pi provider，后为 modelId，勿只写裸 modelId。",
       "LOW": "wizard-local/minimax-m3",
-      "MED": "wizard-local/gpt-5.6-sol",
+      "MED": "wizard-local/gpt-5.6-terra",
       "HIGH": "wizard-local/gpt-5.6-sol"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.33.5",
+  "version": "0.33.6",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/references/command-reference.md

@@ -224,7 +224,9 @@ loop-agent task advance <task-id> "标题" \
   --json
 ```
 
-默认无 LLM 写 source；工程边界用 flags 显式给出。不要让 AI 直接改写 `source/references/*`。高级用户仍可手工编辑后 `task advance --from-draft`。
+默认无 LLM 写 source；工程边界用 flags 显式给出。不要让 AI 直接改写 `source/references/*`。
+Product Requirement V3/V4（`product-requirement.md`）由确定性解析消费；`product-analysis` / `requirement-clarification` 不能单独作为可执行 PRD。
+intake 失败时不要在原 PRD 目录生成兼容 md/json；`--from-draft` **仅**人工 reviewed draft / managed 恢复 / 调试，不是 `EMPTY_ACCEPTANCE` 默认恢复路径。
 
 ### Feature-study workflow（参考代码 → 轻量实现）
 

package/skills/loop-agent/references/source-and-plan-practice.md

@@ -41,6 +41,19 @@ Task 目录布局：`task-workflow.md`。
 - 把用户 PRD **整篇改写**进 `需求.md` 后删掉原文路径。
 - AI 直接 edit `source/references/*`。
 - 只把 PRD 路径写在聊天里，不落盘到 task 容器。
+- 把 `product-analysis.md` 当可执行 PRD，或把 analysis/clarification 改写成假 AC 以通过 prepare。
+- intake 失败后在原 PRD 目录生成「兼容格式」Markdown / `reviewed-draft.json`，再用 `--from-draft` 绕过（默认禁止）。
+- 把 `--from-draft` 当作 `EMPTY_ACCEPTANCE` 的自动恢复手段。
+
+### Product Analysis 套件
+
+| 文件 | role | 用途 |
+|---|---|---|
+| `product-requirement.md` | `requirement` | **唯一**可执行需求事实源（complete 后才进 DAG） |
+| `product-analysis.md` | `analysis` | 分析证据；**不能**单独作为 requirement |
+| `requirement-clarification.md` | `clarification` | 决策追溯；**不能**单独作为 requirement |
+
+`task advance --prd` 可多次传入；未写 `--role` 时按路径/frontmatter 推断。intake 未完成时 lifecycle 为 `intake-incomplete`（PRD 已归档，DAG 未生成）。
 
 ### 推荐顺序（有 PRD 时）
 

package/skills/loop-agent/references/task-workflow.md

@@ -37,6 +37,10 @@ loop-agent task status <task-id> --json
 ```
 
 - 用户原始 PRD 用 `task advance --prd <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就归档**。
+- Product Analysis 套件职责：`product-requirement.md` 是唯一可执行需求事实源；`product-analysis.md` / `requirement-clarification.md` 仅引用。未显式 `--role` 时按文件名/frontmatter 推断（analysis / clarification / requirement）。
+- 遇到 `PRODUCT_ANALYSIS_NOT_EXECUTABLE` / `PRODUCT_REQUIREMENT_PENDING` / `EMPTY_ACCEPTANCE`：**禁止**改写原始产物，**禁止**在原 PRD 目录生成兼容 Markdown 或 `reviewed-draft.json` 自救；应换正确 requirement 文档或补真实验收标准后重试。
+- `--from-draft` 仅用于人工 reviewed draft / managed 恢复 / 调试，不是 intake 失败的默认恢复路径。
+- 确定性解析失败且缺口为结构性时，`task advance` 可自动做**一次** Semantic Intake（只读 Pi → `artifacts/intake/semantic-draft.json` → prepare）；analysis/pending/真缺决策不会调用。可用 `LOOP_AGENT_SEMANTIC_INTAKE=0` 关闭。禁止在原 PRD 目录写 sidecar。
 - 默认用 `task advance`（带 `--allowed-path` / `--verify`）投影 `需求.md` / `执行约束.md` 与 managed paths；**不要**默认让 LLM/主会话手写两 source。
 - 无独立 PRD 的微小任务可用 `task advance --from-text ...` escape hatch（见 `source-and-plan-practice.md`）。
 - 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `task advance --prd` 归档并派生薄契约；避免把长 PRD 直接改写成唯一 source。