@guanlin4924/devflow-pi 0.1.94 → 0.1.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.94",
+  "version": "0.1.96",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",
@@ -14,13 +14,18 @@
     "test:devflow-pi": "bun test tests/devflow-pi",
     "test": "bun test tests/devflow-pi && python3 -m unittest discover -s tests -p 'test_*.py'",
     "check": "bun test tests/devflow-pi && python3 -m unittest discover -s tests -p 'test_*.py'",
+    "build:runtime": "bun scripts/build-runtime.ts",
+    "check:runtime": "bun scripts/build-runtime.ts --check",
     "release": "bash scripts/release-npm.sh"
   },
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.3.14",
+    "node": ">=20"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@oh-my-pi/pi-coding-agent": "17.2.7",
+    "@playwright/test": "1.63.0",
     "@plurnk/plurnk-mimetypes-grammar-cpp": "1.16.1",
     "@plurnk/plurnk-mimetypes-grammar-kotlin": "1.16.1",
     "@plurnk/plurnk-mimetypes-grammar-ruby": "1.16.1",
@@ -29,6 +34,9 @@
     "tree-sitter-graphql-grammar-wasm": "1.1.0",
     "web-tree-sitter": "0.25.10"
   },
+  "bundleDependencies": [
+    "@playwright/test"
+  ],
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
@@ -40,6 +48,9 @@
     "!plugins/**/__pycache__",
     "!plugins/**/*.pyc",
     "!plugins/**/tests",
+    "!plugins/devflow-quality/runtime/playwright/spike",
+    "!plugins/devflow-quality/runtime/playwright/src",
+    "!plugins/devflow-quality/runtime/playwright/SPIKE.md",
     "templates",
     "README.md"
   ],

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -17,6 +17,20 @@ import { projectControlDatabasePath } from "../../../src/paths.ts";
 import { generateProjectDocuments } from "../../../src/project-documents.ts";
 import { exportInitializationSnapshot, importLegacyInitialization, switchInitializationAuthority } from "../../../src/project-migration.ts";
 import { migrateLegacyProjectLayout } from "../../../src/project-layout.ts";
+import {
+  APPROVAL_KINDS,
+  confirmApproval,
+  databaseAuthority,
+  listApprovals,
+  listProposals,
+  proposalIsExpired,
+  proposeApprovals,
+  rejectProposal,
+  type ApprovalKind,
+  type CurrentPins,
+  type HumanResultStatus,
+  type ProposalRecord,
+} from "../../../src/approval-store.ts";
 
 
 export type DevflowIntent = "idle" | "explain-state" | "project-init" | "requirement-draft" | "workflow-execute";
@@ -210,6 +224,28 @@ const STATE_MUTATION_TOOLS = new Set([
   "devflow_run_acceptance_tests",
 ]);
 
+/** Maps devflow_run_acceptance_tests parameters to acceptance_test_runner.py argv; gc_runs is a dry-run unless write=true. */
+export function acceptanceRunnerArgs(params: {
+  action: "validate" | "validate_human" | "run" | "validate_results" | "gc_runs";
+  feature: string;
+  write?: boolean;
+  retentionDays?: number;
+  unreferencedTtlDays?: number;
+}): string[] {
+  const scriptAction = params.action === "validate_results"
+    ? "validate-results"
+    : params.action === "validate_human" ? "validate-human"
+      : params.action === "gc_runs" ? "gc-runs" : params.action;
+  const args = [scriptAction, "--feature", params.feature, "--json"];
+  if (params.action === "run") args.push("--write");
+  if (params.action === "gc_runs") {
+    if (params.write === true) args.push("--write");
+    if (params.retentionDays !== undefined) args.push("--retention-days", String(params.retentionDays));
+    if (params.unreferencedTtlDays !== undefined) args.push("--unreferenced-ttl-days", String(params.unreferencedTtlDays));
+  }
+  return args;
+}
+
 export function initialControlState(): SessionControlState {
   return { intent: "idle", phase: "idle", label: "对话（不自动执行）" };
 }
