@guanlin4924/devflow-pi 0.1.93 → 0.1.95

package/src/cli.ts

@@ -5,6 +5,8 @@ import { readFileSync } from "node:fs";
 
 import { formatDoctor, runHostDoctor } from "./doctor.ts";
 import { initializeProject, loadProjectContext, resolveProjectRoot } from "./project-context.ts";
+import { migrateLegacyProjectLayout } from "./project-layout.ts";
+import { InitializationStore } from "./initialization-store.ts";
 import { aggregateUsage, renderUsage } from "./usage-stats.ts";
 import { projectSessionDir } from "./paths.ts";
 
@@ -12,6 +14,7 @@ function usage(): string {
   return [
     "Usage:",
     "  devflow-pi init [project] [--scan]",
+    "  devflow-pi migrate [project] --confirm-active",
     "  devflow-pi doctor [project]",
     "  devflow-pi usage [project]",
     "  devflow-pi [project] [--resume [session-id]] [--prompt <text>] [--mcp] [--yolo]",
@@ -65,6 +68,18 @@ async function main(): Promise<void> {
     }
     return;
   }
+  if (command === "migrate") {
+    const projectArgument = args[1] && !args[1].startsWith("-") ? args[1] : undefined;
+    if (!args.includes("--confirm-active")) throw new Error("Legacy control-plane migration requires --confirm-active");
+    const requested = projectArgument ? path.resolve(projectArgument) : process.cwd();
+    const root = await resolveProjectRoot(requested, { explicit: requested, allowUninitialized: true });
+    const migrated = await migrateLegacyProjectLayout(root, { allowActive: true, allowUnmanifested: true });
+    const manifest = JSON.parse(readFileSync(path.join(root, ".devflow/project.json"), "utf8"));
+    const store = await InitializationStore.open({ root, manifest });
+    try { await store.registerWorkspace(); } finally { store.close(); }
+    console.log(JSON.stringify({ status: "migrated", root, migrated }, null, 2));
+    return;
+  }
   const positionalProject = command && !["doctor", "usage"].includes(command) && !command.startsWith("-") ? command : undefined;
   const requestedProject = ["doctor", "usage"].includes(command || "") ? args[1] : positionalProject;
   const root = await resolveProjectRoot(process.cwd(), { explicit: requestedProject });

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.93";
+export const PRODUCT_VERSION = "0.1.95";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/doctor.ts

@@ -1,10 +1,22 @@
-import { access, lstat, readFile } from "node:fs/promises";
+import { access, lstat, readFile, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
 
 import { DEVFLOW_PLUGIN_NAMES, OMP_RUNTIME_VERSION, PRODUCT_VERSION } from "./constants.ts";
 import { devflowAgentDir, devflowHome, ompSdkManifestPath, pluginRoots, projectSessionDir } from "./paths.ts";
 import type { ProjectContext } from "./project-context.ts";
 
+const RUNTIME_FILES = ["runner.spec.mjs", "playwright.config.mjs", "reporter.mjs", "devflow-test-dsl-v1.schema.json"] as const;
+const SHA256 = /^[0-9a-f]{64}$/;
+const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const PROFILE_FIELDS = new Set(["profile", "base_url", "api_base_url", "navigation_origins", "api_origins", "subresources", "secret_env", "trace", "screenshots"]);
+const RESERVED_ENV = new Set([
+  "DEVFLOW_DSL_FILE", "DEVFLOW_DSL_SHA256", "DEVFLOW_TC_ID", "DEVFLOW_TC_SHA256", "DEVFLOW_EXECUTION_ID",
+  "DEVFLOW_EXECUTION_NONCE", "DEVFLOW_RESULT_FILE", "DEVFLOW_ARTIFACT_DIR", "DEVFLOW_ENVIRONMENT_FILE",
+  "PATH", "HOME", "TMPDIR", "LANG", "PLAYWRIGHT_BROWSERS_PATH", "SHELL", "USER", "PWD",
+]);
+const RESERVED_ENV_PREFIXES = ["NODE_", "LD_", "DYLD_", "PLAYWRIGHT_", "PYTHON", "BUN_", "NPM_", "DEVFLOW_HOME", "DEVFLOW_KIT", "DEVFLOW_SOFT"];
+
 export interface DoctorCheck {
   id: string;
   ok: boolean;
@@ -30,11 +42,200 @@ function bunVersionOk(version: string): boolean {
   return major > 1 || (major === 1 && (minor > 3 || (minor === 3 && patch >= 14)));
 }
 
-export async function runHostDoctor(project: ProjectContext): Promise<HostDoctorReport> {
+function majorVersion(version: string): number {
+  return Number((version.match(/v?(\d+)/) || [])[1] || 0);
+}
+
+export interface ProbeResult {
+  ok: boolean;
+  timedOut: boolean;
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  /** Human-readable reason when ok is false. */
+  error?: string;
+}
+
+export interface ProbeOptions {
+  timeoutMs: number;
+  cwd?: string;
+}
+
+/** Runs one external command; must never throw and must always settle. */
+export type ProbeRunner = (argv: string[], options: ProbeOptions) => Promise<ProbeResult>;
+
+export interface DoctorOptions {
+  probe?: ProbeRunner;
+  /** Hard limits. A probe that exceeds them is reported as a failed check, never a pass. */
+  timeouts?: { browserLaunchMs?: number; versionMs?: number };
+}
+
+const DEFAULT_BROWSER_LAUNCH_TIMEOUT_MS = 20_000;
+const DEFAULT_VERSION_TIMEOUT_MS = 10_000;
+const PIPE_DRAIN_MS = 500;
+
+function settleWithin<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> {
+  return new Promise(resolve => {
+    const timer = setTimeout(() => resolve(fallback), ms);
+    promise.then(value => { clearTimeout(timer); resolve(value); }, () => { clearTimeout(timer); resolve(fallback); });
+  });
+}
+
+/** Async spawn with a hard timeout: the child is SIGKILLed on expiry and the result is marked failed. */
+export const spawnProbe: ProbeRunner = async (argv, options) => {
+  let child: ReturnType<typeof Bun.spawn>;
+  try {
+    child = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore", cwd: options.cwd });
+  } catch (error) {
+    return { ok: false, timedOut: false, exitCode: null, stdout: "", stderr: "", error: error instanceof Error ? error.message : String(error) };
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try { child.kill("SIGKILL"); } catch { /* already gone */ }
+  }, options.timeoutMs);
+  const stdoutText = new Response(child.stdout as ReadableStream).text();
+  const stderrText = new Response(child.stderr as ReadableStream).text();
+  try {
+    const exitCode = await child.exited;
+    // A grandchild may keep the pipes open after the kill; never wait on them indefinitely.
+    const [stdout, stderr] = await Promise.all([
+      settleWithin(stdoutText, timedOut ? PIPE_DRAIN_MS : 5_000, ""),
+      settleWithin(stderrText, timedOut ? PIPE_DRAIN_MS : 5_000, ""),
+    ]);
+    if (timedOut) {
+      return { ok: false, timedOut: true, exitCode: null, stdout: stdout.trim(), stderr: stderr.trim(), error: `timed out after ${options.timeoutMs} ms and was killed` };
+    }
+    return { ok: exitCode === 0, timedOut: false, exitCode, stdout: stdout.trim(), stderr: stderr.trim(), error: exitCode === 0 ? undefined : `exit code ${exitCode}` };
+  } catch (error) {
+    return { ok: false, timedOut, exitCode: null, stdout: "", stderr: "", error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** Wraps a probe so that even a misbehaving runner cannot block the caller past its deadline. */
+async function guardedProbe(probe: ProbeRunner, argv: string[], options: ProbeOptions): Promise<ProbeResult> {
+  const deadline = options.timeoutMs + Math.min(2_000, Math.max(50, options.timeoutMs));
+  const fallback: ProbeResult = { ok: false, timedOut: true, exitCode: null, stdout: "", stderr: "", error: `timed out after ${options.timeoutMs} ms` };
+  try {
+    const result = await settleWithin(probe(argv, options), deadline, fallback);
+    // A timed-out probe can never count as a pass, whatever the runner claims.
+    return result.timedOut ? { ...result, ok: false } : result;
+  } catch (error) {
+    return { ...fallback, timedOut: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function probeFailure(result: ProbeResult): string {
+  const detail = (result.stderr || result.stdout).split("\n")[0]?.trim();
+  return [result.error, detail].filter(Boolean).join(": ") || "probe failed";
+}
+
+export async function verifyTestRuntime(runtimeRoot: string): Promise<{ ok: boolean; message: string; playwrightVersion?: string }> {
+  const manifestPath = path.join(runtimeRoot, "runtime-manifest.json");
+  try {
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+    const files = manifest.files && typeof manifest.files === "object" ? manifest.files as Record<string, unknown> : {};
+    const errors: string[] = [];
+    if (manifest.schema_version !== 1) errors.push("schema_version must be 1");
+    if (typeof manifest.runtime_version !== "string" || !manifest.runtime_version) errors.push("runtime_version is missing");
+    if (typeof manifest.playwright_version !== "string" || !/^\d+\.\d+\.\d+$/.test(manifest.playwright_version)) errors.push("playwright_version is invalid");
+    for (const name of RUNTIME_FILES) {
+      const expected = files[name];
+      const target = path.join(runtimeRoot, name);
+      const stat = await lstat(target).catch(() => null);
+      if (typeof expected !== "string" || !SHA256.test(expected)) errors.push(`manifest does not pin ${name}`);
+      else if (!stat?.isFile() || stat.isSymbolicLink()) errors.push(`runtime file is missing or unsafe: ${name}`);
+      else if (createHash("sha256").update(await readFile(target)).digest("hex") !== expected) errors.push(`runtime file hash mismatch: ${name}`);
+    }
+    if (!errors.length) {
+      const reporter = await readFile(path.join(runtimeRoot, "reporter.mjs"), "utf8");
+      const embedded = /RUNTIME_VERSION\s*=\s*["']([^"']+)["']/.exec(reporter)?.[1];
+      if (embedded !== manifest.runtime_version) errors.push(`runtime_version ${String(manifest.runtime_version)} does not match reporter ${String(embedded)}`);
+    }
+    return { ok: !errors.length, message: errors.length ? errors.join("; ") : manifestPath, playwrightVersion: typeof manifest.playwright_version === "string" ? manifest.playwright_version : undefined };
+  } catch (error) {
+    return { ok: false, message: `invalid manifest: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+export function playwrightVersionMatches(installed: string, manifest: string | undefined): boolean {
+  return /^\d+\.\d+\.\d+$/.test(installed) && installed === manifest;
+}
+
+function exactOrigin(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return null;
+    return `${url.protocol}//${url.host}` === value ? value : null;
+  } catch { return null; }
+}
+
+export async function validateEnvironmentProfile(file: string): Promise<string[]> {
+  try {
+    const stat = await lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) return ["profile must be a regular non-symlink file"];
+    const profile = JSON.parse(await readFile(file, "utf8")) as Record<string, unknown>;
+    const name = path.basename(file, ".json");
+    const errors: string[] = [];
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) return ["profile root must be an object"];
+    if (!PROFILE_NAME.test(name)) errors.push(`invalid environment profile name: ${name}`);
+    for (const key of Object.keys(profile)) if (!PROFILE_FIELDS.has(key)) errors.push(`profile field is not allowed: ${key}`);
+    if (profile.profile !== name) errors.push("profile field must equal file name");
+    for (const key of ["navigation_origins", "api_origins"] as const) {
+      const values = key === "api_origins" && !(key in profile) ? [] : profile[key];
+      if (!Array.isArray(values) || (key === "navigation_origins" && !values.length)) errors.push(`${key} must be ${key === "navigation_origins" ? "a non-empty " : "an "}array`);
+      else {
+        if (values.some(value => !exactOrigin(value))) errors.push(`${key} contains an invalid origin`);
+        if (new Set(values).size !== values.length) errors.push(`${key} contains duplicate origins`);
+      }
+    }
+    const navigation = Array.isArray(profile.navigation_origins) ? profile.navigation_origins : [];
+    const api = Array.isArray(profile.api_origins) ? profile.api_origins : [];
+    for (const [key, allowed] of [["base_url", navigation], ["api_base_url", api]] as const) {
+      if (key === "api_base_url" && !(key in profile)) continue;
+      if (typeof profile[key] !== "string") errors.push(`${key} must be an absolute http(s) URL`);
+      else {
+        try { if (!allowed.includes(new URL(profile[key]).origin)) errors.push(`${key} origin is not declared`); }
+        catch { errors.push(`${key} must be an absolute http(s) URL`); }
+      }
+    }
+    const subresources = profile.subresources ?? { policy: "same-site-plus-declared", allowed_origins: [] };
+    if (!subresources || typeof subresources !== "object" || Array.isArray(subresources)) errors.push("subresources must be an object");
+    else {
+      const value = subresources as Record<string, unknown>;
+      if (Object.keys(value).some(key => !["policy", "allowed_origins"].includes(key))) errors.push("subresources contains an unsupported field");
+      if (!["same-site-plus-declared", "declared-only"].includes(String(value.policy))) errors.push("subresources.policy is invalid");
+      const allowed = value.allowed_origins;
+      if (!Array.isArray(allowed) || allowed.some(origin => !exactOrigin(origin))) errors.push("subresources.allowed_origins contains an invalid origin");
+    }
+    const secrets = profile.secret_env ?? {};
+    if (!secrets || typeof secrets !== "object" || Array.isArray(secrets)) errors.push("secret_env must be an object");
+    else for (const [key, value] of Object.entries(secrets)) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(key)) errors.push(`secret_env key is invalid: ${key}`);
+      if (typeof value !== "string" || !/^[A-Z_][A-Z0-9_]{0,127}$/.test(value)) errors.push(`secret_env.${key} must name an upper-case environment variable`);
+      else if (RESERVED_ENV.has(value) || RESERVED_ENV_PREFIXES.some(prefix => value.startsWith(prefix))) errors.push(`secret_env.${key} uses a reserved environment variable`);
+    }
+    for (const key of ["trace", "screenshots"] as const) if (key in profile && !["on_failure", "off"].includes(String(profile[key]))) errors.push(`${key} is invalid`);
+    return errors;
+  } catch (error) {
+    return [`invalid profile: ${error instanceof Error ? error.message : String(error)}`];
+  }
+}
+
+export async function runHostDoctor(project: ProjectContext, options: DoctorOptions = {}): Promise<HostDoctorReport> {
   const checks: DoctorCheck[] = [];
   const add = (id: string, ok: boolean, message: string) => checks.push({ id, ok, message });
+  const probe = options.probe ?? spawnProbe;
+  const versionMs = options.timeouts?.versionMs ?? DEFAULT_VERSION_TIMEOUT_MS;
+  const browserMs = options.timeouts?.browserLaunchMs ?? DEFAULT_BROWSER_LAUNCH_TIMEOUT_MS;
   add("branch-runtime", true, `devflow-pi ${PRODUCT_VERSION}; OMP SDK ${OMP_RUNTIME_VERSION}`);
   add("bun", bunVersionOk(Bun.version), bunVersionOk(Bun.version) ? Bun.version : `${Bun.version}; requires >=1.3.14`);
+  const node = await guardedProbe(probe, ["node", "--version"], { timeoutMs: versionMs });
+  const nodeOk = node.ok && majorVersion(node.stdout) >= 20;
+  add("node", nodeOk, node.ok ? `${node.stdout}; requires >=20` : `missing or unusable: ${probeFailure(node)}`);
   add("project-root", path.isAbsolute(project.root), project.root);
   add("project-id", Boolean(project.manifest.projectId), project.manifest.projectId);
   const planningStat = await lstat(project.planningRoot).catch(() => null);
@@ -45,6 +246,62 @@ export async function runHostDoctor(project: ProjectContext): Promise<HostDoctor
     const root = roots[index];
     add(`plugin:${plugin}`, await exists(path.join(root, "skills")), root);
   }
+  const qualityRoot = roots[DEVFLOW_PLUGIN_NAMES.indexOf("devflow-quality")];
+  // Never fall back to a relative path: verifyTestRuntime("") would read ./runtime-manifest.json from the cwd.
+  const runtimeRoot = qualityRoot ? path.join(qualityRoot, "runtime", "playwright") : null;
+  const runtime = runtimeRoot
+    ? await verifyTestRuntime(runtimeRoot)
+    : { ok: false, message: "devflow-quality plugin root is unknown", playwrightVersion: undefined };
+  add("test-runtime-manifest", runtime.ok, runtime.message);
+  let installedPlaywright: ProbeResult | null = null;
+  if (runtime.ok && runtimeRoot) {
+    installedPlaywright = await guardedProbe(
+      probe,
+      ["node", "-e", "process.stdout.write(require(require.resolve('@playwright/test/package.json',{paths:[process.argv[1]]})).version)", runtimeRoot],
+      { timeoutMs: versionMs },
+    );
+  }
+  const versionOk = Boolean(installedPlaywright?.ok && playwrightVersionMatches(installedPlaywright.stdout, runtime.playwrightVersion));
+  add("test-runtime-playwright-version", versionOk,
+    !installedPlaywright ? "skipped: Runtime manifest is invalid"
+      : !installedPlaywright.ok ? `Playwright version probe failed: ${probeFailure(installedPlaywright)}`
+        : `${installedPlaywright.stdout}; manifest ${runtime.playwrightVersion}${versionOk ? "" : " (mismatch)"}`);
+  let chromiumOk = false;
+  let chromiumMessage = "not checked: Node >=20 and a valid Runtime manifest are required";
+  if (nodeOk && runtime.ok && runtimeRoot) {
+    const launch = await guardedProbe(
+      probe,
+      ["node", "-e", `const {chromium}=require(require.resolve('@playwright/test',{paths:[process.argv[1]]}));chromium.launch({timeout:${Math.max(1000, browserMs - 2000)}}).then(b=>b.close()).then(()=>process.exit(0),e=>{console.error(e.message);process.exit(1)})`, runtimeRoot],
+      { timeoutMs: browserMs },
+    );
+    chromiumOk = launch.ok && !launch.timedOut;
+    chromiumMessage = chromiumOk ? "launchable"
+      : launch.timedOut ? `Chromium launch timed out after ${browserMs} ms and was killed; the browser is not launchable`
+        : `Chromium is not launchable: ${probeFailure(launch)}`;
+  }
+  add("test-runtime-chromium", chromiumOk, chromiumMessage);
+  const environmentRoot = path.join(project.planningRoot, "test-environments");
+  const environmentStat = await lstat(environmentRoot).catch(() => null);
+  let profiles: string[] = [];
+  if (environmentStat?.isDirectory() && !environmentStat.isSymbolicLink()) {
+    profiles = (await readdir(environmentRoot)).filter(name => name.endsWith(".json") && !name.endsWith(".example.json"));
+  }
+  const profileErrors: string[] = [];
+  for (const profile of profiles) for (const error of await validateEnvironmentProfile(path.join(environmentRoot, profile))) profileErrors.push(`${profile}: ${error}`);
+  add("test-environments", profiles.length > 0 && !profileErrors.length,
+    !profiles.length ? `${environmentRoot}: configure a profile from local.example.json` : profileErrors.length ? profileErrors.join("; ") : `${environmentRoot}: ${profiles.join(", ")}`);
+  const runsRoot = path.join(project.root, ".devflow", "runs");
+  const runsStat = await lstat(runsRoot).catch(() => null);
+  if (!runsStat?.isDirectory() || runsStat.isSymbolicLink()) {
+    add("test-runs-root", false, `${runsRoot}: missing, not a directory, or a symlink`);
+  } else {
+    // Run directories hold traces, screenshots and result files and must never enter source control.
+    const ignored = await guardedProbe(probe, ["git", "-C", project.root, "check-ignore", "-q", "--no-index", ".devflow/runs/doctor-probe/x"], { timeoutMs: versionMs });
+    if (ignored.ok) add("test-runs-root", true, `${runsRoot} (git-ignored)`);
+    else if (ignored.exitCode === 1) add("test-runs-root", false, `${runsRoot} is not git-ignored; add .devflow/runs/ to .gitignore (run artifacts may contain secrets)`);
+    else if (ignored.exitCode === 128 && /not a git repository/i.test(ignored.stderr)) add("test-runs-root", true, `${runsRoot} (project is not a git repository; ignore rule not applicable)`);
+    else add("test-runs-root", false, `cannot verify that ${runsRoot} is git-ignored: ${probeFailure(ignored)}`);
+  }
   const sdkManifest = ompSdkManifestPath();
   let installedVersion = "missing";
   if (await exists(sdkManifest)) {

package/src/initialization-store.ts

@@ -5,8 +5,9 @@ import path from "node:path";
 import { Database } from "bun:sqlite";
 
 import { projectControlDatabasePath, projectDataDir } from "./paths.ts";
+import { DEVFLOW_SCAN_EXCLUDES, PLANNING_DIRECTORY } from "./project-layout.ts";
 
-export const INITIALIZATION_SCHEMA_VERSION = 2;
+export const INITIALIZATION_SCHEMA_VERSION = 3;
 export const FACT_KINDS = [
   "asset", "technology", "api", "page", "data_model", "integration",
   "rule", "toolchain", "evidence", "capability",
@@ -198,6 +199,48 @@ WHEN EXISTS(SELECT 1 FROM initialization_runs r WHERE r.id=OLD.run_id AND r.stat
 BEGIN SELECT RAISE(ABORT, 'published facts are immutable'); END;
 `;
 
+// Human approval records (schema v3). The column contract is shared with the
+// Python reader side; the triggers below make the records append-only except
+// for the Core-owned proposal lifecycle and approval supersession.
+export const APPROVAL_SCHEMA = `
+CREATE TABLE IF NOT EXISTS approval_proposals(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL, feature TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('execution_plan','environment_profile','mode_override','human_result')),
+  subject_key TEXT NOT NULL, payload_json TEXT NOT NULL, pins_json TEXT NOT NULL,
+  state_revision INTEGER NOT NULL, status TEXT NOT NULL CHECK(status IN ('proposed','consumed','rejected','expired')),
+  created_at TEXT NOT NULL, resolved_at TEXT);
+CREATE TABLE IF NOT EXISTS approvals(
+  id TEXT PRIMARY KEY, proposal_id TEXT NOT NULL UNIQUE REFERENCES approval_proposals(id),
+  project_id TEXT NOT NULL, feature TEXT NOT NULL, kind TEXT NOT NULL, subject_key TEXT NOT NULL,
+  pins_json TEXT NOT NULL, decision_json TEXT NOT NULL, approved_via TEXT NOT NULL CHECK(approved_via='runtime_ui_confirm'),
+  approved_at TEXT NOT NULL, superseded_at TEXT);
+CREATE INDEX IF NOT EXISTS idx_approval_proposals_subject ON approval_proposals(project_id, feature, kind, subject_key, status);
+CREATE INDEX IF NOT EXISTS idx_approvals_subject ON approvals(project_id, feature, kind, subject_key, superseded_at);
+CREATE TRIGGER IF NOT EXISTS approval_proposal_lifecycle BEFORE UPDATE ON approval_proposals
+WHEN OLD.status!='proposed' OR NEW.status='proposed' OR NEW.resolved_at IS NULL
+ OR NEW.id!=OLD.id OR NEW.project_id!=OLD.project_id OR NEW.feature!=OLD.feature OR NEW.kind!=OLD.kind
+ OR NEW.subject_key!=OLD.subject_key OR NEW.payload_json!=OLD.payload_json OR NEW.pins_json!=OLD.pins_json
+ OR NEW.state_revision!=OLD.state_revision OR NEW.created_at!=OLD.created_at
+BEGIN SELECT RAISE(ABORT, 'approval proposals only transition once from proposed'); END;
+CREATE TRIGGER IF NOT EXISTS approval_proposal_delete BEFORE DELETE ON approval_proposals
+BEGIN SELECT RAISE(ABORT, 'approval proposals are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS approval_requires_open_proposal BEFORE INSERT ON approvals
+WHEN NOT EXISTS(
+  SELECT 1 FROM approval_proposals p
+  WHERE p.id=NEW.proposal_id AND p.status='proposed' AND p.project_id=NEW.project_id AND p.feature=NEW.feature
+    AND p.kind=NEW.kind AND p.subject_key=NEW.subject_key AND p.pins_json=NEW.pins_json
+)
+BEGIN SELECT RAISE(ABORT, 'approval does not match an open proposal'); END;
+CREATE TRIGGER IF NOT EXISTS approval_supersede_only BEFORE UPDATE ON approvals
+WHEN OLD.superseded_at IS NOT NULL OR NEW.superseded_at IS NULL
+ OR NEW.id!=OLD.id OR NEW.proposal_id!=OLD.proposal_id OR NEW.project_id!=OLD.project_id OR NEW.feature!=OLD.feature
+ OR NEW.kind!=OLD.kind OR NEW.subject_key!=OLD.subject_key OR NEW.pins_json!=OLD.pins_json
+ OR NEW.decision_json!=OLD.decision_json OR NEW.approved_via!=OLD.approved_via OR NEW.approved_at!=OLD.approved_at
+BEGIN SELECT RAISE(ABORT, 'approvals are immutable except supersession'); END;
+CREATE TRIGGER IF NOT EXISTS approval_delete BEFORE DELETE ON approvals
+BEGIN SELECT RAISE(ABORT, 'approvals are append-only'); END;
+`;
+
 function now(): string { return new Date().toISOString(); }
 function canonicalJson(value: unknown): string {
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
@@ -267,6 +310,7 @@ export class InitializationStore {
     }
     const migrate = db.transaction(() => {
       db.exec(SCHEMA);
+      db.exec(APPROVAL_SCHEMA);
       const ensureColumn = (table: string, column: string, definition: string) => {
         const columns = db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
         if (!columns.some(item => item.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
@@ -286,6 +330,10 @@ export class InitializationStore {
           db.exec("CREATE INDEX IF NOT EXISTS idx_document_jobs_status ON document_jobs(status, updated_at)");
           version = 2;
         }
+        if (version < 3) {
+          // v3 only adds the approval tables created above; existing rows are untouched.
+          version = 3;
+        }
         db.query("UPDATE schema_meta SET version=?").run(version);
       }
       const verified = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number };
@@ -323,7 +371,7 @@ export class InitializationStore {
     }));
     const requiredKinds = input.requiredKinds ?? [...FACT_KINDS];
     if (input.mode === "fast" && requiredKinds.length === FACT_KINDS.length) throw new Error("Fast mode must explicitly limit required fact kinds");
-    const config = { ...input, repositories, requiredKinds, includes: input.includes ?? ["**/*"], excludes: input.excludes ?? [".git/**", ".planning/**", ".devflow/**"], adapterVersions: input.adapterVersions ?? {} };
+    const config = { ...input, repositories, requiredKinds, includes: input.includes ?? ["**/*"], excludes: [...new Set([...DEVFLOW_SCAN_EXCLUDES, ...(input.excludes ?? [])])], adapterVersions: input.adapterVersions ?? {} };
     const configJson = canonicalJson(config);
     const contentHash = hash(configJson);
     const existing = this.db.query("SELECT id, revision FROM scan_configs WHERE project_id=? AND content_hash=?").get(this.context.manifest.projectId, contentHash) as { id: string; revision: number } | null;
@@ -510,7 +558,7 @@ export class InitializationStore {
       if (options.indexRef.status === "complete" && (typeof options.indexRef.generation !== "string" || typeof options.indexRef.snapshotHash !== "string")) throw new Error("Complete index references require generation and snapshot hash");
       if (options.indexRef.status === "complete") {
         if (typeof options.indexRef.contentManifestHash !== "string" || typeof options.indexRef.repositoryRevision !== "string") throw new Error("Complete index references require content manifest and repository revision");
-        const indexRoot = path.resolve(this.context.root, String(options.indexRef.stagingPath ?? options.indexRef.path ?? ".planning/code-index"));
+        const indexRoot = path.resolve(this.context.root, String(options.indexRef.stagingPath ?? options.indexRef.path ?? `${PLANNING_DIRECTORY}/code-index`));
         const immutable = path.resolve(indexRoot, String(options.indexRef.immutablePath ?? `snapshots/${options.indexRef.generation}`));
         const snapshotFile = path.join(immutable, "SNAPSHOT.json");
         if (!existsSync(snapshotFile)) throw new Error("Complete index reference does not point to an immutable generation");

package/src/paths.ts

@@ -8,8 +8,19 @@ export function packageRoot(): string {
   return path.resolve(import.meta.dir, "..");
 }
 
+/**
+ * DEVFLOW_HOME rule (shared with the Python readers and hooks): unset, empty or whitespace-only
+ * falls back to ~/.devflow-pi; otherwise a leading `~` is expanded and the path made absolute
+ * (path.resolve semantics, existence not required).
+ */
+export function normalizeDevflowHome(value: string | undefined): string {
+  if (value === undefined || value.trim() === "") return path.resolve(path.join(os.homedir(), ".devflow-pi"));
+  const expanded = value === "~" || value.startsWith("~/") ? os.homedir() + value.slice(1) : value;
+  return path.resolve(expanded);
+}
+
 export function devflowHome(): string {
-  return path.resolve(process.env.DEVFLOW_HOME || path.join(os.homedir(), ".devflow-pi"));
+  return normalizeDevflowHome(process.env.DEVFLOW_HOME);
 }
 
 export function devflowAgentDir(): string {

package/src/project-context.ts

@@ -5,9 +5,11 @@ import path from "node:path";
 import { PROJECT_SCHEMA_VERSION } from "./constants.ts";
 import { InitializationStore } from "./initialization-store.ts";
 import { projectControlDatabasePath } from "./paths.ts";
+import { DEVFLOW_MANIFEST, migrateLegacyProjectLayout, PLANNING_DIRECTORY, projectLayout } from "./project-layout.ts";
 
 export interface ProjectManifest {
   schemaVersion: number;
+  layoutVersion: number;
   projectId: string;
   name: string;
   createdAt: string;
@@ -23,11 +25,12 @@ export interface ProjectContext {
 }
 
 const PROJECT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PROJECT_LAYOUT_VERSION = 2;
 const CONTROL_BOUNDARY_PATHS = [
-  ".planning/STATE.md",
-  ".planning/.devflow.lock",
-  ".planning/workflows",
-  ".planning/artifacts",
+  `${PLANNING_DIRECTORY}/STATE.md`,
+  `${PLANNING_DIRECTORY}/.devflow.lock`,
+  `${PLANNING_DIRECTORY}/workflows`,
+  `${PLANNING_DIRECTORY}/artifacts`,
 ];
 
 async function assertNoSymlinkDescendants(target: string): Promise<void> {
@@ -58,7 +61,7 @@ async function canonicalDirectory(candidate: string): Promise<string> {
 async function nearestManifest(start: string): Promise<string | null> {
   let current = await canonicalDirectory(start);
   while (true) {
-    const manifest = path.join(current, ".devflow", "project.json");
+    const manifest = path.join(current, DEVFLOW_MANIFEST);
     if (await exists(manifest)) return current;
     const parent = path.dirname(current);
     if (parent === current) return null;
@@ -95,18 +98,21 @@ function validateManifest(value: unknown, manifestPath: string): ProjectManifest
   if (record.schemaVersion !== PROJECT_SCHEMA_VERSION) {
     throw new Error(`Unsupported project schema in ${manifestPath}: ${String(record.schemaVersion)}`);
   }
+  if (record.layoutVersion !== undefined && record.layoutVersion !== 1 && record.layoutVersion !== PROJECT_LAYOUT_VERSION) {
+    throw new Error(`Unsupported project layout in ${manifestPath}: ${String(record.layoutVersion)}`);
+  }
   if (typeof record.projectId !== "string" || !PROJECT_ID_PATTERN.test(record.projectId)) {
     throw new Error(`Invalid projectId in ${manifestPath}`);
   }
   if (typeof record.name !== "string" || !record.name || typeof record.createdAt !== "string") {
     throw new Error(`Incomplete project manifest: ${manifestPath}`);
   }
-  return record as unknown as ProjectManifest;
+  return { ...record, layoutVersion: Number(record.layoutVersion ?? 1) } as unknown as ProjectManifest;
 }
 
 export async function assertPlanningBoundary(root: string): Promise<string> {
   const canonicalRoot = await canonicalDirectory(root);
-  const planningRoot = path.join(canonicalRoot, ".planning");
+  const planningRoot = projectLayout(canonicalRoot).planningRoot;
   const stat = await lstat(planningRoot).catch(() => null);
   if (stat?.isSymbolicLink()) throw new Error(`Refusing symlinked planning root: ${planningRoot}`);
   if (stat && !stat.isDirectory()) throw new Error(`Planning root is not a directory: ${planningRoot}`);
@@ -133,8 +139,16 @@ export async function assertPlanningBoundary(root: string): Promise<string> {
 
 export async function loadProjectContext(root: string): Promise<ProjectContext> {
   const canonicalRoot = await canonicalDirectory(root);
-  const manifestPath = path.join(canonicalRoot, ".devflow", "project.json");
-  const manifest = validateManifest(JSON.parse(await readFile(manifestPath, "utf8")), manifestPath);
+  const manifestPath = projectLayout(canonicalRoot).manifestPath;
+  const manifestValue = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+  validateManifest(manifestValue, manifestPath);
+  await migrateLegacyProjectLayout(canonicalRoot);
+  if (manifestValue.layoutVersion !== PROJECT_LAYOUT_VERSION) {
+    manifestValue.layoutVersion = PROJECT_LAYOUT_VERSION;
+    await atomicWriteJson(manifestPath, manifestValue);
+  }
+  const manifest = validateManifest(manifestValue, manifestPath);
+  await mkdir(projectLayout(canonicalRoot).planningRoot, { recursive: true });
   const planningRoot = await assertPlanningBoundary(canonicalRoot);
   if (!(await exists(projectControlDatabasePath(manifest.projectId)))) throw new Error("Project initialization database is not registered; run explicit project initialization first");
   return attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot });
@@ -158,24 +172,55 @@ async function atomicWriteJson(target: string, value: unknown): Promise<void> {
   await rename(temporary, target);
 }
 
+async function ensureTestRuntimeLayout(root: string, planningRoot: string): Promise<void> {
+  const environments = path.join(planningRoot, "test-environments");
+  const runs = path.join(root, ".devflow", "runs");
+  await mkdir(environments, { recursive: true });
+  await mkdir(runs, { recursive: true });
+  const example = path.join(environments, "local.example.json");
+  if (!(await exists(example))) {
+    await atomicWriteJson(example, {
+      profile: "local",
+      base_url: "http://127.0.0.1:3000",
+      navigation_origins: ["http://127.0.0.1:3000"],
+      api_origins: ["http://127.0.0.1:3000"],
+      subresources: { policy: "same-site-plus-declared", allowed_origins: [] },
+      secret_env: {},
+      trace: "on_failure",
+      screenshots: "on_failure",
+    });
+  }
+}
+
 export async function initializeProject(root: string): Promise<{ context: ProjectContext; created: boolean }> {
   const canonicalRoot = await canonicalDirectory(root);
-  const devflowDir = path.join(canonicalRoot, ".devflow");
-  const planningRoot = path.join(canonicalRoot, ".planning");
-  await assertPlanningBoundary(canonicalRoot);
+  const { devflowRoot: devflowDir, manifestPath, planningRoot } = projectLayout(canonicalRoot);
   await mkdir(devflowDir, { recursive: true });
-  await mkdir(planningRoot, { recursive: true });
-  const manifestPath = path.join(devflowDir, "project.json");
+  await assertPlanningBoundary(canonicalRoot);
   if (await exists(manifestPath)) {
-    return { context: await loadProjectContext(canonicalRoot), created: false };
+    const context = await loadProjectContext(canonicalRoot);
+    await ensureTestRuntimeLayout(canonicalRoot, context.planningRoot);
+    return { context, created: false };
   }
   const manifest: ProjectManifest = {
     schemaVersion: PROJECT_SCHEMA_VERSION,
+    // Establish a v1-compatible pending identity while legacy material is
+    // assessed; only commit v2 after migration succeeds.
+    layoutVersion: 1,
     projectId: randomUUID(),
     name: path.basename(canonicalRoot),
     createdAt: new Date().toISOString(),
   };
   await atomicWriteJson(manifestPath, manifest);
+  // Explicit initialization establishes project identity before attempting a
+  // legacy-layout migration. This prevents a tracked v1 project with no local
+  // manifest from being permanently skipped, while active/conflicting legacy
+  // control state still fails closed in migrateLegacyProjectLayout.
+  await migrateLegacyProjectLayout(canonicalRoot);
+  manifest.layoutVersion = PROJECT_LAYOUT_VERSION;
+  await atomicWriteJson(manifestPath, manifest);
+  await mkdir(planningRoot, { recursive: true });
+  await ensureTestRuntimeLayout(canonicalRoot, planningRoot);
   const bootstrapStore = await InitializationStore.open({ root: canonicalRoot, manifest });
   try { await bootstrapStore.registerWorkspace(); } finally { bootstrapStore.close(); }
   return {