@guanlin4924/devflow-pi 0.1.93 → 0.1.95

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

@@ -16,6 +16,21 @@ import { runProjectInitialization } from "../../../src/project-initializer.ts";
 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";
@@ -209,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: "对话（不自动执行）" };
 }
@@ -351,7 +388,7 @@ export function discoverExistingProjectInitialization(cwd: string, options: { al
     }
   }
   if (!options.allowLegacyImport) return null;
-  const sources = [".planning/PROJECT.md", ".planning/navigation/INDEX.md"];
+  const sources = [".devflow/planning/PROJECT.md", ".devflow/planning/navigation/INDEX.md"];
   const records: Array<ExistingProjectInitialization> = [];
   for (const sourcePath of sources) {
     const absolute = path.join(cwd, sourcePath);
@@ -531,13 +568,13 @@ type DoctorContext = {
 };
 
 const CONTROL_PATHS = [
-  ".planning/STATE.md",
-  ".planning/.next-intent",
-  ".planning/.devflow.lock",
-  ".planning/artifacts/index.yaml",
+  ".devflow/planning/STATE.md",
+  ".devflow/planning/.next-intent",
+  ".devflow/planning/.devflow.lock",
+  ".devflow/planning/artifacts/index.yaml",
 ];
 
-const CONTROL_PREFIXES = [".planning/workflows/", ".planning/contracts/", ".planning/evidence/", ".planning/review-runs/"];
+const CONTROL_PREFIXES = [".devflow/planning/workflows/", ".devflow/planning/contracts/", ".devflow/planning/evidence/", ".devflow/planning/review-runs/"];
 
 const REQUIRED_EXTENSION_TOOLS = [
   "devflow_doctor",
@@ -560,6 +597,7 @@ const REQUIRED_EXTENSION_TOOLS = [
   "devflow_context_cursor",
   "devflow_design_rule",
   "devflow_mainflow",
+  "devflow_approval",
 ];
 
 const REQUIRED_SKILLS = [
@@ -583,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",
@@ -703,16 +742,63 @@ function assertRuntimeProjectBoundary(cwd: string): void {
   if (configured && realpathSync(configured) !== resolvedCwd) {
     throw new Error(`Devflow project-root mismatch: session=${resolvedCwd}, configured=${configured}`);
   }
-  const planningRoot = path.join(resolvedCwd, ".planning");
+  const legacyPlanning = path.join(resolvedCwd, ".planning");
+  const legacyContext = path.join(resolvedCwd, ".context");
+  const planningMarkers = ["STATE.md", "PROJECT.md", ".devflow.lock", "navigation/INDEX.md", "code-index/INDEX.md", "workflows", "contracts", "evidence", "review-runs", "requirements", "features", "handoffs", "artifacts", "phase-ownership.yaml"];
+  const contextMarkers = ["spec/index.md", "index.md", "project/index.md", "knowledge/index.md"];
+  const legacyMarker = planningMarkers.some(relative => existsSync(path.join(legacyPlanning, relative)))
+    || contextMarkers.some(relative => existsSync(path.join(legacyContext, relative)));
+  const activeLegacy = ["STATE.md", "workflows", "contracts", "evidence", "review-runs", "requirements", "features", "handoffs", "artifacts", "phase-ownership.yaml"]
+    .find(relative => existsSync(path.join(legacyPlanning, relative)));
+  if (legacyMarker) {
+    const manifestPath = path.join(resolvedCwd, ".devflow", "project.json");
+    let manifestValid = false;
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+      manifestValid = manifest.schemaVersion === 1
+        && typeof manifest.projectId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(manifest.projectId)
+        && typeof manifest.name === "string" && manifest.name.trim().length > 0
+        && typeof manifest.createdAt === "string" && Number.isFinite(Date.parse(manifest.createdAt))
+        && [undefined, 1, 2].includes(manifest.layoutVersion as undefined | number);
+    } catch { /* reported below */ }
+    if (!manifestValid) throw new Error("DEVFLOW_LEGACY_LAYOUT_CONFIRMATION_REQUIRED: valid .devflow/project.json is required before legacy layout migration");
+    let migrationCompletePrecheck = false;
+    try {
+      const marker = JSON.parse(readFileSync(path.join(resolvedCwd, ".devflow", "layout-migration.json"), "utf8")) as Record<string, unknown>;
+      migrationCompletePrecheck = marker.schemaVersion === 1 && marker.status === "complete" && Array.isArray(marker.migrated);
+    } catch { /* reported by the normal conflict checks below */ }
+    if (activeLegacy && !migrationCompletePrecheck) {
+      throw new Error(`DEVFLOW_ACTIVE_LEGACY_LAYOUT: .planning/${activeLegacy} requires dedicated control-plane migration`);
+    }
+    const canonicalExists = existsSync(path.join(resolvedCwd, ".devflow", "planning")) || existsSync(path.join(resolvedCwd, ".devflow", "context"));
+    const migrationComplete = (() => {
+      try {
+        const marker = JSON.parse(readFileSync(path.join(resolvedCwd, ".devflow", "layout-migration.json"), "utf8")) as Record<string, unknown>;
+        return marker.schemaVersion === 1 && marker.status === "complete" && Array.isArray(marker.migrated);
+      } catch { return false; }
+    })();
+    if (manifestValid && (() => {
+      try { return (JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>).layoutVersion === 2; } catch { return false; }
+    })() && migrationComplete) {
+      const planningLegacy = planningMarkers.some(relative => existsSync(path.join(legacyPlanning, relative)));
+      const contextLegacy = contextMarkers.some(relative => existsSync(path.join(legacyContext, relative)));
+      if ((planningLegacy && !existsSync(path.join(resolvedCwd, ".devflow", "planning"))) || (contextLegacy && !existsSync(path.join(resolvedCwd, ".devflow", "context")))) {
+        throw new Error("DEVFLOW_LEGACY_REINTRODUCTION: v2 project will not backfill a missing canonical directory");
+      }
+    }
+    if (canonicalExists && !migrationComplete) throw new Error("DEVFLOW_LAYOUT_CONFLICT: canonical and legacy layouts coexist without a completed migration marker");
+    if (!canonicalExists) throw new Error("DEVFLOW_LAYOUT_MIGRATION_REQUIRED: run project initialization to migrate legacy read-only artifacts");
+  }
+  const planningRoot = path.join(resolvedCwd, ".devflow/planning");
   if (existsSync(planningRoot) && lstatSync(planningRoot).isSymbolicLink()) {
     throw new Error(`Refusing symlinked Devflow planning root: ${planningRoot}`);
   }
   for (const relative of [
-    ".planning/STATE.md",
-    ".planning/.devflow.lock",
-    ".planning/workflows",
-    ".planning/artifacts",
-    ".planning/review-runs",
+    ".devflow/planning/STATE.md",
+    ".devflow/planning/.devflow.lock",
+    ".devflow/planning/workflows",
+    ".devflow/planning/artifacts",
+    ".devflow/planning/review-runs",
   ]) {
     const target = path.join(resolvedCwd, relative);
     try {
@@ -744,29 +830,30 @@ function safeControlPath(cwd: string, raw: string | undefined, kind: "state" | "
   const relative = normalizedProjectPath(raw, cwd);
   const allowed =
     kind === "state"
-      ? relative === ".planning/STATE.md"
-      : Boolean(relative?.startsWith(".planning/workflows/") && relative.endsWith(".yaml"));
+      ? relative === ".devflow/planning/STATE.md"
+      : Boolean(relative?.startsWith(".devflow/planning/workflows/") && relative.endsWith(".yaml"));
   if (!relative || !allowed) throw new Error(`Invalid ${kind} control path: ${raw}`);
   return relative;
 }
 
 function isCanonicalRequirementGraphPath(filePath: string): boolean {
-  return /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:governance|evidence|definitions|behavior-graph|requirement-graph|slices|acceptance|tests|traceability|graph\.meta)\.json$/u.test(filePath)
-    || /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:context\/[^/\\]+\.json|control-events\.jsonl)$/u.test(filePath);
+  return /^\.devflow\/planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:governance|evidence|definitions|behavior-graph|requirement-graph|slices|acceptance|tests|traceability|graph\.meta)\.json$/u.test(filePath)
+    || /^\.devflow\/planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:context\/[^/\\]+\.json|control-events\.jsonl)$/u.test(filePath);
 }
 
 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)
