@guanlin4924/devflow-pi 0.1.0

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

@@ -0,0 +1,1642 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+
+export type DevflowIntent = "idle" | "explain-state" | "project-init" | "requirement-draft" | "workflow-execute";
+
+export type ControlPhase = "idle" | "planning" | "awaiting-approval" | "waiting-user" | "executing" | "blocked";
+
+export type SessionControlState = {
+  intent: DevflowIntent;
+  phase: ControlPhase;
+  label: string;
+};
+
+type ActiveExecutionContract = {
+  contractId: string;
+  feature: string;
+  step: string;
+  allowedPaths: string[];
+  allowedAgents: string[];
+  acceptance: string[];
+  onUnknown: "block_and_escalate";
+};
+
+const READ_ONLY_TOOLS = new Set([
+  "read",
+  "grep",
+  "find",
+  "glob",
+  "lsp",
+  "search",
+  "devflow_state",
+  "devflow_doctor",
+  "devflow_code_index",
+  "devflow_context_cursor",
+  "devflow_usage_stats",
+]);
+
+const PLANNING_AGENTS = new Set(["project-scout", "requirements-auditor", "contract-auditor"]);
+
+const STATE_MUTATION_TOOLS = new Set([
+  "devflow_bootstrap",
+  "devflow_transition",
+  "devflow_artifact",
+  "devflow_context_sync",
+  "devflow_evidence",
+]);
+
+export function initialControlState(): SessionControlState {
+  return { intent: "idle", phase: "idle", label: "对话（不自动执行）" };
+}
+
+export function classifyNaturalLanguageIntent(input: string): DevflowIntent | null {
+  const text = input.trim();
+  if (!text) return null;
+  if (/^(?:查看|看|解释|说明).{0,12}(?:状态|进度)|^(?:当前)?状态(?:是什么|如何|\?|？)?$/.test(text)) {
+    return "explain-state";
+  }
+  if (/^(?:初始化|新建).{0,8}(?:项目|工程)|^(?:项目|工程)初始化$/.test(text)) {
+    return "project-init";
+  }
+  if (/^(?:开始|新增|录入)?(?:需求)\s*[:：]/.test(text) || /^(?:我有个)?需求[：:]/.test(text)) {
+    return "requirement-draft";
+  }
+  return null;
+}
+
+export function planningState(intent: "project-init" | "requirement-draft"): SessionControlState {
+  return {
+    intent,
+    phase: "planning",
+    label: intent === "project-init" ? "项目初始化规划（只读）" : "需求梳理（只读）",
+  };
+}
+
+export function executingState(label = "当前工作流步骤执行"): SessionControlState {
+  return { intent: "workflow-execute", phase: "executing", label };
+}
+
+export function waitingUserState(label = "等待用户确认"): SessionControlState {
+  return { intent: "workflow-execute", phase: "waiting-user", label };
+}
+
+export function statusText(state: SessionControlState): string {
+  return `意图：${state.intent} | 模式：${state.label}`;
+}
+
+export function isPlanningToolAllowed(toolName: string, taskAgents: string[] = []): boolean {
+  const normalized = toolName.toLowerCase();
+  if (READ_ONLY_TOOLS.has(normalized)) return true;
+  if (normalized !== "task") return false;
+  return taskAgents.length > 0 && taskAgents.every(agent => PLANNING_AGENTS.has(agent));
+}
+
+export function isStateMutationTool(toolName: string): boolean {
+  return STATE_MUTATION_TOOLS.has(toolName.toLowerCase());
+}
+
+export function planningToolBlockReason(toolName: string): string {
+  return `Devflow ${toolName} blocked: current intent is planning. Planning is read-only; present an Evidence Pack or plan and wait for explicit approval before writing or executing.`;
+}
+
+const DEVFLOW_CHINESE_LANGUAGE_POLICY = `
+Devflow 语言策略（强制）：
+- 默认使用简体中文与用户沟通。
+- 需求、计划、Evidence Pack、Execution Contract、审查报告、验证报告和阻塞原因必须使用简体中文。
+- 文件名、类名、函数名、接口路径、命令、代码、日志原文和模型/Agent 名称保持原样，不翻译标识符。
+- 推理时先区分“事实、推断、未知、待用户确认”，不要用英文长篇解释替代证据。
+- 如果引用英文源码或工具输出，保留原文并紧跟中文解释。
+- 不要因为语言切换而扩大任务范围；未知项用中文明确写出并停止。
+`;
+
+type ProcessResult = {
+  ok: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+type DoctorStatus = "pass" | "warn" | "fail";
+
+type DoctorCheck = {
+  id: string;
+  status: DoctorStatus;
+  message: string;
+};
+
+type DoctorReport = {
+  ok: boolean;
+  checks: DoctorCheck[];
+  models: Record<string, string>;
+};
+
+type ModelLike = {
+  provider?: unknown;
+  id?: unknown;
+  name?: unknown;
+};
+
+type DoctorContext = {
+  cwd: string;
+  models: {
+    resolve(spec: string): ModelLike | undefined;
+  };
+};
+
+const CONTROL_PATHS = [
+  ".planning/STATE.md",
+  ".planning/.next-intent",
+  ".planning/.devflow.lock",
+  ".planning/artifacts/index.yaml",
+];
+
+const CONTROL_PREFIXES = [".planning/workflows/", ".planning/contracts/"];
+
+const REQUIRED_EXTENSION_TOOLS = [
+  "devflow_doctor",
+  "devflow_state",
+  "devflow_bootstrap",
+  "devflow_transition",
+  "devflow_artifact",
+  "devflow_skill_script",
+  "devflow_context_sync",
+  "devflow_code_index",
+  "devflow_context_cursor",
+  "devflow_design_rule",
+  "devflow_mainflow",
+];
+
+const REQUIRED_SKILLS = [
+  "code-index-query",
+  "code-review",
+  "requirement-feasibility-review",
+  "workflow-api-call-guide",
+  "workflow-api-contract",
+  "workflow-api-supplement",
+  "workflow-audit-milestone",
+  "workflow-backend-tech-spec",
+  "workflow-bug-fix",
+  "workflow-change-plan",
+  "workflow-code-index",
+  "workflow-complete-milestone",
+  "workflow-context-sync",
+  "workflow-demand-clarify",
+  "workflow-design-rule-pack",
+  "workflow-domain-modeling",
+  "workflow-execute-phase",
+  "workflow-feature-breakdown",
+  "workflow-frontend-tech-spec",
+  "workflow-generate-mainflow-cases",
+  "workflow-integration-verify",
+  "workflow-orchestrator",
+  "workflow-pipeline",
+  "workflow-project-context",
+  "workflow-requirement-baseline",
+  "workflow-requirement-triage",
+  "workflow-ui-spec",
+  "workflow-update-navigation",
+  "workflow-verify-work",
+  "workflow-wayfinder",
+];
+
+const PLUGIN_NAMES = [
+  "devflow-core",
+  "devflow-intel",
+  "devflow-requirements",
+  "devflow-design",
+  "devflow-implementation",
+  "devflow-quality",
+];
+
+const REQUIRED_AGENTS: Record<string, { file: string; role: string }> = {
+  "project-scout": { file: "project-scout.md", role: "@smol" },
+  "requirements-auditor": { file: "requirements-auditor.md", role: "@slow" },
+  "contract-auditor": { file: "contract-auditor.md", role: "@slow" },
+  "implementation-worker": { file: "implementation-worker.md", role: "@task" },
+  "devflow-code-reviewer": { file: "code-reviewer.md", role: "@slow" },
+  "verification-runner": { file: "verification-runner.md", role: "@task" },
+};
+
+const REQUIRED_MODEL_ROLES = ["@smol", "@task", "@slow"];
+const REQUIRED_AGENT_NAMES = new Set(Object.keys(REQUIRED_AGENTS));
+
+const REQUIRED_SCRIPTS = [
+  "workflow-orchestrator/scripts/init_workflow.rb",
+  "workflow-orchestrator/scripts/init_state.rb",
+  "workflow-orchestrator/scripts/inspect_state.rb",
+  "workflow-orchestrator/scripts/advance_state.rb",
+  "workflow-orchestrator/scripts/sync_artifacts.rb",
+  "workflow-code-index/scripts/code_index.py",
+  "workflow-context-sync/scripts/context_sync_cursor.py",
+];
+
+function resolvePluginRoot(): string {
+  const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(process.env.DEVFLOW_PLUGIN_ROOT || path.resolve(moduleDirectory, "../.."));
+}
+
+function isEmbeddedRuntime(): boolean {
+  return process.env.DEVFLOW_RUNTIME_MODE === "embedded";
+}
+
+/**
+ * Embedded Devflow Pi never executes a target project's legacy `.skills`
+ * copy. Legacy OMP installation mode intentionally retains its old lookup
+ * order for backwards compatibility.
+ */
+function resolveKitRoot(cwd: string): string {
+  if (isEmbeddedRuntime()) {
+    const packaged = path.join(resolvePluginRoot(), "devflow-core", "skills");
+    if (existsSync(path.join(packaged, "workflow-orchestrator", "scripts", "inspect_state.rb"))) {
+      return packaged;
+    }
+    throw new Error(`Embedded Devflow Pi core skills are missing: ${packaged}`);
+  }
+  const configured = process.env.DEVFLOW_KIT_ROOT;
+  const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const pluginSkills = path.resolve(moduleDirectory, "../skills");
+  const repositoryRoot = path.resolve(moduleDirectory, "../../..");
+  const candidates = [configured, path.join(cwd, ".skills"), pluginSkills, repositoryRoot].filter(
+    Boolean,
+  ) as string[];
+  for (const candidate of candidates) {
+    if (existsSync(path.join(candidate, "workflow-orchestrator", "scripts", "inspect_state.rb"))) {
+      return path.resolve(candidate);
+    }
+  }
+  throw new Error(
+    "Devflow skill root not found. Keep the kit at <project>/.skills or set DEVFLOW_KIT_ROOT.",
+  );
+}
+
+function devflowSkillRoots(cwd: string): string[] {
+  const pluginRoot = resolvePluginRoot();
+  const roots = isEmbeddedRuntime() ? [] : [path.join(cwd, ".skills")];
+  roots.push(...PLUGIN_NAMES.map(plugin => path.join(pluginRoot, plugin, "skills")));
+  return [...new Set(roots.map(root => path.resolve(root)))];
+}
+
+function assertRuntimeProjectBoundary(cwd: string): void {
+  const resolvedCwd = realpathSync(cwd);
+  const configured = process.env.DEVFLOW_PROJECT_ROOT;
+  if (configured && realpathSync(configured) !== resolvedCwd) {
+    throw new Error(`Devflow project-root mismatch: session=${resolvedCwd}, configured=${configured}`);
+  }
+  const planningRoot = path.join(resolvedCwd, ".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",
+  ]) {
+    const target = path.join(resolvedCwd, relative);
+    try {
+      if (lstatSync(target).isSymbolicLink()) {
+        throw new Error(`Refusing symlinked Devflow control path: ${target}`);
+      }
+      const canonical = realpathSync(target);
+      if (!canonical.startsWith(`${resolvedCwd}${path.sep}`)) {
+        throw new Error(`Devflow control path escapes project boundary: ${canonical}`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+function safeControlPath(cwd: string, raw: string | undefined, kind: "state" | "workflow"): string | undefined {
+  if (raw === undefined) return undefined;
+  if (path.isAbsolute(raw)) throw new Error(`${kind} path must be project-relative`);
+  const relative = normalizedProjectPath(raw, cwd);
+  const allowed =
+    kind === "state"
+      ? relative === ".planning/STATE.md"
+      : Boolean(relative?.startsWith(".planning/workflows/") && relative.endsWith(".yaml"));
+  if (!relative || !allowed) throw new Error(`Invalid ${kind} control path: ${raw}`);
+  return relative;
+}
+
+function resolveIntelSkillRoot(cwd: string): string | undefined {
+  if (isEmbeddedRuntime()) {
+    const packaged = path.join(resolvePluginRoot(), "devflow-intel", "skills");
+    return existsSync(path.join(packaged, "workflow-code-index/scripts/code_index.py")) ? packaged : undefined;
+  }
+  const candidates = [
+    path.join(cwd, ".skills"),
+    path.join(cwd, ".omp/plugins/node_modules/@devflow/omp-intel/skills"),
+    path.join(resolvePluginRoot(), "devflow-intel", "skills"),
+  ];
+  return candidates.find(candidate =>
+    existsSync(path.join(candidate, "workflow-code-index/scripts/code_index.py")),
+  );
+}
+
+function requestedTaskAgents(input: unknown): { names: string[]; missing: boolean } {
+  if (!input || typeof input !== "object") return { names: [], missing: true };
+  const record = input as Record<string, unknown>;
+  const values: unknown[] = [];
+  if (Array.isArray(record.tasks)) {
+    values.push(...record.tasks.map(task => (task && typeof task === "object" ? (task as Record<string, unknown>).agent : undefined)));
+  } else {
+    values.push(record.agent);
+  }
+  const names = values.filter((value): value is string => typeof value === "string" && value.trim() !== "").map(value => value.trim());
+  return { names, missing: values.length === 0 || names.length !== values.length };
+}
+
+function agentShadowIssue(cwd: string, name: string): string | undefined {
+  const definition = REQUIRED_AGENTS[name];
+  if (!definition) return `agent ${name} is outside the Devflow allowlist`;
+  const packaged = PLUGIN_NAMES.map(plugin => path.join(resolvePluginRoot(), plugin, "agents", definition.file)).find(candidate => existsSync(candidate));
+  if (!packaged) return `packaged agent definition is missing for ${name}`;
+  const expected = readFileSync(packaged, "utf8");
+  const roots = [
+    path.join(cwd, ".omp", "agents"),
+    process.env.PI_CODING_AGENT_DIR ? path.join(process.env.PI_CODING_AGENT_DIR, "agents") : undefined,
+  ].filter(Boolean) as string[];
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+      const candidate = path.join(root, entry.name);
+      const content = readFileSync(candidate, "utf8");
+      if (!new RegExp(`^name:\\s*["']?${name}["']?\\s*$`, "m").test(content)) continue;
+      if (content !== expected) return `${candidate} shadows packaged agent ${name} with different content`;
+    }
+  }
+  return undefined;
+}
+
+async function runProcess(
+  command: string[],
+  cwd: string,
+  env: Record<string, string | undefined> = {},
+  stdin?: string,
+): Promise<ProcessResult> {
+  const processHandle = Bun.spawn(command, {
+    cwd,
+    env: { ...process.env, ...env },
+    stdin: stdin === undefined ? undefined : "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (stdin !== undefined && processHandle.stdin) {
+    processHandle.stdin.write(stdin);
+    processHandle.stdin.end();
+  }
+  const [exitCode, stdout, stderr] = await Promise.all([
+    processHandle.exited,
+    new Response(processHandle.stdout).text(),
+    new Response(processHandle.stderr).text(),
+  ]);
+  return {
+    ok: exitCode === 0,
+    exitCode,
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+  };
+}
+
+function renderResult(result: ProcessResult, details: Record<string, unknown> = {}) {
+  const text = result.stdout || result.stderr || `Process exited with ${result.exitCode}`;
+  return {
+    content: [{ type: "text" as const, text }],
+    details: { ...details, exitCode: result.exitCode, stderr: result.stderr || undefined },
+    isError: !result.ok,
+  };
+}
+
+function registeredNames(value: unknown): Set<string> {
+  if (Array.isArray(value)) {
+    return new Set(
+      value
+        .map(item => {
+          if (typeof item === "string") return item;
+          if (!item || typeof item !== "object") return "";
+          const record = item as Record<string, unknown>;
+          return String(record.name ?? record.command ?? record.id ?? "");
+        })
+        .filter(Boolean),
+    );
+  }
+  if (value && typeof value === "object") return new Set(Object.keys(value as Record<string, unknown>));
+  return new Set();
+}
+
+function modelIdentity(model: ModelLike): string | null {
+  const provider = typeof model.provider === "string" ? model.provider : "";
+  const id = typeof model.id === "string" ? model.id : "";
+  if (provider && id) return `${provider}/${id}`;
+  if (id) return id;
+  return typeof model.name === "string" && model.name ? model.name : null;
+}
+
+function formatDoctorReport(report: DoctorReport): string {
+  const icon: Record<DoctorStatus, string> = { pass: "PASS", warn: "WARN", fail: "FAIL" };
+  const lines = [`Devflow doctor: ${report.ok ? "PASS" : "FAIL"}`];
+  for (const check of report.checks) {
+    lines.push(`[${icon[check.status]}] ${check.id}: ${check.message}`);
+  }
+  const modelEntries = Object.entries(report.models);
+  if (modelEntries.length > 0) {
+    lines.push(`models: ${modelEntries.map(([role, model]) => `${role}=${model}`).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+function parseJsonResult(result: ProcessResult): Record<string, unknown> | null {
+  if (!result.ok || !result.stdout) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function compactStep(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object") return null;
+  const step = value as Record<string, unknown>;
+  return {
+    id: step.id,
+    label: step.label,
+    skill: step.skill,
+    action: step.action,
+    inputs: step.inputs,
+    outputs: Array.isArray(step.outputs)
+      ? step.outputs.map(output => {
+          if (!output || typeof output !== "object") return output;
+          const record = output as Record<string, unknown>;
+          return {
+            path: record.path ?? record.resolved_path,
+            required: record.required,
+            exists: record.exists,
+            artifact_status: record.artifact_status,
+          };
+        })
+      : undefined,
+  };
+}
+
+function workflowDirective(snapshot: Record<string, unknown>, source: "start" | "resume" | "continue"): string {
+  const selectedStep = compactStep(snapshot.next_step) ?? compactStep(snapshot.current_step);
+  const envelope = {
+    source,
+    action: snapshot.action,
+    revision: snapshot.revision,
+    feature: snapshot.current_feature,
+    phase: snapshot.current_phase,
+    checkpoint: snapshot.checkpoint,
+    step: selectedStep,
+    parallel_window: snapshot.parallel_window,
+    failure_branch: snapshot.failure_branch,
+    reason: snapshot.reason,
+    recovery: snapshot.recovery,
+  };
+  return [
+    "<devflow-runtime-directive>",
+    "Devflow 已通过启动预检。读取 skill://workflow-pipeline，并只执行当前项目的一个工作流步骤。",
+    "先调用 devflow_state(action=\"inspect\") 重新确认 revision，再由 workflow-orchestrator 路由当前步骤。",
+    "只按 inspector 返回的当前 step 加载所需 Skill；不得调用 devflow_transition、不得推进下一步骤、不得替用户通过人工 checkpoint。",
+    "完成本步骤的真实产物后，报告证据、未决项和验证结果并停止，等待用户执行 /devflow advance。",
+    "当前步骤信封：",
+    JSON.stringify(envelope, null, 2),
+    "</devflow-runtime-directive>",
+  ].join("\n");
+}
+
+function explainWorkflowSnapshot(snapshot: Record<string, unknown> | null): string {
+  if (!snapshot) return "Devflow 当前没有可解释的工作流状态。可使用 /devflow start <feature> 创建新 Feature。";
+  const step = compactStep(snapshot.next_step) ?? compactStep(snapshot.current_step);
+  const lines = [
+    `Feature：${String(snapshot.current_feature ?? "未开始")}`,
+    `状态：${String(snapshot.status ?? "unknown")}`,
+    `动作：${String(snapshot.action ?? "unknown")}`,
+    `Revision：${String(snapshot.revision ?? "unknown")}`,
+  ];
+  if (step?.id) lines.push(`当前/下一步骤：${String(step.id)}${step.label ? `（${String(step.label)}）` : ""}`);
+  if (snapshot.checkpoint) lines.push(`Checkpoint：${String(snapshot.checkpoint)}`);
+  if (snapshot.action === "workflow_complete") {
+    lines.push("结论：上一 Feature 已完成；可以使用 /devflow start <新功能名> 创建下一 Feature。");
+  } else {
+    lines.push("结论：这是只读解释；未执行任何状态迁移或文件写入。");
+  }
+  return lines.join("\n");
+}
+
+function normalizedProjectPath(raw: unknown, cwd: string): string | null {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  const absolute = path.resolve(cwd, raw);
+  const relative = path.relative(cwd, absolute).replaceAll("\\", "/");
+  if (relative === ".." || relative.startsWith("../")) return null;
+  return relative.replace(/^\.\//, "");
+}
+
+function inputPaths(input: unknown, cwd: string): string[] {
+  if (!input || typeof input !== "object") return [];
+  const record = input as Record<string, unknown>;
+  const values = [record.file_path, record.filePath, record.path, record.target];
+  if (Array.isArray(record.paths)) values.push(...record.paths);
+  return values
+    .map(value => normalizedProjectPath(value, cwd))
+    .filter((value): value is string => value !== null);
+}
+
+function isControlPath(filePath: string): boolean {
+  return CONTROL_PATHS.includes(filePath) || CONTROL_PREFIXES.some(prefix => filePath.startsWith(prefix));
+}
+
+function isDirectControlMutation(toolName: string, input: unknown, cwd: string): boolean {
+  if (!["write", "edit", "apply_patch", "notebook_edit"].includes(toolName)) return false;
+  return inputPaths(input, cwd).some(isControlPath);
+}
+
+function isShellControlMutation(toolName: string, input: unknown): boolean {
+  if (!["bash", "shell", "exec_command"].includes(toolName) || !input || typeof input !== "object") {
+    return false;
+  }
+  const command = String((input as Record<string, unknown>).command ?? (input as Record<string, unknown>).cmd ?? "");
+  if (!command) return false;
+  const invokesWriter =
+    /workflow-orchestrator\/scripts\/(?:advance_state|init_state|init_workflow|sync_artifacts)\.rb[^\n]*--write/.test(
+      command,
+    );
+  const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item));
+  const looksLikeWrite = /(?:^|[;&|]\s*)(?:rm|mv|cp|install|truncate)\b|(?:^|\s)(?:tee|sed\s+-i|perl\s+-i)\b|>{1,2}/.test(
+    command,
+  );
+  return invokesWriter || (namesControlPath && looksLikeWrite);
+}
+
+function shellMutationPaths(command: string, cwd: string): { mutating: boolean; paths: string[] } {
+  const mutating = /(?:\bsed\s+-i\b|\bperl\s+-i\b|\b(?:cp|mv|rm|install|truncate|tee)\b|(?:^|\s)>{1,2}\s*\S|\b(?:python3?|node|ruby)\b[^\n]*(?:writeFile|write_text|open\([^\n]*['\"]w|unlink|rename)\b)/i.test(command);
+  if (!mutating) return { mutating: false, paths: [] };
+  const candidates = command.match(/(?:^|\s|>)([A-Za-z0-9_./~-]+)(?=\s|$|2?>)/g) ?? [];
+  const paths = candidates
+    .map(value => value.replace(/^\s|^>/g, "").trim())
+    .filter(value => value && !["-i", "-f", "-r", "-p", "sudo"].includes(value))
+    .map(value => normalizedProjectPath(value, cwd))
+    .filter((value): value is string => value !== null && value !== "");
+  return { mutating: true, paths };
+}
+
+export default function devflowCore(pi: ExtensionAPI) {
+  const { z } = pi.zod;
+  let sessionId = randomUUID();
+  let controlState: SessionControlState = initialControlState();
+  let activeContract: ActiveExecutionContract | undefined;
+  let toolCalls = 0;
+  const toolCallBudget = 40;
+
+  function setControlState(ctx: { ui: { setStatus(key: string, text: string | undefined): void } }, state: SessionControlState) {
+    if (state.phase === "executing" && controlState.phase !== "executing") toolCalls = 0;
+    controlState = state;
+    ctx.ui.setStatus("devflow-control", statusText(state));
+  }
+
+  function normalizeContractSegment(value: string, label: string): string {
+    const normalized = value.trim();
+    if (!/^[\p{L}\p{N}][\p{L}\p{N}._-]{0,119}$/u.test(normalized)) {
+      throw new Error(`${label} must be 1-120 letters, numbers, dot, underscore, or hyphen without path separators`);
+    }
+    return normalized;
+  }
+
+  function contractAllowsPath(contract: ActiveExecutionContract, filePath: string): boolean {
+    return contract.allowedPaths.some(root => filePath === root || filePath.startsWith(`${root}/`));
+  }
+
+  async function persistContract(cwd: string, contract: ActiveExecutionContract): Promise<string> {
+    assertRuntimeProjectBoundary(cwd);
+    const feature = normalizeContractSegment(contract.feature, "feature");
+    const contractId = normalizeContractSegment(contract.contractId, "contractId");
+    const root = path.join(cwd, ".planning", "contracts", feature);
+    const destination = path.join(root, `${contractId}.json`);
+    await mkdir(root, { recursive: true });
+    const payload = JSON.stringify({ schemaVersion: 1, activatedAt: new Date().toISOString(), ...contract }, null, 2) + "\n";
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    await writeFile(temporary, payload, "utf8");
+    await rename(temporary, destination);
+    return path.relative(cwd, destination).replaceAll("\\", "/");
+  }
+
+  async function collectProjectInitialization(ctx: {
+    ui: {
+      input(title: string, placeholder?: string): Promise<string | undefined>;
+      confirm(title: string, message: string): Promise<boolean>;
+      notify(message: string, type?: "info" | "warning" | "error"): void;
+    };
+  }): Promise<string | null> {
+    const projectName = await ctx.ui.input("Devflow 项目初始化", "项目名称（留空则使用当前目录）");
+    const frontendPath = await ctx.ui.input("前端边界", "前端目录；没有请填写 none");
+    if (frontendPath === undefined) return null;
+    const backendPath = await ctx.ui.input("后端边界", "后端目录；没有请填写 none");
+    if (backendPath === undefined) return null;
+    const buildIndex = await ctx.ui.input("代码索引", "建立索引？输入 yes 或 no");
+    if (buildIndex === undefined) return null;
+    const summary = [
+      `项目名：${projectName?.trim() || "当前目录"}`,
+      `前端：${frontendPath.trim() || "未提供"}`,
+      `后端：${backendPath.trim() || "未提供"}`,
+      `建立代码索引：${buildIndex.trim() || "未提供"}`,
+    ].join("\n");
+    const confirmed = await ctx.ui.confirm("确认项目初始化范围", `${summary}\n\n确认后只进入只读规划，不会创建工作流或写入项目文件。`);
+    if (!confirmed) {
+      ctx.ui.notify("项目初始化已取消；未写入任何文件。", "info");
+      return null;
+    }
+    return summary;
+  }
+
+  async function runRuby(cwd: string, relativeScript: string, args: string[]) {
+    assertRuntimeProjectBoundary(cwd);
+    const kitRoot = resolveKitRoot(cwd);
+    return runProcess(["ruby", path.join(kitRoot, relativeScript), ...args], cwd, {
+      DEVFLOW_KIT_ROOT: kitRoot,
+      OMP_PROJECT_DIR: cwd,
+    });
+  }
+
+  async function runHook(
+    cwd: string,
+    scriptName: string,
+    event: Record<string, unknown>,
+    args: string[] = [],
+  ) {
+    assertRuntimeProjectBoundary(cwd);
+    const kitRoot = resolveKitRoot(cwd);
+    const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+      path.resolve(moduleDirectory, "../runtime/hooks", scriptName),
+      path.join(kitRoot, "templates", "hooks", scriptName),
+      path.resolve(kitRoot, "../runtime/hooks", scriptName),
+    ];
+    const script = candidates.find(candidate => existsSync(candidate));
+    if (!script) throw new Error(`Devflow hook not found: ${scriptName}`);
+    return runProcess(
+      ["python3", script, ...args],
+      cwd,
+      {
+        DEVFLOW_KIT_ROOT: kitRoot,
+        DEVFLOW_INTEL_SKILL_ROOT: resolveIntelSkillRoot(cwd),
+        OMP_PROJECT_DIR: cwd,
+      },
+      JSON.stringify(event),
+    );
+  }
+
+  async function runDoctor(ctx: DoctorContext): Promise<DoctorReport> {
+    const checks: DoctorCheck[] = [];
+    const models: Record<string, string> = {};
+    const add = (id: string, status: DoctorStatus, message: string) => {
+      checks.push({ id, status, message });
+    };
+
+    let kitRoot: string | null = null;
+    try {
+      kitRoot = resolveKitRoot(ctx.cwd);
+      add("kit", "pass", `skill root resolved at ${kitRoot}`);
+    } catch (error) {
+      add("kit", "fail", error instanceof Error ? error.message : String(error));
+    }
+
+    const toolNames = registeredNames(pi.getAllTools());
+    const missingTools = REQUIRED_EXTENSION_TOOLS.filter(name => !toolNames.has(name));
+    add(
+      "extensions",
+      missingTools.length === 0 ? "pass" : "fail",
+      missingTools.length === 0
+        ? "all four runtime extensions registered their required tools"
+        : `missing runtime tools: ${missingTools.join(", ")}; run the full installer and restart OMP`,
+    );
+
+    try {
+      assertRuntimeProjectBoundary(ctx.cwd);
+      add("project-boundary", "pass", `control plane is contained in ${realpathSync(ctx.cwd)}`);
+    } catch (error) {
+      add("project-boundary", "fail", error instanceof Error ? error.message : String(error));
+    }
+
+    const configPath = path.join(ctx.cwd, ".omp", "config.yml");
+    if (isEmbeddedRuntime()) {
+      add("config", "pass", "embedded Devflow Pi owns the managed runtime profile");
+    } else if (!existsSync(configPath)) {
+      add("config", "fail", "missing .omp/config.yml; run bash .skills/install.sh --apply");
+    } else {
+      const config = readFileSync(configPath, "utf8");
+      const requiredConfigPatterns: Array<[string, RegExp]> = [
+        ["project role storage", /modelRoleStorage:\s*project/],
+        ["manual skill diagnostics", /enableSkillCommands:\s*true/],
+        ["task model overrides", /agentModelOverrides:/],
+        ...Object.entries(REQUIRED_AGENTS).map(
+          ([agent, definition]) =>
+            [`${agent} -> ${definition.role}`, new RegExp(`${agent}:\\s*["']?${definition.role}`)] as [string, RegExp],
+        ),
+        ...PLUGIN_NAMES.map(
+          plugin =>
+            [
+              `${plugin} skill source`,
+              new RegExp(`-\\s+\\.skills/plugins/${plugin}/skills`),
+            ] as [string, RegExp],
+        ),
+      ];
+      const missingConfig = requiredConfigPatterns
+        .filter(([, pattern]) => !pattern.test(config))
+        .map(([label]) => label);
+      add(
+        "config",
+        missingConfig.length === 0 ? "pass" : "fail",
+        missingConfig.length === 0
+          ? "project profile contains Devflow skill sources and agent model overrides"
+          : `missing required project settings: ${missingConfig.join(", ")}; review then run installer with --force-config`,
+      );
+    }
+
+    if (kitRoot) {
+      const skillRoots = devflowSkillRoots(ctx.cwd);
+      const missingSkills = REQUIRED_SKILLS.filter(skill => {
+        const candidates = skillRoots.map(root => path.join(root, skill, "SKILL.md"));
+        return !candidates.some(candidate => existsSync(candidate));
+      });
+      add(
+        "skills",
+        missingSkills.length === 0 ? "pass" : "fail",
+        missingSkills.length === 0
+          ? `${REQUIRED_SKILLS.length} required skills are present`
+          : `missing skills: ${missingSkills.join(", ")}`,
+      );
+
+      const missingScripts = REQUIRED_SCRIPTS.filter(
+        script => !skillRoots.some(root => existsSync(path.join(root, script))),
+      );
+      add(
+        "scripts",
+        missingScripts.length === 0 ? "pass" : "fail",
+        missingScripts.length === 0 ? "deterministic workflow scripts are present" : `missing scripts: ${missingScripts.join(", ")}`,
+      );
+    }
+
+    const embeddedAgentRoots = PLUGIN_NAMES.map(plugin => path.join(resolvePluginRoot(), plugin, "agents"));
+    const agentRoots = isEmbeddedRuntime() ? embeddedAgentRoots : [path.join(ctx.cwd, ".omp", "agents")];
+    const invalidAgents = Object.entries(REQUIRED_AGENTS).flatMap(([name, definition]) => {
+      const agentPath = agentRoots.map(root => path.join(root, definition.file)).find(candidate => existsSync(candidate));
+      if (!agentPath) return [`${name}: missing ${definition.file}`];
+      const content = readFileSync(agentPath, "utf8");
+      const hasName = new RegExp(`^name:\\s*["']?${name}["']?\\s*$`, "m").test(content);
+      const hasRole = new RegExp(`^model:\\s*["']?${definition.role}["']?\\s*$`, "m").test(content);
+      if (!hasName || !hasRole) return [`${name}: expected model ${definition.role}`];
+      const shadow = isEmbeddedRuntime() ? agentShadowIssue(ctx.cwd, name) : undefined;
+      return shadow ? [shadow] : [];
+    });
+    add(
+      "agents",
+      invalidAgents.length === 0 ? "pass" : "fail",
+      invalidAgents.length === 0 ? "all task agents are installed with the expected role aliases" : invalidAgents.join(", "),
+    );
+
+    const resolvedModels: string[] = [];
+    for (const role of REQUIRED_MODEL_ROLES) {
+      let model: ModelLike | undefined;
+      try {
+        model = ctx.models.resolve(role);
+      } catch (error) {
+        add(`model:${role}`, "fail", error instanceof Error ? error.message : String(error));
+        continue;
+      }
+      const identity = model && modelIdentity(model);
+      if (!identity) {
+        add(
+          `model:${role}`,
+          "fail",
+          `role is unresolved; assign a concrete authenticated model to ${role} in the project model roles`,
+        );
+        continue;
+      }
+      models[role] = identity;
+      resolvedModels.push(identity);
+      add(`model:${role}`, "pass", identity);
+    }
+    const uniqueModels = new Set(resolvedModels);
+    add(
+      "model-separation",
+      resolvedModels.length === REQUIRED_MODEL_ROLES.length && uniqueModels.size === REQUIRED_MODEL_ROLES.length
+        ? "pass"
+        : "fail",
+      resolvedModels.length === REQUIRED_MODEL_ROLES.length && uniqueModels.size === REQUIRED_MODEL_ROLES.length
+        ? "scout, implementation/verification, and adversarial review resolve to different models"
+        : "@smol, @task, and @slow must resolve to three different concrete models; silent parent-model fallback is not allowed",
+    );
+
+    const commandNames = registeredNames(pi.getCommands());
+    const skillCommands = REQUIRED_SKILLS.map(name => `skill:${name}`);
+    const missingCommands = skillCommands.filter(name => !commandNames.has(name));
+    add(
+      "skills-runtime",
+      missingCommands.length === 0 ? "pass" : "fail",
+      missingCommands.length === 0
+        ? `${REQUIRED_SKILLS.length} skills are registered in the active OMP runtime`
+        : `active OMP runtime is missing skill commands: ${missingCommands.join(", ")}; do not start with --no-skills`,
+    );
+
+    return { ok: checks.every(check => check.status !== "fail"), checks, models };
+  }
+
+  async function inspectWorkflow(cwd: string): Promise<{ result: ProcessResult; snapshot: Record<string, unknown> | null }> {
+    const result = await runRuby(cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]);
+    return { result, snapshot: parseJsonResult(result) };
+  }
+
+  async function triggerWorkflow(snapshot: Record<string, unknown>, source: "start" | "resume" | "continue") {
+    await pi.sendUserMessage(workflowDirective(snapshot, source));
+  }
+
+  pi.setLabel("Devflow Project Runtime");
+
+  pi.on("session_start", async (_event, ctx) => {
+    sessionId = randomUUID();
+    const result = await runHook(ctx.cwd, "start.py", {
+      session_id: sessionId,
+      cwd: ctx.cwd,
+      source: "startup",
+      hook_event_name: "SessionStart",
+    });
+    if (!result.ok) {
+      ctx.ui.notify(`Devflow bootstrap failed: ${result.stderr || result.stdout}`, "error");
+      return;
+    }
+    ctx.ui.setStatus("devflow", "Devflow ready");
+    setControlState(ctx, initialControlState());
+  });
+
+  pi.on("before_agent_start", async event => ({
+    systemPrompt: [...event.systemPrompt, DEVFLOW_CHINESE_LANGUAGE_POLICY],
+  }));
+
+  pi.on("input", async (event, ctx) => {
+    if (event.source !== "interactive") return;
+    const intent = classifyNaturalLanguageIntent(event.text);
+    if (intent === "explain-state") {
+      const inspected = await inspectWorkflow(ctx.cwd);
+      ctx.ui.notify(
+        inspected.result.ok ? explainWorkflowSnapshot(inspected.snapshot) : `状态读取失败：${inspected.result.stderr || inspected.result.stdout}`,
+        inspected.result.ok ? "info" : "error",
+      );
+      setControlState(ctx, initialControlState());
+      return { handled: true };
+    }
+    if (intent === "project-init") {
+      const summary = await collectProjectInitialization(ctx);
+      if (!summary) return { handled: true };
+      const state = planningState("project-init");
+      setControlState(ctx, state);
+      return {
+        text: [
+          "<devflow-planner-directive>",
+          "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
+          "不得创建 .planning 文件、不得调用状态迁移、不得执行实现。",
+          "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
+          summary,
+          "</devflow-planner-directive>",
+        ].join("\n"),
+      };
+    }
+    if (intent === "requirement-draft") {
+      const state = planningState("requirement-draft");
+      setControlState(ctx, state);
+      return {
+        text: [
+          "<devflow-planner-directive>",
+          "当前是需求梳理（只读）阶段。只允许澄清、收集证据、派发只读审查代理和输出计划草案。",
+          "不得开始工作流、不得写入产物、不得调用实现代理或状态迁移。",
+          "把用户目标、约束、未知项、反例和下一步最少问题分开列出；缺少证据时不得猜测。",
+          event.text,
+          "</devflow-planner-directive>",
+        ].join("\n"),
+      };
+    }
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    toolCalls += 1;
+    if (toolCalls > toolCallBudget && controlState.phase === "executing") {
+      return {
+        block: true,
+        reason: `本步骤已达到工具调用上限（${toolCallBudget}）。已自动停止，请检查证据后使用 /devflow advance 或重新 /devflow continue。`,
+      };
+    }
+    const toolName = String(event.toolName).toLowerCase();
+    if (toolName === "task") {
+      const requested = requestedTaskAgents(event.input);
+      if (requested.missing) {
+        return {
+          block: true,
+          reason: "Devflow task calls must name an explicit role agent; parent-model/default-agent fallback is forbidden.",
+        };
+      }
+      const disallowed = requested.names.filter(name => !REQUIRED_AGENT_NAMES.has(name));
+      if (disallowed.length > 0) {
+        return {
+          block: true,
+          reason: `Devflow task agent is outside the product allowlist: ${disallowed.join(", ")}`,
+        };
+      }
+      const shadows = requested.names.map(name => agentShadowIssue(ctx.cwd, name)).filter(Boolean);
+      if (shadows.length > 0) {
+        return { block: true, reason: `Devflow task agent shadow detected: ${shadows.join("; ")}` };
+      }
+      if (controlState.phase === "planning" && !isPlanningToolAllowed(toolName, requested.names)) {
+        return { block: true, reason: planningToolBlockReason(toolName) };
+      }
+      if (
+        activeContract &&
+        controlState.phase === "executing" &&
+        !requested.names.every(agent => activeContract?.allowedAgents.includes(agent))
+      ) {
+        return { block: true, reason: `Active contract ${activeContract.contractId} only allows agents: ${activeContract.allowedAgents.join(", ")}` };
+      }
+    } else if (
+      controlState.phase === "planning" &&
+      toolName !== "devflow_contract" &&
+      !(toolName === "devflow_evidence" && String((event.input as Record<string, unknown> | undefined)?.action) !== "create") &&
+      !isPlanningToolAllowed(toolName)
+    ) {
+      return { block: true, reason: planningToolBlockReason(toolName) };
+    }
+    if (isStateMutationTool(toolName)) {
+      return {
+        block: true,
+        reason:
+          "Devflow state transitions are user-command-only. Use /devflow start, /devflow advance, or /devflow checkpoint; an LLM may not advance delivery state directly.",
+      };
+    }
+    if (toolName.startsWith("devflow_")) return;
+    if (
+      activeContract &&
+      controlState.phase === "executing" &&
+      ["write", "edit", "apply_patch", "notebook_edit"].includes(toolName)
+    ) {
+      const paths = inputPaths(event.input, ctx.cwd);
+      if (paths.length === 0 || paths.some(filePath => !contractAllowsPath(activeContract!, filePath))) {
+        return {
+          block: true,
+          reason: `Active contract ${activeContract.contractId} only allows edits under: ${activeContract.allowedPaths.join(", ")}`,
+        };
+      }
+    }
+    if (activeContract && controlState.phase === "executing" && ["bash", "shell", "exec_command"].includes(toolName)) {
+      const command = String((event.input as Record<string, unknown> | undefined)?.command ?? (event.input as Record<string, unknown> | undefined)?.cmd ?? "");
+      const shell = shellMutationPaths(command, ctx.cwd);
+      if (shell.mutating && (shell.paths.length === 0 || shell.paths.some(filePath => !contractAllowsPath(activeContract!, filePath)))) {
+        return {
+          block: true,
+          reason: `Active contract ${activeContract.contractId} 不允许通过 Bash/脚本修改合同外路径；请使用合同允许路径，或先更新合同。`,
+        };
+      }
+    }
+    if (isDirectControlMutation(toolName, event.input, ctx.cwd) || isShellControlMutation(toolName, event.input)) {
+      return {
+        block: true,
+        reason:
+          "Devflow control-plane files are single-writer resources. Use devflow_bootstrap or devflow_transition instead of editing them directly.",
+      };
+    }
+    const gate = await runHook(ctx.cwd, "index_gate.py", {
+      session_id: sessionId,
+      cwd: ctx.cwd,
+      hook_event_name: "PreToolUse",
+      tool_name: event.toolName,
+      tool_input: event.input ?? {},
+    });
+    if (!gate.ok) {
+      return {
+        block: true,
+        reason: `Devflow index gate failed closed: ${gate.stderr || gate.stdout || `exit ${gate.exitCode}`}`,
+      };
+    }
+    if (gate.stdout) {
+      try {
+        const payload = JSON.parse(gate.stdout) as {
+          hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string };
+        };
+        if (payload.hookSpecificOutput?.permissionDecision === "deny") {
+          return {
+            block: true,
+            reason: payload.hookSpecificOutput.permissionDecisionReason || "Devflow index-first gate denied the tool call.",
+          };
+        }
+      } catch {
+        return {
+          block: true,
+          reason: `Devflow index gate returned invalid JSON: ${gate.stdout.slice(0, 1000)}`,
+        };
+      }
+    }
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (event.isError) return;
+    await runHook(ctx.cwd, "post_tool.py", {
+      session_id: sessionId,
+      cwd: ctx.cwd,
+      hook_event_name: "PostToolUse",
+      tool_name: event.toolName,
+      tool_input: event.input ?? {},
+    });
+  });
+
+  pi.on("session_stop", async (_event, ctx) => {
+    const result = await runHook(ctx.cwd, "context_sync_gate.py", {
+      session_id: sessionId,
+      cwd: ctx.cwd,
+      hook_event_name: "Stop",
+    });
+    if (!result.ok || !result.stdout) return;
+    try {
+      const decision = JSON.parse(result.stdout) as { decision?: string; reason?: string };
+      if (decision.decision === "block" && decision.reason) {
+        return {
+          continue: true,
+          additionalContext:
+            `${decision.reason}\nUse skill://workflow-context-sync for the reconciliation procedure, then call ` +
+            "devflow_context_sync(action=\"ack\", level=<reported-level>).",
+        };
+      }
+    } catch {
+      ctx.ui.notify(`Devflow context-sync returned invalid JSON: ${result.stdout}`, "error");
+    }
+  });
+
+  pi.registerTool({
+    name: "devflow_evidence",
+    label: "Devflow Evidence Pack",
+    description: "Create, inspect, and validate structured evidence packs used to prevent unsupported workflow progression.",
+    parameters: z.object({
+      action: z.enum(["create", "inspect", "validate"]),
+      feature: z.string().min(1),
+      taskId: z.string().min(1),
+      pack: z.record(z.string(), z.unknown()).optional(),
+    }),
+    approval: (args) => args.action === "create" ? "write" : "read",
+    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 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"];
+        const record = pack as Record<string, unknown>;
+        const errors: string[] = [];
+        if (record.schemaVersion !== 1) errors.push("schemaVersion must equal 1");
+        for (const key of ["facts", "unknowns", "risks"]) {
+          if (!Array.isArray(record[key])) errors.push(`${key} must be an array`);
+        }
+        if (typeof record.taskId !== "string" || record.taskId !== taskId) errors.push("taskId must match the requested taskId");
+        return errors;
+      };
+      if (params.action === "inspect" || params.action === "validate") {
+        if (!existsSync(destination)) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: `Evidence Pack not found: ${path.relative(ctx.cwd, destination)}` }, { action: params.action });
+        let parsed: unknown;
+        try { parsed = JSON.parse(readFileSync(destination, "utf8")); } catch (error) {
+          return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: `Invalid Evidence Pack JSON: ${String(error)}` }, { action: params.action });
+        }
+        const errors = validatePack(parsed);
+        if (params.action === "validate") return renderResult({ ok: errors.length === 0, exitCode: errors.length === 0 ? 0 : 1, stdout: errors.length === 0 ? "Evidence Pack valid" : "", stderr: errors.join("; ") }, { action: params.action, errors });
+        return { content: [{ type: "text" as const, text: JSON.stringify(parsed, null, 2) }], details: { action: params.action, path: path.relative(ctx.cwd, destination), errors } };
+      }
+      if (!params.pack) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "pack is required for create" }, { action: params.action });
+      const pack = { schemaVersion: 1, taskId, createdAt: new Date().toISOString(), ...params.pack };
+      const errors = validatePack(pack);
+      if (errors.length > 0) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: errors.join("; ") }, { action: params.action, errors });
+      await mkdir(root, { recursive: true });
+      await writeFile(destination, JSON.stringify(pack, null, 2) + "\n", "utf8");
+      return { content: [{ type: "text" as const, text: `Evidence Pack created: ${path.relative(ctx.cwd, destination)}` }], details: { action: params.action, path: path.relative(ctx.cwd, destination) } };
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_contract",
+    label: "Devflow Execution Contract",
+    description: "Show or activate a user-confirmed, path-bounded execution contract. Only an active contract may authorize low-cost implementation agents.",
+    parameters: z.object({
+      action: z.enum(["status", "activate"]),
+      contractId: z.string().min(1).optional(),
+      feature: z.string().min(1).optional(),
+      step: z.string().min(1).optional(),
+      allowedPaths: z.array(z.string().min(1)).default([]),
+      allowedAgents: z.array(z.enum(["implementation-worker", "verification-runner"])).default([]),
+      acceptance: z.array(z.string().min(1)).default([]),
+    }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const input = params as {
+        action: "status" | "activate";
+        contractId?: string;
+        feature?: string;
+        step?: string;
+        allowedPaths: string[];
+        allowedAgents: string[];
+        acceptance: string[];
+      };
+      if (input.action === "status") {
+        return {
+          content: [{ type: "text" as const, text: activeContract ? JSON.stringify(activeContract, null, 2) : "No active execution contract in this session." }],
+          details: { activeContract },
+        };
+      }
+      if (controlState.phase !== "planning") {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "Contracts may only be activated from the planning phase." });
+      }
+      if (!input.contractId || !input.feature || !input.step || input.allowedPaths.length === 0 || input.allowedAgents.length === 0 || input.acceptance.length === 0) {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "contractId, feature, step, allowedPaths, allowedAgents, and acceptance are required." });
+      }
+      let allowedPaths: string[];
+      try {
+        allowedPaths = input.allowedPaths.map(candidate => {
+          const relative = normalizedProjectPath(candidate, ctx.cwd);
+          if (!relative || relative.startsWith(".planning/")) throw new Error(`Invalid contract path: ${candidate}`);
+          return relative.replace(/\/$/, "");
+        });
+      } catch (error) {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: error instanceof Error ? error.message : String(error) });
+      }
+      const contract: ActiveExecutionContract = {
+        contractId: input.contractId,
+        feature: input.feature,
+        step: input.step,
+        allowedPaths: [...new Set(allowedPaths)],
+        allowedAgents: [...new Set(input.allowedAgents)],
+        acceptance: [...new Set(input.acceptance)],
+        onUnknown: "block_and_escalate",
+      };
+      const confirmed = await ctx.ui.confirm(
+        "激活 Devflow 执行合同",
+        [
+          `合同：${contract.contractId}`,
+          `Feature：${contract.feature}`,
+          `步骤：${contract.step}`,
+          `可写路径：${contract.allowedPaths.join(", ")}`,
+          `允许 Agent：${contract.allowedAgents.join(", ")}`,
+          `验收：${contract.acceptance.join("；")}`,
+          "确认后低成本模型只能在以上范围执行；未知项必须阻塞升级。",
+        ].join("\n"),
+      );
+      if (!confirmed) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "User declined execution contract activation." });
+      try {
+        const destination = await persistContract(ctx.cwd, contract);
+        activeContract = contract;
+        setControlState(ctx, executingState(`合同执行：${contract.contractId}`));
+        return {
+          content: [{ type: "text" as const, text: `Execution contract activated: ${destination}` }],
+          details: { contract, destination },
+        };
+      } catch (error) {
+        return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_state",
+    label: "Devflow State",
+    description: "Inspect or validate the project delivery state without mutating it.",
+    parameters: z.object({
+      action: z.enum(["inspect", "validate"]),
+      state: z.string().optional(),
+    }),
+    approval: "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const script =
+        params.action === "inspect"
+          ? "workflow-orchestrator/scripts/inspect_state.rb"
+          : "workflow-orchestrator/scripts/validate_state.rb";
+      const args = ["--json"];
+      const state = safeControlPath(ctx.cwd, params.state, "state");
+      if (state) args.push("--state", state);
+      return renderResult(await runRuby(ctx.cwd, script, args), { action: params.action });
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_doctor",
+    label: "Devflow Doctor",
+    description: "Verify the complete Devflow runtime, project profile, skills, agents, scripts, and distinct task-model bindings.",
+    parameters: z.object({}),
+    approval: "read",
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const report = await runDoctor(ctx);
+      return {
+        content: [{ type: "text" as const, text: formatDoctorReport(report) }],
+        details: report,
+        isError: !report.ok,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_bootstrap",
+    label: "Devflow Bootstrap",
+    description: "Initialize workflow definitions, STATE.md, and the artifact registry for a project feature.",
+    parameters: z.object({
+      feature: z.string().min(1),
+      phase: z.string().min(1).default("delivery"),
+      flow: z.string().min(1).default("feature-development"),
+      force: z.boolean().default(false),
+    }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const force = params.force ? ["--force"] : [];
+      const workflow = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_workflow.rb", [
+        "--write",
+        "--json",
+        ...force,
+      ]);
+      if (!workflow.ok) return renderResult(workflow, { stage: "workflow" });
+      const state = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_state.rb", [
+        "--feature",
+        params.feature,
+        "--phase",
+        params.phase,
+        "--flow",
+        params.flow,
+        "--write",
+        "--json",
+        ...force,
+      ]);
+      if (!state.ok) return renderResult(state, { stage: "state" });
+      const artifacts = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
+        "--write",
+        "--json",
+      ]);
+      return renderResult(artifacts, {
+        stage: "complete",
+        workflow: workflow.stdout,
+        state: state.stdout,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_transition",
+    label: "Devflow Transition",
+    description: "Apply one validated delivery-state transition. This is the only supported STATE.md mutation path.",
+    parameters: z.object({
+      action: z.enum(["complete-step", "confirm-checkpoint", "checkpoint-decision", "enter-failure-branch"]),
+      step: z.string().optional(),
+      decision: z.string().optional(),
+      state: z.string().optional(),
+      expectedRevision: z.number().int().min(0),
+    }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const args = ["--write", "--json"];
+      const state = safeControlPath(ctx.cwd, params.state, "state");
+      if (state) args.push("--state", state);
+      args.push("--expected-revision", String(params.expectedRevision));
+      if (params.action === "complete-step") {
+        if (!params.step) {
+          return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "step is required" });
+        }
+        args.push("--complete-step", params.step);
+      } else if (params.action === "confirm-checkpoint") {
+        args.push("--confirm-checkpoint");
+      } else if (params.action === "checkpoint-decision") {
+        if (!params.decision) {
+          return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "decision is required" });
+        }
+        args.push("--checkpoint-decision", params.decision);
+      } else {
+        args.push("--enter-failure-branch");
+      }
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", args),
+        { action: params.action },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_artifact",
+    label: "Devflow Artifact Registry",
+    description: "Synchronize the workflow artifact registry from validated state and workflow definitions.",
+    parameters: z.object({
+      action: z.literal("sync"),
+      state: z.string().optional(),
+      workflow: z.string().optional(),
+      preserve: z.boolean().default(true),
+    }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const args = ["--write", "--json"];
+      const state = safeControlPath(ctx.cwd, params.state, "state");
+      const workflow = safeControlPath(ctx.cwd, params.workflow, "workflow");
+      if (state) args.push("--state", state);
+      if (workflow) args.push("--workflow", workflow);
+      if (!params.preserve) args.push("--no-preserve");
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", args),
+        { action: params.action },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_skill_script",
+    label: "Devflow Skill Script",
+    description: "Run an allowlisted deterministic script bundled with a Devflow skill without relying on a .skills filesystem path.",
+    parameters: z.object({
+      script: z.enum([
+        "project-context-validate",
+        "orchestrator-manage-lessons",
+        "orchestrator-update-triage",
+      ]),
+      args: z.array(z.string()).default([]),
+    }),
+    approval: "exec",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const kitRoot = resolveKitRoot(ctx.cwd);
+      const scripts: Record<string, [string, string]> = {
+        "project-context-validate": ["python3", "workflow-project-context/scripts/validate_initialization.py"],
+        "orchestrator-manage-lessons": ["ruby", "workflow-orchestrator/scripts/manage_lessons.rb"],
+        "orchestrator-update-triage": ["ruby", "workflow-orchestrator/scripts/update_triage_route.rb"],
+      };
+      const [runtime, relativeScript] = scripts[params.script];
+      const result = await runProcess(
+        [runtime, path.join(kitRoot, relativeScript), ...params.args],
+        ctx.cwd,
+        { DEVFLOW_KIT_ROOT: kitRoot, OMP_PROJECT_DIR: ctx.cwd },
+      );
+      return renderResult(result, { script: params.script });
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_context_sync",
+    label: "Devflow Context Sync",
+    description: "Acknowledge the exact context-sync change set after the required reconciliation and validation completed.",
+    parameters: z.object({
+      action: z.literal("ack"),
+      level: z.enum(["Light", "Medium", "Full"]),
+    }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const result = await runHook(
+        ctx.cwd,
+        "context_sync_gate.py",
+        { session_id: sessionId, cwd: ctx.cwd },
+        ["mark-synced", "--session-id", sessionId, "--level", params.level],
+      );
+      return renderResult(result, { action: params.action, level: params.level });
+    },
+  });
+
+  pi.registerCommand("devflow", {
+    description: "Devflow runtime: inspect, initialize, plan, run one step, or explicitly advance the controlled delivery pipeline",
+    handler: async (args, ctx) => {
+      const trimmed = args.trim();
+      if (trimmed === "" || trimmed === "status") {
+        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]);
+        ctx.ui.notify((result.stdout || result.stderr).slice(0, 6000), result.ok ? "info" : "error");
+        return;
+      }
+      if (trimmed === "explain-state") {
+        const inspected = await inspectWorkflow(ctx.cwd);
+        ctx.ui.notify(
+          inspected.result.ok ? explainWorkflowSnapshot(inspected.snapshot) : `状态读取失败：${inspected.result.stderr || inspected.result.stdout}`,
+          inspected.result.ok ? "info" : "error",
+        );
+        setControlState(ctx, initialControlState());
+        return;
+      }
+      if (trimmed === "project-init") {
+        const summary = await collectProjectInitialization(ctx);
+        if (!summary) return;
+        setControlState(ctx, planningState("project-init"));
+        await pi.sendUserMessage(
+          [
+            "<devflow-planner-directive>",
+            "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
+            "不得创建 .planning 文件、不得调用状态迁移、不得执行实现。",
+            "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
+            summary,
+            "</devflow-planner-directive>",
+          ].join("\n"),
+        );
+        return;
+      }
+      if (trimmed === "doctor") {
+        const report = await runDoctor(ctx);
+        ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), report.ok ? "info" : "error");
+        return;
+      }
+      if (trimmed === "resume") {
+        const report = await runDoctor(ctx);
+        if (!report.ok) {
+          ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
+          return;
+        }
+        const inspected = await inspectWorkflow(ctx.cwd);
+        if (!inspected.result.ok || !inspected.snapshot) {
+          ctx.ui.notify(
+            `Devflow resume failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`,
+            "error",
+          );
+          return;
+        }
+        if (inspected.snapshot.action === "workflow_complete") {
+          ctx.ui.notify("Devflow workflow is already complete.", "info");
+          return;
+        }
+        setControlState(ctx, waitingUserState("等待用户审查步骤产物"));
+        ctx.ui.notify(
+          `Devflow 已恢复到 ${String((compactStep(inspected.snapshot.next_step) ?? compactStep(inspected.snapshot.current_step))?.id ?? "当前步骤")}；未自动执行。请先查看状态或使用 /devflow continue 执行一个步骤。`,
+          "info",
+        );
+        return;
+      }
+      if (trimmed === "continue") {
+        const report = await runDoctor(ctx);
+        if (!report.ok) {
+          ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
+          return;
+        }
+        const inspected = await inspectWorkflow(ctx.cwd);
+        if (!inspected.result.ok || !inspected.snapshot) {
+          ctx.ui.notify(`Devflow continue failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
+          return;
+        }
+        if (inspected.snapshot.action === "workflow_complete") {
+          ctx.ui.notify("Devflow workflow is already complete.", "info");
+          return;
+        }
+        if (inspected.snapshot.status === "waiting_checkpoint") {
+          setControlState(ctx, { intent: "workflow-execute", phase: "awaiting-approval", label: "等待用户确认 checkpoint" });
+          ctx.ui.notify("当前步骤正在等待 checkpoint；请审查产物后使用 /devflow checkpoint。", "warning");
+          return;
+        }
+        setControlState(ctx, executingState("执行当前工作流步骤（完成后停止）"));
+        ctx.ui.notify("仅启动当前步骤；模型被禁止迁移状态或继续下一步骤。", "info");
+        await triggerWorkflow(inspected.snapshot, "continue");
+        return;
+      }
+      if (trimmed === "advance") {
+        const inspected = await inspectWorkflow(ctx.cwd);
+        if (!inspected.result.ok || !inspected.snapshot) {
+          ctx.ui.notify(`Devflow advance failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
+          return;
+        }
+        if (inspected.snapshot.status === "waiting_checkpoint") {
+          ctx.ui.notify("当前状态等待 checkpoint；请使用 /devflow checkpoint。", "warning");
+          return;
+        }
+        const step = compactStep(inspected.snapshot.next_step) ?? compactStep(inspected.snapshot.current_step);
+        const stepId = typeof step?.id === "string" ? step.id : undefined;
+        const revision = typeof inspected.snapshot.revision === "number" ? inspected.snapshot.revision : undefined;
+        if (!stepId || revision === undefined) {
+          ctx.ui.notify("当前状态没有可推进的步骤或 revision；请先执行 /devflow explain-state。", "error");
+          return;
+        }
+        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
+          "--write",
+          "--json",
+          "--expected-revision",
+          String(revision),
+          "--complete-step",
+          stepId,
+        ]);
+        if (!result.ok) {
+          setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "推进校验失败" });
+          ctx.ui.notify(`步骤未推进：${result.stderr || result.stdout}`, "error");
+          return;
+        }
+        const after = await inspectWorkflow(ctx.cwd);
+        setControlState(
+          ctx,
+          after.snapshot?.status === "waiting_checkpoint"
+            ? { intent: "workflow-execute", phase: "awaiting-approval", label: "等待用户确认 checkpoint" }
+            : waitingUserState("等待用户审查步骤产物"),
+        );
+        ctx.ui.notify(`已完成步骤 ${stepId} 的真实产物校验并推进状态。${after.snapshot?.status === "waiting_checkpoint" ? "下一步需要 /devflow checkpoint。" : "下一步请审查后使用 /devflow continue。"}`, "info");
+        return;
+      }
+      if (trimmed === "checkpoint") {
+        const inspected = await inspectWorkflow(ctx.cwd);
+        if (!inspected.result.ok || !inspected.snapshot) {
+          ctx.ui.notify(`Devflow checkpoint failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
+          return;
+        }
+        if (inspected.snapshot.status !== "waiting_checkpoint") {
+          ctx.ui.notify("当前并不等待 checkpoint；请使用 /devflow explain-state 查看原因。", "warning");
+          return;
+        }
+        const revision = typeof inspected.snapshot.revision === "number" ? inspected.snapshot.revision : undefined;
+        if (revision === undefined) {
+          ctx.ui.notify("当前状态缺少 revision，拒绝确认 checkpoint。", "error");
+          return;
+        }
+        const confirmed = await ctx.ui.confirm("确认 Devflow checkpoint", "你已审查当前步骤产物并同意推进到下一步骤吗？");
+        if (!confirmed) {
+          ctx.ui.notify("checkpoint 未确认；状态保持不变。", "info");
+          return;
+        }
+        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
+          "--write",
+          "--json",
+          "--expected-revision",
+          String(revision),
+          "--confirm-checkpoint",
+        ]);
+        if (!result.ok) {
+          setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "checkpoint 校验失败" });
+          ctx.ui.notify(`checkpoint 未推进：${result.stderr || result.stdout}`, "error");
+          return;
+        }
+        setControlState(ctx, waitingUserState("等待用户确认下一步骤"));
+        ctx.ui.notify("checkpoint 已由用户确认；下一步骤尚未执行，请使用 /devflow continue。", "info");
+        return;
+      }
+      if (trimmed.startsWith("start ")) {
+        const [feature, phase = "delivery"] = trimmed.slice(6).split("|", 2).map(value => value.trim());
+        if (!feature) {
+          ctx.ui.notify("Usage: /devflow start <feature>|<phase>", "error");
+          return;
+        }
+        const report = await runDoctor(ctx);
+        if (!report.ok) {
+          ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
+          return;
+        }
+        const existing = await inspectWorkflow(ctx.cwd);
+        const existingFeature = existing.snapshot?.current_feature;
+        const previousWorkflowComplete = existing.snapshot?.action === "workflow_complete";
+        if (
+          !previousWorkflowComplete &&
+          typeof existingFeature === "string" &&
+          existingFeature !== feature
+        ) {
+          ctx.ui.notify(
+            `An unfinished Devflow state belongs to feature ${existingFeature}. Use /devflow resume and complete that workflow before starting ${feature}.`,
+            "error",
+          );
+          return;
+        }
+        const workflow = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_workflow.rb", [
+          "--write",
+          "--json",
+        ]);
+        if (!workflow.ok) {
+          ctx.ui.notify(workflow.stderr || workflow.stdout, "error");
+          return;
+        }
+        const state = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_state.rb", [
+          "--feature",
+          feature,
+          "--phase",
+          phase,
+          "--flow",
+          "feature-development",
+          "--write",
+          "--json",
+          ...(previousWorkflowComplete ? ["--force"] : []),
+        ]);
+        if (!state.ok) {
+          ctx.ui.notify((state.stderr || state.stdout).slice(0, 6000), "error");
+          return;
+        }
+        const artifacts = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
+          "--write",
+          "--json",
+        ]);
+        if (!artifacts.ok) {
+          ctx.ui.notify((artifacts.stderr || artifacts.stdout).slice(0, 6000), "error");
+          return;
+        }
+        const inspected = await inspectWorkflow(ctx.cwd);
+        if (!inspected.result.ok || !inspected.snapshot) {
+          ctx.ui.notify(
+            `Devflow initialized but inspector failed: ${inspected.result.stderr || inspected.result.stdout || "invalid JSON"}`,
+            "error",
+          );
+          return;
+        }
+        setControlState(ctx, planningState("requirement-draft"));
+        ctx.ui.notify(
+          `Devflow 已创建 Feature ${feature}，但没有自动执行。当前步骤：${String((compactStep(inspected.snapshot.next_step) ?? compactStep(inspected.snapshot.current_step))?.id ?? "requirement-triage")}。请补充需求后使用 /devflow continue。`,
+          "info",
+        );
+        return;
+      }
+      ctx.ui.notify(
+        "Usage: /devflow doctor | status | explain-state | project-init | start <feature>|<phase> | resume | continue | advance | checkpoint",
+        "warning",
+      );
+    },
+  });
+}