@@ -561,6 +597,7 @@ const REQUIRED_EXTENSION_TOOLS = [
   "devflow_context_cursor",
   "devflow_design_rule",
   "devflow_mainflow",
+  "devflow_approval",
 ];
 
 const REQUIRED_SKILLS = [
@@ -584,6 +621,7 @@ const REQUIRED_SKILLS = [
   "workflow-frontend-tech-spec",
   "workflow-gen-test-guide",
   "workflow-generate-mainflow-cases",
+  "workflow-human-acceptance",
   "workflow-integration-verify",
   "workflow-orchestrator",
   "workflow-pipeline",
@@ -807,6 +845,7 @@ function isCoreOwnedGovernancePath(filePath: string): boolean {
   // 规范需求图谱只能由 Core 的 devflow_requirement_graph writer 写入；the
   // same ownership extends to its views, machine evidence, and audit records.
   return isCanonicalRequirementGraphPath(filePath)
+    || /^\.devflow\/planning\/test-runs\/[^/\\\x00-\x1F\x7F]+\/acceptance-results(?:\.meta)?\.json$/u.test(filePath)
     || /^\.devflow\/planning\/evidence\/[^/\\\x00-\x1F\x7F]+\/[^/\\]+\.machine\.json$/u.test(filePath)
     || /^\.devflow\/planning\/contracts\/[^/\\\x00-\x1F\x7F]+\/(?:EC-[A-Fa-f0-9]+\.json|control-events\.jsonl)$/u.test(filePath)
     || filePath.startsWith(".devflow/planning/review-runs/")
@@ -1292,7 +1331,9 @@ function stepScopedMutationOwner(toolName: string, input: unknown): string | nul
   if (normalized === "devflow_api_test_matrix") return action === "validate" ? undefined : "acceptance-test-design";
   if (normalized === "devflow_tdd_evidence") return action === "inspect" ? undefined : "execute";
   if (normalized === "devflow_run_acceptance_tests") return action === "run" ? "run-acceptance-tests" : undefined;
-  if (normalized === "devflow_mainflow") return "generate-mainflow-cases";
+  // Mainflow generation is an optional developer handoff inside the explicit
+  // human-acceptance step, not a standalone workflow step.
+  if (normalized === "devflow_mainflow") return "human-acceptance";
   if (normalized === "devflow_wireframe" || normalized === "devflow_design_rule") return "ui-spec";
   if (normalized.startsWith("devflow_architecture_") || normalized === "devflow_workload_constraint") {
     return action === "inspect" ? undefined : "architecture-feasibility";
@@ -1349,6 +1390,198 @@ export function stepScopedMutationBlockReason(
   return undefined;
 }
 
+// ---------------------------------------------------------------------------
+// Core human approvals (change list P03/P04). The agent may only propose or
+// list; confirmation exists solely in the /devflow control panel callback,
+// which writes control.db directly from this extension process.
+// ---------------------------------------------------------------------------
+
+export const APPROVAL_TOOL_ACTIONS = ["propose", "list"] as const;
+
+/** Parameter schema of `devflow_approval`; there is deliberately no confirm action. */
+export function approvalToolParameters(z: any) {
+  const item = z.object({
+    subject: z.string().min(1).max(128),
+    dsl_file: z.string().min(1).max(512).optional(),
+    evidence_files: z.array(z.string().min(1).max(512)).max(50).optional(),
+    note: z.string().max(4000).optional(),
+    review_issues: z.array(z.string().min(1).max(2000)).max(100).optional(),
+  }).strict();
+  return z.object({
+    action: z.enum(APPROVAL_TOOL_ACTIONS),
+    feature: z.string().min(1).max(200).optional(),
+    kind: z.enum(APPROVAL_KINDS).optional(),
+    items: z.array(item).min(1).max(200).optional(),
+    status: z.enum(["proposed", "consumed", "rejected", "expired"]).optional(),
+  }).strict();
+}
+
+export type ApprovalProposeItem = {
+  subject: string;
+  dsl_file?: string;
+  evidence_files?: string[];
+  note?: string;
+  review_issues?: string[];
+};
+
+/**
+ * Splits one agent item into the pin-computation request (re-used verbatim for
+ * the confirm-time CAS) and agent-supplied context that is only displayed.
+ */
+export function approvalProposeRequest(kind: ApprovalKind, item: ApprovalProposeItem): { request: Record<string, unknown>; agent: Record<string, unknown> } {
+  if (item.dsl_file !== undefined && kind !== "execution_plan") throw new Error(`dsl_file is only valid for execution_plan proposals`);
+  if (item.review_issues !== undefined && kind !== "execution_plan") throw new Error(`review_issues are only valid for execution_plan proposals`);
+  if (item.evidence_files !== undefined && kind !== "human_result") throw new Error(`evidence_files are only valid for human_result proposals`);
+  const request: Record<string, unknown> = {};
+  if (kind === "execution_plan" && item.dsl_file) request.dsl_file = item.dsl_file;
+  if (kind === "human_result") request.evidence_files = item.evidence_files ?? [];
+  const agent: Record<string, unknown> = {};
+  if (item.note?.trim()) agent.note = item.note.trim();
+  if (item.review_issues?.length) agent.review_issues = item.review_issues;
+  return { request, agent };
+}
+
+export function approvalPinsScript(): string {
+  // Always the packaged helper next to this extension: never a project-local
+  // `.skills` copy the agent could edit to forge the confirm-time CAS.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../skills/workflow-orchestrator/scripts/approval_pins.py");
+}
+
+export function approvalPinsArgv(root: string, feature: string, kind: ApprovalKind, subject: string, request: Record<string, unknown>): string[] {
+  return [
+    "python3", "-I", approvalPinsScript(), "compute",
+    "--root", root, "--feature", feature, "--kind", kind, "--subject", subject,
+    "--payload-json", JSON.stringify(request), "--json",
+  ];
+}
+
+export type ApprovalPinsResult = { ok: true; pins: Record<string, unknown>; stateRevision: number; display: Record<string, unknown> } | { ok: false; errors: string[] };
+
+export function parseApprovalPinsOutput(stdout: string, stderr = ""): ApprovalPinsResult {
+  let parsed: Record<string, unknown> | null = null;
+  try { parsed = JSON.parse(stdout) as Record<string, unknown>; } catch { parsed = null; }
+  if (!parsed || typeof parsed !== "object") return { ok: false, errors: [`approval pin helper returned invalid JSON: ${(stderr || stdout).slice(0, 500)}`] };
+  if (parsed.ok !== true) {
+    const errors = Array.isArray(parsed.errors) ? parsed.errors.map(String) : ["approval pin helper failed"];
+    return { ok: false, errors };
+  }
+  if (!parsed.pins || typeof parsed.pins !== "object" || !Number.isInteger(parsed.state_revision)) {
+    return { ok: false, errors: ["approval pin helper returned no pins"] };
+  }
+  return {
+    ok: true,
+    pins: parsed.pins as Record<string, unknown>,
+    stateRevision: Number(parsed.state_revision),
+    display: parsed.display && typeof parsed.display === "object" ? parsed.display as Record<string, unknown> : {},
+  };
+}
+
+/** Synchronous recompute used inside the confirm transaction. */
+export function recomputeApprovalPinsSync(root: string, proposal: ProposalRecord): CurrentPins {
+  const request = proposal.payload.request && typeof proposal.payload.request === "object" ? proposal.payload.request as Record<string, unknown> : {};
+  const child = Bun.spawnSync(approvalPinsArgv(root, proposal.feature, proposal.kind, proposal.subjectKey, request), {
+    cwd: root, stdout: "pipe", stderr: "pipe", env: { ...process.env, OMP_PROJECT_DIR: root },
+  });
+  const result = parseApprovalPinsOutput(child.stdout.toString(), child.stderr.toString());
+  if (!result.ok) throw new Error(result.errors.join("; "));
+  return { pins: result.pins, stateRevision: result.stateRevision };
+}
+
+export const APPROVAL_KIND_LABELS: Record<ApprovalKind, string> = {
+  execution_plan: "执行计划",
+  environment_profile: "环境配置",
+  mode_override: "降级为人工",
+  human_result: "人工验收结果",
+};
+
+export const HUMAN_RESULT_CHOICES: Array<{ label: string; status: HumanResultStatus }> = [
+  { label: "passed（通过）", status: "passed" },
+  { label: "failed（失败）", status: "failed" },
+  { label: "blocked（阻塞）", status: "blocked" },
+];
+
+/** Builds a human_result decision only from the user's own selection and input. */
+export function humanResultDecision(choice: string | undefined, actualResult: string | undefined): { status: HumanResultStatus; actual_result: string } | null {
+  const status = HUMAN_RESULT_CHOICES.find(item => item.label === choice)?.status;
+  const actual = actualResult?.trim();
+  if (!status || !actual) return null;
+  return { status, actual_result: actual };
+}
+
+export function pendingApprovalProposals(proposals: ProposalRecord[], now = new Date()): ProposalRecord[] {
+  return proposals.filter(item => item.status === "proposed" && !proposalIsExpired(item, now));
+}
+
+export function approvalProposalLabel(proposal: ProposalRecord): string {
+  return `${APPROVAL_KIND_LABELS[proposal.kind] ?? proposal.kind} · ${proposal.feature} · ${proposal.subjectKey} · ${proposal.createdAt.slice(0, 16).replace("T", " ")} · ${proposal.id.slice(0, 8)}`;
+}
+
+function approvalText(value: unknown, limit = 600): string {
+  const text = typeof value === "string" ? value : value === undefined || value === null ? "（无）" : JSON.stringify(value);
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+function approvalList(values: unknown, empty = "（无）"): string[] {
+  if (!Array.isArray(values) || values.length === 0) return [`  ${empty}`];
+  return values.map((value, index) => `  ${index + 1}. ${approvalText(value, 400)}`);
+}
+
+/** Pure display assembly for one pending proposal (tested without a UI). */
+export function approvalReviewText(proposal: ProposalRecord): string {
+  const display = proposal.payload.display && typeof proposal.payload.display === "object" ? proposal.payload.display as Record<string, any> : {};
+  const agent = proposal.payload.agent && typeof proposal.payload.agent === "object" ? proposal.payload.agent as Record<string, any> : {};
+  const lines = [
+    `类型：${APPROVAL_KIND_LABELS[proposal.kind] ?? proposal.kind}`,
+    `功能：${proposal.feature}`,
+    `对象：${proposal.subjectKey}`,
+    `提案：${proposal.id}（${proposal.createdAt}，状态版本 ${proposal.stateRevision}）`,
+    "",
+  ];
+  const tcLines = () => [
+    `TC 目标：${approvalText(display.target)}`,
+    `Oracle 原文：${approvalText(display.oracle, 2000)}`,
+    "前置条件：", ...approvalList(display.preconditions),
+    "步骤：", ...approvalList(display.steps),
+  ];
+  if (proposal.kind === "execution_plan") {
+    lines.push(...tcLines());
+    lines.push(`DSL：${approvalText(display.dsl_file)}  sha256=${approvalText(proposal.pins.dsl_sha256)}`);
+    lines.push("覆盖 oracle 的断言：", ...approvalList(display.oracle_assertions, "（无 — 请勿批准）"));
+    const uncovered = [
+      ...(Array.isArray(display.uncovered_preconditions) && display.uncovered_preconditions.length ? [`前置条件 ${display.uncovered_preconditions.join(", ")}`] : []),
+      ...(Array.isArray(display.uncovered_steps) && display.uncovered_steps.length ? [`步骤 ${display.uncovered_steps.join(", ")}`] : []),
+    ];
+    lines.push(`未被覆盖：${uncovered.length ? uncovered.join("；") : "无"}`);
+    if (display.structural_validation === "unavailable") lines.push("注意：Core 结构覆盖校验器不可用，本次只展示覆盖声明。");
+    lines.push("AI 审查问题（建议性）：", ...approvalList(agent.review_issues, "（未提供独立 AI 审查结果）"));
+  } else if (proposal.kind === "environment_profile") {
+    lines.push(`Profile：${approvalText(display.profile)}（${approvalText(display.path)}）`);
+    lines.push(`base_url：${approvalText(display.base_url)}`);
+    lines.push("允许的页面导航 origin：", ...approvalList(display.navigation_origins));
+    lines.push("允许的 API origin：", ...approvalList(display.api_origins));
+    lines.push(`子资源策略：${approvalText(display.subresources)}`);
+    const secrets = display.secret_env && typeof display.secret_env === "object" ? Object.entries(display.secret_env as Record<string, unknown>) : [];
+    lines.push("密钥环境变量（仅名称）：", ...(secrets.length ? secrets.map(([alias, name]) => `  ${alias} ← ${String(name)}`) : ["  （无）"]));
+    lines.push(`trace：${approvalText(display.trace)}`);
+    lines.push(`profile sha256：${approvalText(proposal.pins.profile_sha256)}`);
+  } else if (proposal.kind === "mode_override") {
+    lines.push(...tcLines());
+    lines.push(`降级：${approvalText(display.from)} → ${approvalText(display.to)}`);
+    lines.push(`绑定条目：${approvalText(display.binding_entry, 1000)}`);
+  } else if (proposal.kind === "human_result") {
+    lines.push(...tcLines());
+    const evidence = Array.isArray(display.evidence) ? display.evidence as Array<Record<string, unknown>> : [];
+    lines.push("证据文件（批准时固定哈希）：", ...(evidence.length ? evidence.map(item => `  ${String(item.path)}  sha256=${String(item.sha256)}`) : ["  （无证据文件；无法选择 passed）"]));
+    lines.push("结论未预填：请根据你自己的执行结果选择 passed / failed / blocked，并填写实际结果。");
+  }
+  if (agent.note && proposal.kind !== "execution_plan") {
+    lines.push("", `Agent 说明（仅供参考，不是结论）：${approvalText(agent.note, 2000)}`);
+  } else if (agent.note) {
+    lines.push("", `Agent 说明：${approvalText(agent.note, 2000)}`);
+  }
+  return lines.join("\n");
+}
+
 export default function devflowCore(pi: ExtensionAPI) {
   const { z } = pi.zod;
   pi.registerTool({
@@ -2326,6 +2559,115 @@ export default function devflowCore(pi: ExtensionAPI) {
     ctx.ui.notify(`功能“${feature}”已取消；现有工件已保留。`, "info");
   }
 
+  async function pendingApprovalCount(cwd: string): Promise<number | null> {
+    try {
+      const project = await loadProjectContext(cwd);
+      const store = await InitializationStore.open(project);
+      try {
+        if (databaseAuthority(store.db, project.manifest.projectId) !== "database") return null;
+        return pendingApprovalProposals(listProposals(store.db, project.manifest.projectId, { status: "proposed" })).length;
+      } finally { store.close(); }
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * The only confirmation path for Core approvals. It runs in this extension
+   * process, re-computes pins inside the control.db transaction and never
+   * shells out to a script the agent could also call to confirm.
+   */
+  async function reviewPendingApprovalsFromPanel(ctx: ProjectControlCommandContext): Promise<void> {
+    let project: Awaited<ReturnType<typeof loadProjectContext>>;
+    try {
+      project = await loadProjectContext(ctx.cwd);
+    } catch (error) {
+      ctx.ui.notify(`无法读取项目上下文：${error instanceof Error ? error.message : String(error)}`, "error");
+      return;
+    }
+    const projectId = project.manifest.projectId;
+    for (;;) {
+      const store = await InitializationStore.open(project);
+      try {
+        if (databaseAuthority(store.db, projectId) !== "database") {
+          ctx.ui.notify("approval_requires_database_authority：只有 database authority 模式支持人工批准。", "error");
+          return;
+        }
+        const pending = pendingApprovalProposals(listProposals(store.db, projectId, { status: "proposed" }));
+        if (pending.length === 0) {
+          ctx.ui.notify("当前没有待审批的提案。", "info");
+          return;
+        }
+        const labels = pending.map(approvalProposalLabel);
+        const selected = await ctx.ui.select("待审批", [...labels, "返回"]);
+        if (!selected || selected === "返回") return;
+        const proposal = pending[labels.indexOf(selected)];
+        if (!proposal) return;
+        const review = approvalReviewText(proposal);
+        let decision: Record<string, unknown> | null = null;
+        if (proposal.kind === "human_result") {
+          ctx.ui.notify(review.slice(0, 10000), "info");
+          const choice = await ctx.ui.select(`人工验收结论（${proposal.subjectKey}）`, [...HUMAN_RESULT_CHOICES.map(item => item.label), "拒绝该提案", "返回"]);
+          if (!choice || choice === "返回") continue;
+          if (choice === "拒绝该提案") {
+            if (await ctx.ui.confirm("拒绝提案", `${approvalProposalLabel(proposal)}
+
+拒绝后该提案不能再被确认。继续吗？`)) {
+              rejectProposal(store.db, projectId, proposal.id);
+              ctx.ui.notify("已拒绝该提案。", "info");
+            }
+            continue;
+          }
+          const actual = await ctx.ui.input(`实际结果（${proposal.subjectKey}）`, "请填写你实际观察到的结果");
+          decision = humanResultDecision(choice, actual);
+          if (!decision) {
+            ctx.ui.notify("必须选择结论并填写实际结果；未写入任何批准。", "error");
+            continue;
+          }
+          const confirmed = await ctx.ui.confirm(
+            "确认人工验收结果",
+            `${proposal.subjectKey}
+结论：${String(decision.status)}
+实际结果：${String(decision.actual_result)}
+
+确认后 Core 将固定当前 TC 与证据哈希并记录该结果。继续吗？`,
+          );
+          if (!confirmed) continue;
+        } else {
+          const action = await ctx.ui.select(`审查：${approvalProposalLabel(proposal)}`, ["查看详情并批准…", "拒绝该提案", "返回"]);
+          if (!action || action === "返回") continue;
+          if (action === "拒绝该提案") {
+            if (await ctx.ui.confirm("拒绝提案", `${approvalProposalLabel(proposal)}
+
+拒绝后该提案不能再被确认。继续吗？`)) {
+              rejectProposal(store.db, projectId, proposal.id);
+              ctx.ui.notify("已拒绝该提案。", "info");
+            }
+            continue;
+          }
+          const confirmed = await ctx.ui.confirm(`批准${APPROVAL_KIND_LABELS[proposal.kind]}`, `${review.slice(0, 12000)}
+
+确认批准吗？`);
+          if (!confirmed) continue;
+          decision = { approved: true };
+        }
+        const result = confirmApproval(store.db, {
+          projectId,
+          proposalId: proposal.id,
+          decision,
+          recompute: current => recomputeApprovalPinsSync(project.root, current),
+        });
+        if (result.ok) {
+          ctx.ui.notify(`已批准：${approvalProposalLabel(proposal)}${result.supersededIds.length ? `（替代 ${result.supersededIds.length} 条旧批准）` : ""}`, "info");
+        } else {
+          ctx.ui.notify(`批准失败（${result.code}）：${result.message}`, "error");
+        }
+      } finally {
+        store.close();
+      }
+    }
+  }
+
   async function openProjectControlPanel(ctx: ProjectControlCommandContext): Promise<void> {
     for (;;) {
       // The control panel is a read-only projection. Each action below reads a
@@ -2341,6 +2683,9 @@ export default function devflowCore(pi: ExtensionAPI) {
       if (snapshot.action === "await_user_confirmation") options.push("审查并批准推进…");
       if (hasSafeRecoveryPlan(snapshot)) options.push("执行安全恢复…");
       if (typeof snapshot.current_feature === "string" && !["completed", "cancelled", "failed"].includes(String(snapshot.status))) options.push("取消当前功能…");
+      const approvalCount = await pendingApprovalCount(ctx.cwd);
+      const approvalOption = approvalCount === null ? null : `待审批（${approvalCount}）…`;
+      if (approvalOption) options.push(approvalOption);
       options.push("关闭");
 
       const selected = await ctx.ui.select("项目控制操作", options);
@@ -2371,6 +2716,10 @@ export default function devflowCore(pi: ExtensionAPI) {
         await cancelFeatureFromPanel(ctx);
         return;
       }
+      if (approvalOption && selected === approvalOption) {
+        await reviewPendingApprovalsFromPanel(ctx);
+        continue;
+      }
     }
   }
 
@@ -3429,16 +3778,23 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.registerTool({
     name: "devflow_run_acceptance_tests",
     label: "Devflow Run Acceptance Tests",
-    description: "Validate or execute only command or portable HTTP adapters bound to the frozen TC acceptance suite.",
+    description: [
+      "Validate or execute the adapters bound to the frozen TC acceptance suite: command, portable HTTP, and devflow_playwright (the Core-owned Playwright Runtime driven by a pinned DSL).",
+      "Actions: validate (bindings and suite), validate_human (manual TCs), run (executes every automated TC and writes the canonical acceptance-results.json; Core is the only writer), validate_results (re-checks recorded results against current approvals and hashes), gc_runs (prunes .devflow/runs/<feature> execution directories per retention rules; dry-run by default, pass write=true to delete; optional retentionDays / unreferencedTtlDays).",
+      "Failure analysis reads only the Core-produced result.json summary; trace files and screenshots are not readable by Agent tools and are for the user to inspect locally with Playwright in a terminal.",
+      "devflow_playwright bindings require CURRENT human approvals created with devflow_approval and confirmed by the user in /devflow control: an execution_plan approval per TC (pins the DSL, TC and suite) and an environment_profile approval for the target profile; manual or downgraded TCs need a human_result / mode_override approval. You cannot confirm approvals yourself.",
+      "Hard gate: a missing, superseded or expired approval, or a DSL/profile/suite/evidence hash that changed after the approval or the run, makes run and validate_results return ok=false and blocks run-acceptance-tests from completing; there is no soft override and results must never be written by hand.",
+    ].join(" "),
     parameters: z.object({
-      action: z.enum(["validate", "run", "validate_results"]),
+      action: z.enum(["validate", "validate_human", "run", "validate_results", "gc_runs"]),
       feature: z.string().min(1),
+      write: z.boolean().optional().describe("gc_runs only: actually delete expired run directories. Omit for a dry-run."),
+      retentionDays: z.number().int().min(0).optional().describe("gc_runs only: days referenced runs are kept after release-closeout."),
+      unreferencedTtlDays: z.number().int().min(0).optional().describe("gc_runs only: days unreferenced runs are kept."),
     }),
-    approval: args => args.action === "run" ? "write" : "read",
+    approval: args => args.action === "run" || (args.action === "gc_runs" && args.write === true) ? "write" : "read",
     async execute(_id, params, _signal, _onUpdate, ctx) {
-      const scriptAction = params.action === "validate_results" ? "validate-results" : params.action;
-      const args = [scriptAction, "--feature", params.feature, "--json"];
-      if (params.action === "run") args.push("--write");
+      const args = acceptanceRunnerArgs(params);
       const process = await runPython(ctx.cwd, "workflow-orchestrator/scripts/acceptance_test_runner.py", args);
       const payload = parseJsonResult(process);
       const failed = payload && typeof payload === "object" && (payload as { ok?: unknown }).ok === false;
@@ -3449,6 +3805,75 @@ export default function devflowCore(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "devflow_approval",
+    label: "Devflow Approval",
+    description: "Propose or list Core human approvals (execution_plan, environment_profile, mode_override, human_result). Core computes and pins the current TC/DSL/binding/profile/evidence hashes. Only the user can confirm, in /devflow control → 待审批; this tool has no confirm action. human_result proposals carry evidence only, never a verdict. Requires database authority.",
+    parameters: approvalToolParameters(z),
+    approval: args => (args.action === "list" ? "read" : "write"),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const fail = (message: string, details: Record<string, unknown> = {}) => ({
+        content: [{ type: "text" as const, text: message }],
+        details: { action: params.action, error: message, ...details },
+        isError: true,
+      });
+      try {
+        if (!(APPROVAL_TOOL_ACTIONS as readonly string[]).includes(params.action)) {
+          return fail(`devflow_approval only supports ${APPROVAL_TOOL_ACTIONS.join("|")}; approvals are confirmed by the user in /devflow control`);
+        }
+        const project = await loadProjectContext(ctx.cwd);
+        const projectId = project.manifest.projectId;
+        const store = await InitializationStore.open(project);
+        try {
+          if (databaseAuthority(store.db, projectId) !== "database") {
+            return fail("approval_requires_database_authority: approvals are only supported when the project uses database authority", { code: "approval_requires_database_authority" });
+          }
+          if (params.action === "list") {
+            const proposals = listProposals(store.db, projectId, { feature: params.feature, kind: params.kind, status: params.status ?? "proposed" })
+              .map(item => ({ proposalId: item.id, feature: item.feature, kind: item.kind, subject: item.subjectKey, status: item.status, createdAt: item.createdAt, resolvedAt: item.resolvedAt, expired: item.status === "proposed" && proposalIsExpired(item) }));
+            const approvals = listApprovals(store.db, projectId, { feature: params.feature, kind: params.kind })
+              .map(item => ({ approvalId: item.id, proposalId: item.proposalId, feature: item.feature, kind: item.kind, subject: item.subjectKey, pins: item.pins, decision: item.decision, approvedAt: item.approvedAt }));
+            const value = { proposals, approvals, note: "Approvals listed here are current records; validity is re-checked against current pins by the reader." };
+            return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value };
+          }
+          if (!params.feature || !params.kind || !params.items?.length) return fail("propose requires feature, kind and at least one item");
+          const kind = params.kind as ApprovalKind;
+          const subjects = new Set<string>();
+          const prepared: Array<{ subject: string; request: Record<string, unknown>; agent: Record<string, unknown>; pins: Record<string, unknown>; stateRevision: number; display: Record<string, unknown> }> = [];
+          const errors: string[] = [];
+          for (const item of params.items as ApprovalProposeItem[]) {
+            if (subjects.has(item.subject)) { errors.push(`${item.subject}: duplicate subject`); continue; }
+            subjects.add(item.subject);
+            let split: { request: Record<string, unknown>; agent: Record<string, unknown> };
+            try { split = approvalProposeRequest(kind, item); } catch (error) { errors.push(`${item.subject}: ${error instanceof Error ? error.message : String(error)}`); continue; }
+            const result = await runProcess(approvalPinsArgv(project.root, params.feature, kind, item.subject, split.request), project.root, { OMP_PROJECT_DIR: project.root });
+            const pins = parseApprovalPinsOutput(result.stdout, result.stderr);
+            if (!pins.ok) { errors.push(`${item.subject}: ${pins.errors.join("; ")}`); continue; }
+            prepared.push({ subject: item.subject, ...split, pins: pins.pins, stateRevision: pins.stateRevision, display: pins.display });
+          }
+          // All-or-nothing: a partially recorded execution plan would be misleading to review.
+          if (errors.length) return fail(`No proposal was recorded:\n${errors.join("\n")}`, { errors });
+          // One immediate transaction: any store-level error rolls back every insert and every "expire older proposal" update.
+          const recorded = proposeApprovals(store.db, prepared.map(item => ({
+            projectId, feature: params.feature!, kind, subjectKey: item.subject,
+            payload: { request: item.request, agent: item.agent, display: item.display },
+            pins: item.pins, stateRevision: item.stateRevision,
+          })));
+          const created = prepared.map((item, index) => ({
+            proposalId: recorded[index]!.proposalId, subject: item.subject, pins: item.pins, replacedProposals: recorded[index]!.expiredIds,
+          }));
+          const value = {
+            kind, feature: params.feature, proposals: created,
+            next: "Ask the user to review and decide in /devflow control → 待审批. You cannot confirm approvals; do not write verdicts or approval records yourself.",
+          };
+          return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value };
+        } finally { store.close(); }
+      } catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+      }
+    },
+  });
+
   pi.registerTool({
     name: "devflow_runtime_context",
     label: "Devflow Runtime Context",