-    || /^\.planning\/evidence\/[^/\\\x00-\x1F\x7F]+\/[^/\\]+\.machine\.json$/u.test(filePath)
-    || /^\.planning\/contracts\/[^/\\\x00-\x1F\x7F]+\/(?:EC-[A-Fa-f0-9]+\.json|control-events\.jsonl)$/u.test(filePath)
-    || filePath.startsWith(".planning/review-runs/")
-    || /^\.planning\/phases\/[^/\\\x00-\x1F\x7F]+\/REVIEW\.md$/u.test(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/")
+    || /^\.devflow\/planning\/phases\/[^/\\\x00-\x1F\x7F]+\/REVIEW\.md$/u.test(filePath);
 }
 
 function planningFeatureFromPath(filePath: string): string | null {
-  const match = filePath.match(/^\.planning\/(?:requirements|features)\/([^/\\\x00-\x1F\x7F]+)(?:\/|$)/u);
+  const match = filePath.match(/^\.devflow\/planning\/(?:requirements|features)\/([^/\\\x00-\x1F\x7F]+)(?:\/|$)/u);
   return match?.[1] ?? null;
 }
 
@@ -1083,8 +1170,8 @@ function projectInitializationDirective(summary: string): string {
   return [
     "<devflow-project-initialization-directive>",
     "用户已批准完整项目初始化。现在处于执行模式；不要再创建 Todo、不要读取或写入 xd://devflow_contract。",
-    "执行 skill://workflow-project-context，按已确认的项目边界建立 .planning/PROJECT.md、.planning/navigation/INDEX.md、.context/spec/index.md，并按用户选择建立 full 代码索引。",
-    "只写项目初始化所需的 .planning/ 与 .context/ 控制产物；不得改动业务源码、依赖或配置。完成后运行项目初始化校验，报告生成文件和验证结果并停止，等待用户审查。",
+    "执行 skill://workflow-project-context，按已确认的项目边界建立 .devflow/planning/PROJECT.md、.devflow/planning/navigation/INDEX.md、.devflow/context/spec/index.md，并按用户选择建立 full 代码索引。",
+    "只写项目初始化所需的 .devflow/planning/ 与 .devflow/context/ 控制产物；不得改动业务源码、依赖或配置。完成后运行项目初始化校验，报告生成文件和验证结果并停止，等待用户审查。",
     summary,
     "</devflow-project-initialization-directive>",
   ].join("\n");
@@ -1177,7 +1264,7 @@ export function isShellControlMutation(toolName: string, input: unknown): boolea
     /workflow-orchestrator\/scripts\/(?:advance_state|init_state|init_workflow|sync_artifacts|requirement_graph|machine_evidence|execution_contract)\.rb[^\n]*--write/.test(
       command,
     );
-  const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item)) || /\.planning\/requirements\//.test(command);
+  const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item)) || /\.devflow\/planning\/requirements\//.test(command);
   // `2>` and `2>>` only redirect stderr. They frequently accompany read-only
   // probes of control-plane files and must not be treated as a file mutation.
   // Keep bare `>`/`>>` and explicit stdout `1>`/`1>>` guarded.
@@ -1244,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";
@@ -1301,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({
@@ -1424,7 +1705,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     const feature = activeContract.feature;
     const step = activeContract.step;
     if (!/^[\p{L}\p{N}._-]{1,160}$/u.test(feature) || !/^[\p{L}\p{N}._-]{1,160}$/u.test(step)) return;
-    const directory = path.join(cwd, ".planning", "evidence", feature);
+    const directory = path.join(cwd, ".devflow/planning", "evidence", feature);
     const attempt = typeof extra.attempt === "number" && Number.isInteger(extra.attempt) && extra.attempt >= 0
       ? extra.attempt
       : undefined;
@@ -1619,7 +1900,7 @@ export default function devflowCore(pi: ExtensionAPI) {
             ? (rawStep as { id: string }).id
             : undefined;
       if (!feature || !step) return undefined;
-      const contractsDir = path.join(cwd, ".planning", "contracts", feature);
+      const contractsDir = path.join(cwd, ".devflow/planning", "contracts", feature);
       if (!existsSync(contractsDir)) return undefined;
       const candidates = readdirSync(contractsDir)
         .filter(name => name.startsWith("EC-") && name.endsWith(".json"))
@@ -1755,7 +2036,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       `初始化方式：${modeSummary}`,
     ].join("\n");
     const consequence = mode === "apply"
-      ? "确认后会创建 Devflow 的 .planning/ 与 .context/ 初始化产物；不会修改业务源码、依赖或项目配置。"
+      ? "确认后会创建 Devflow 的 .devflow/planning/ 与 .devflow/context/ 初始化产物；不会修改业务源码、依赖或项目配置。"
       : "确认后只进入只读规划，不会创建工作流或写入项目文件。";
     const confirmed = await ctx.ui.confirm("确认项目初始化范围", `${summary}\n\n${consequence}`);
     if (!confirmed) {
@@ -2004,7 +2285,7 @@ export default function devflowCore(pi: ExtensionAPI) {
   const runtimeBootstrapAuthorizations = new Set<string>();
 
   async function enqueueControlledRolloverRequest(cwd: string, rolloverId: string, sourceSessionId: string) {
-    const requestPath = path.join(cwd, ".planning", "rollover-request.json");
+    const requestPath = path.join(cwd, ".devflow/planning", "rollover-request.json");
     const temporary = `${requestPath}.${randomUUID()}.tmp`;
     await writeFile(temporary, JSON.stringify({ schema_version: 1, rollover_id: rolloverId, source_session_id: sourceSessionId }) + "\n", "utf8");
     await rename(temporary, requestPath);
@@ -2278,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
@@ -2293,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);
@@ -2323,6 +2716,10 @@ export default function devflowCore(pi: ExtensionAPI) {
         await cancelFeatureFromPanel(ctx);
         return;
       }
+      if (approvalOption && selected === approvalOption) {
+        await reviewPendingApprovalsFromPanel(ctx);
+        continue;
+      }
     }
   }
 
@@ -2403,6 +2800,12 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     projectRoot = ctx.cwd;
     sessionId = randomUUID();
+    try {
+      await migrateLegacyProjectLayout(ctx.cwd);
+    } catch (error) {
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      return;
+    }
     const result = await runHook(ctx.cwd, "start.py", {
       session_id: sessionId,
       cwd: ctx.cwd,
@@ -2736,7 +3139,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         text: [
           "<devflow-planner-directive>",
           "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
-          "不得创建 .planning 文件、不得调用状态迁移、不得执行实现。",
+          "不得创建 .devflow/planning 文件、不得调用状态迁移、不得执行实现。",
           "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
           initialization.summary,
           "</devflow-planner-directive>",
@@ -2841,7 +3244,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           "--root", ctx.cwd,
           "--feature", activeContract.feature,
           "--step", activeContract.step,
-          "--contract", `.planning/contracts/${activeContract.feature}/${activeContract.contractId}.json`,
+          "--contract", `.devflow/planning/contracts/${activeContract.feature}/${activeContract.contractId}.json`,
           "--obligations", "[]",
           "--review-agent", "devflow-code-reviewer",
           "--stage", "entry",
@@ -3375,16 +3778,22 @@ 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).",
+      "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;
@@ -3395,6 +3804,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",
@@ -3625,7 +4103,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     async execute(_id, params, _signal, _onUpdate, ctx) {
       const feature = normalizeContractSegment(params.feature, "feature");
       const taskId = normalizeContractSegment(params.taskId, "taskId");
-      const root = path.join(ctx.cwd, ".planning", "evidence", feature);
+      const root = path.join(ctx.cwd, ".devflow/planning", "evidence", feature);
       const destination = path.join(root, `${taskId}.json`);
       const validatePack = (pack: unknown): string[] => {
         if (!pack || typeof pack !== "object" || Array.isArray(pack)) return ["pack must be an object"];
@@ -3718,7 +4196,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         const written = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", createArgs);
         if (!controlPlaneSucceeded(written)) return renderResult(written, { action: input.action });
         const writtenPayload = parseJsonResult(written);
-        const destination = typeof writtenPayload?.path === "string" ? writtenPayload.path : ".planning/contracts/";
+        const destination = typeof writtenPayload?.path === "string" ? writtenPayload.path : ".devflow/planning/contracts/";
         contract.contractPath = destination;
         activeContract = contract;
         contractAgentCalls = 0;
@@ -4264,7 +4742,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           [
             "<devflow-planner-directive>",
             "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
-            "不得创建 .planning 文件、不得调用状态迁移、不得执行实现。",
+            "不得创建 .devflow/planning 文件、不得调用状态迁移、不得执行实现。",
             "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
             initialization.summary,
             "</devflow-planner-directive>",