empirical-sdd 0.20.0

package/dist/index.js

@@ -0,0 +1,3224 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/core.ts
+import { mkdir as mkdir2, readFile as readFile5 } from "node:fs/promises";
+import { createHash as createHash3 } from "node:crypto";
+import { basename as basename2, join as join5, resolve as resolve4 } from "node:path";
+
+// src/errors.ts
+class EmpiricalError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "EmpiricalError";
+    this.code = code;
+    this.details = details;
+  }
+}
+function asErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/integrations.ts
+import { lstat as lstat2, readFile as readFile2 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
+
+// src/storage.ts
+import { chmod, lstat, open, readFile, readdir, rename, rm, rmdir, stat, writeFile, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+
+// src/types.ts
+var SCHEMA_VERSION = 4;
+var PRODUCT_VERSION = "0.20.0";
+var POLICY_SCHEMA_VERSION = 1;
+
+// src/storage.ts
+var EMPIRICAL_DIR = ".empirical";
+var LOCK_STALE_AFTER_MS = 30000;
+var LOCK_WAIT_MS = 5000;
+
+class ProjectStore {
+  root;
+  feature;
+  constructor(root, feature = null) {
+    this.root = resolve(root);
+    if (feature !== null)
+      assertFeatureId(feature);
+    this.feature = feature;
+  }
+  get directory() {
+    return join(this.root, EMPIRICAL_DIR);
+  }
+  get configPath() {
+    return join(this.directory, "config.json");
+  }
+  get policyPath() {
+    return join(this.directory, "policy.json");
+  }
+  get stateDirectory() {
+    return this.specDirectory(this.requireFeature());
+  }
+  get statePath() {
+    return join(this.stateDirectory, "state.json");
+  }
+  get eventsDirectory() {
+    return join(this.stateDirectory, "events");
+  }
+  get capabilitiesDirectory() {
+    return join(this.directory, "capabilities");
+  }
+  forFeature(feature) {
+    return new ProjectStore(this.root, feature);
+  }
+  capabilityDirectory(capability) {
+    assertCapabilityId(capability);
+    return join(this.capabilitiesDirectory, capability);
+  }
+  capabilitySpecPath(capability) {
+    return join(this.capabilityDirectory(capability), "spec.md");
+  }
+  specDirectory(feature) {
+    assertFeatureId(feature);
+    return join(this.directory, "specs", feature);
+  }
+  specPath(feature) {
+    return join(this.specDirectory(feature), "spec.md");
+  }
+  evidencePath(feature) {
+    return join(this.specDirectory(feature), "evidence.json");
+  }
+  deltaDirectory(feature) {
+    return join(this.specDirectory(feature), "deltas");
+  }
+  async exists() {
+    return isFile(this.configPath);
+  }
+  async ensureLayout() {
+    await this.assertProjectPathSafe();
+    if (this.feature) {
+      await this.assertFeaturePathSafe(this.feature, [this.statePath, this.eventsDirectory]);
+    }
+    await mkdir(join(this.directory, "specs"), { recursive: true });
+    await mkdir(this.capabilitiesDirectory, { recursive: true });
+    if (this.feature)
+      await mkdir(this.eventsDirectory, { recursive: true });
+  }
+  async loadPolicy() {
+    if (!await isFile(this.policyPath))
+      return defaultPolicy();
+    return normalizePolicy(await readJson(this.policyPath, "INVALID_POLICY"));
+  }
+  async writePolicy(policy) {
+    await this.withResourceLock("policy", async () => {
+      await writeJsonAtomic(this.policyPath, normalizePolicy(policy));
+    });
+  }
+  async loadConfig() {
+    const config = await readJson(this.configPath, "PROJECT_NOT_INITIALIZED");
+    return normalizeConfig(config);
+  }
+  async loadState(recover = true) {
+    if (!this.feature) {
+      const active = await this.activeFeature(recover);
+      if (active)
+        return this.forFeature(active).loadState(recover);
+      const config = await this.loadConfig();
+      return idleState(config.profile);
+    }
+    await this.assertFeaturePathSafe(this.feature, [this.statePath, this.eventsDirectory]);
+    const projected = normalizeState(await readJson(this.statePath, "PROJECT_NOT_INITIALIZED"));
+    const event = await this.latestEvent();
+    if (event && event.revision > projected.revision) {
+      if (recover)
+        await writeJsonAtomic(this.statePath, event.state);
+      return event.state;
+    }
+    return projected;
+  }
+  async writeConfig(config) {
+    await this.ensureLayout();
+    await writeJsonAtomic(this.configPath, normalizeConfig(config));
+    await this.ensureProjectMetadata();
+  }
+  async writeInitial(config) {
+    await this.writeConfig(config);
+  }
+  async writeInitialFeature(state, actor = "empirical-start", summary) {
+    if (!this.feature)
+      throw new EmpiricalError("FEATURE_REQUIRED", "Feature-scoped state needs a feature store");
+    if (await isFile(this.statePath)) {
+      throw new EmpiricalError("FEATURE_EXISTS", `Feature ${this.feature} already has workflow state`);
+    }
+    await this.ensureLayout();
+    await this.commitInitialState(state, actor, summary ?? `Started ${this.feature}`);
+  }
+  async configure(update) {
+    return this.withResourceLock("policy", async () => {
+      const current = await this.loadConfig();
+      const next = normalizeConfig({
+        ...current,
+        ...update,
+        isolation: { ...current.isolation, ...update.isolation },
+        decisions: { ...current.decisions, ...update.decisions }
+      });
+      await writeJsonAtomic(this.configPath, next);
+      return next;
+    });
+  }
+  async activeFeature(recover = true) {
+    const active = [];
+    for (const feature of await this.listFeatureIds()) {
+      const scoped = this.forFeature(feature);
+      if (!await isFile(scoped.statePath))
+        continue;
+      const state = await scoped.loadState(recover);
+      if (state.phase !== "done" && (state.status === "waiting" || state.status === "awaiting_human" || state.status === "blocked")) {
+        active.push(feature);
+      }
+    }
+    if (active.length > 1) {
+      throw new EmpiricalError("MULTIPLE_ACTIVE_FEATURES", `This checkout has multiple active features: ${active.join(", ")}`, { features: active });
+    }
+    return active[0] ?? null;
+  }
+  async listFeatureIds() {
+    const directory = join(this.directory, "specs");
+    if (await isSymbolicLink(directory)) {
+      throw new EmpiricalError("UNSAFE_SPEC_PATH", `Feature storage cannot use symbolic links: ${directory}`);
+    }
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return [];
+      throw error;
+    }
+    return entries.filter((entry) => entry.isDirectory() && isFeatureId(entry.name)).map((entry) => entry.name).sort();
+  }
+  async transition(expectedRevision, actor, summary, mutate) {
+    const committed = await this.transaction(async (current) => {
+      if (current.revision !== expectedRevision) {
+        throw new EmpiricalError("STALE_REVISION", `Expected revision ${expectedRevision}, but the project is at ${current.revision}`, { expectedRevision, actualRevision: current.revision });
+      }
+      return {
+        actor,
+        summary,
+        state: mutate(structuredClone(current)),
+        value: undefined
+      };
+    });
+    return committed.state;
+  }
+  async transaction(prepare) {
+    this.requireFeature();
+    await this.ensureProjectMetadata();
+    return this.withLock(async () => {
+      const current = await this.loadState();
+      const prepared = await prepare(structuredClone(current));
+      const now = new Date().toISOString();
+      const next = prepared.state;
+      next.schemaVersion = SCHEMA_VERSION;
+      next.revision = current.revision + 1;
+      next.updatedAt = now;
+      const event = {
+        schemaVersion: SCHEMA_VERSION,
+        revision: next.revision,
+        previousRevision: current.revision,
+        actor: prepared.actor,
+        summary: prepared.summary,
+        createdAt: now,
+        state: next
+      };
+      await this.ensureCurrentConfigSchema();
+      await prepared.validate?.();
+      let rollback;
+      let eventWritten = false;
+      try {
+        rollback = await prepared.effect?.();
+        await writeJsonAtomic(this.eventPath(event.revision), event);
+        eventWritten = true;
+        await writeJsonAtomic(this.statePath, next);
+        return { state: next, value: prepared.value };
+      } catch (error) {
+        if (eventWritten) {
+          try {
+            await rm(this.eventPath(event.revision), { force: true });
+          } catch (cleanupError) {
+            throw new EmpiricalError("TRANSACTION_RECOVERY_REQUIRED", "The transition event committed but its state projection failed; the next read will recover it", { error: errorMessage(error), cleanupError: errorMessage(cleanupError) });
+          }
+        }
+        if (rollback) {
+          try {
+            await rollback();
+          } catch (rollbackError) {
+            throw new EmpiricalError("TRANSACTION_ROLLBACK_FAILED", "The state transition failed and its external effect could not be fully rolled back", { error: errorMessage(error), rollbackError: errorMessage(rollbackError) });
+          }
+        }
+        throw error;
+      }
+    });
+  }
+  async migrateSchema() {
+    const project = new ProjectStore(this.root);
+    await project.ensureProjectMetadata();
+    return project.withResourceLock("specs", async () => {
+      const rawConfig = await readJson(project.configPath, "PROJECT_NOT_INITIALIZED");
+      const configVersion = schemaVersion(rawConfig);
+      const config = normalizeConfig(rawConfig);
+      let changed = JSON.stringify(rawConfig) !== JSON.stringify(config);
+      if (changed)
+        await writeJsonAtomic(project.configPath, config);
+      const legacyStatePath = join(project.directory, "state.json");
+      const legacyEvents = join(project.directory, "events");
+      let stateVersion = null;
+      let migratedFeature = null;
+      if (await isSymbolicLink(legacyStatePath) || await isSymbolicLink(legacyEvents)) {
+        throw new EmpiricalError("UNSAFE_MIGRATION_PATH", "Workflow migration cannot follow symbolic links");
+      }
+      const eventNames = await legacyEventNames(legacyEvents);
+      const hasLegacyState = await isFile(legacyStatePath);
+      if (!hasLegacyState && eventNames.length) {
+        throw new EmpiricalError("MIGRATION_CONFLICT", "Cannot migrate root transition history because its state projection is missing");
+      }
+      if (hasLegacyState) {
+        const rawState = await readJson(legacyStatePath, "PROJECT_NOT_INITIALIZED");
+        stateVersion = schemaVersion(rawState);
+        const state = normalizeState(rawState);
+        const eventsByFeature = new Map;
+        const desiredState = new Map;
+        for (const name of eventNames) {
+          const sourcePath = join(legacyEvents, name);
+          if (await isSymbolicLink(sourcePath)) {
+            throw new EmpiricalError("UNSAFE_MIGRATION_PATH", `Workflow migration cannot follow ${sourcePath}`);
+          }
+          const event = normalizeEvent(await readJson(sourcePath, "INVALID_EVENT"));
+          const feature = event.state.activeFeature;
+          if (!feature) {
+            throw new EmpiricalError("MIGRATION_CONFLICT", `Cannot assign root transition event ${name} to a feature`);
+          }
+          assertFeatureId(feature);
+          const records = eventsByFeature.get(feature) ?? [];
+          records.push({ name, event });
+          eventsByFeature.set(feature, records);
+          const current = desiredState.get(feature);
+          if (!current || event.state.revision > current.revision)
+            desiredState.set(feature, event.state);
+        }
+        if (state.activeFeature) {
+          assertFeatureId(state.activeFeature);
+          desiredState.set(state.activeFeature, state);
+          migratedFeature = state.activeFeature;
+        }
+        const features = [...new Set([...eventsByFeature.keys(), ...desiredState.keys()])].sort();
+        for (const feature of features) {
+          const scoped = project.forFeature(feature);
+          const specPath = project.specPath(feature);
+          await scoped.assertFeaturePathSafe(feature, [specPath, scoped.statePath, scoped.eventsDirectory]);
+          if (!await isFile(specPath)) {
+            throw new EmpiricalError("MIGRATION_CONFLICT", `Cannot migrate ${feature}: its specification is missing`);
+          }
+          for (const { name, event } of eventsByFeature.get(feature) ?? []) {
+            const targetPath = join(scoped.eventsDirectory, name);
+            if (await isSymbolicLink(targetPath)) {
+              throw new EmpiricalError("UNSAFE_MIGRATION_PATH", `Workflow migration cannot follow ${targetPath}`);
+            }
+            if (await isFile(targetPath)) {
+              const existing = normalizeEvent(await readJson(targetPath, "INVALID_EVENT"));
+              if (JSON.stringify(existing) !== JSON.stringify(event)) {
+                throw new EmpiricalError("MIGRATION_CONFLICT", `Transition event ${name} conflicts with ${feature} history`);
+              }
+            }
+          }
+          const projected = desiredState.get(feature);
+          if (projected && await isFile(scoped.statePath)) {
+            const existing = normalizeState(await readJson(scoped.statePath, "PROJECT_NOT_INITIALIZED"));
+            if (existing.revision === projected.revision && JSON.stringify(existing) !== JSON.stringify(projected)) {
+              throw new EmpiricalError("MIGRATION_CONFLICT", `Feature ${feature} has conflicting workflow state`);
+            }
+          }
+        }
+        for (const feature of features) {
+          const scoped = project.forFeature(feature);
+          await scoped.ensureLayout();
+          for (const { name, event } of eventsByFeature.get(feature) ?? []) {
+            const targetPath = join(scoped.eventsDirectory, name);
+            if (!await isFile(targetPath))
+              await writeJsonAtomic(targetPath, event);
+          }
+          const projected = desiredState.get(feature);
+          if (!projected)
+            continue;
+          const existing = await isFile(scoped.statePath) ? normalizeState(await readJson(scoped.statePath, "PROJECT_NOT_INITIALIZED")) : null;
+          if (!existing || existing.revision < projected.revision) {
+            await writeJsonAtomic(scoped.statePath, projected);
+          }
+        }
+        await rm(legacyStatePath, { force: true });
+        await rm(join(project.directory, "state.lock"), { force: true });
+        await rm(legacyEvents, { recursive: true, force: true });
+        changed = true;
+      }
+      for (const feature of await project.listFeatureIds()) {
+        const scoped = project.forFeature(feature);
+        await scoped.assertFeaturePathSafe(feature, [scoped.statePath, scoped.eventsDirectory]);
+        if (!await isFile(scoped.statePath))
+          continue;
+        const raw = await readJson(scoped.statePath, "PROJECT_NOT_INITIALIZED");
+        const normalized = normalizeState(raw);
+        if (JSON.stringify(raw) !== JSON.stringify(normalized)) {
+          await writeJsonAtomic(scoped.statePath, normalized);
+          changed = true;
+        }
+      }
+      return {
+        changed,
+        from: { config: configVersion, state: stateVersion },
+        to: SCHEMA_VERSION,
+        migratedFeature
+      };
+    });
+  }
+  async writeSpec(feature, contents) {
+    const path = this.specPath(feature);
+    await this.assertFeaturePathSafe(feature, [path]);
+    await mkdir(dirname(path), { recursive: true });
+    await writeTextAtomic(path, contents);
+  }
+  async readSpec(feature) {
+    await this.assertFeaturePathSafe(feature, [this.specPath(feature)]);
+    try {
+      return await readFile(this.specPath(feature), "utf8");
+    } catch (error) {
+      throw new EmpiricalError("SPEC_NOT_FOUND", `Missing specification for ${feature}`, error);
+    }
+  }
+  async writeEvidence(feature, evidence) {
+    await this.assertFeaturePathSafe(feature, [this.evidencePath(feature)]);
+    await writeJsonAtomic(this.evidencePath(feature), evidence);
+  }
+  async readEvidence(feature) {
+    await this.assertFeaturePathSafe(feature, [this.evidencePath(feature)]);
+    if (!await isFile(this.evidencePath(feature)))
+      return [];
+    return readJson(this.evidencePath(feature), "INVALID_EVIDENCE");
+  }
+  async listCapabilityNames() {
+    await this.assertCapabilityPathSafe();
+    let entries;
+    try {
+      entries = await readdir(this.capabilitiesDirectory, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return [];
+      throw error;
+    }
+    return entries.filter((entry) => entry.isDirectory() && isCapabilityId(entry.name)).map((entry) => entry.name).sort();
+  }
+  async readCapability(capability) {
+    await this.assertCapabilityPathSafe(capability);
+    const path = this.capabilitySpecPath(capability);
+    return await isFile(path) ? readFile(path, "utf8") : null;
+  }
+  async writeCapability(capability, contents) {
+    await this.assertCapabilityPathSafe(capability);
+    await writeTextAtomic(this.capabilitySpecPath(capability), contents);
+  }
+  async removeCapability(capability) {
+    await this.assertCapabilityPathSafe(capability);
+    await rm(this.capabilitySpecPath(capability), { force: true });
+    await rmdir(this.capabilityDirectory(capability)).catch((error) => {
+      if (error.code !== "ENOENT" && error.code !== "ENOTEMPTY" && error.code !== "EEXIST")
+        throw error;
+    });
+  }
+  async withResourceLock(resource, operation) {
+    return withFileLock(join(this.directory, `${resource}.lock`), operation);
+  }
+  async assertCurrentSchemaReadOnly() {
+    await this.assertProjectPathSafe();
+    const config = await readJson(this.configPath, "PROJECT_NOT_INITIALIZED");
+    if (config.schemaVersion !== SCHEMA_VERSION || await pathExists(join(this.directory, "state.json")) || await pathExists(join(this.directory, "events"))) {
+      throw new EmpiricalError("MIGRATION_REQUIRED", "This read-only operation requires schema 4; run empirical migrate first");
+    }
+  }
+  eventPath(revision) {
+    return join(this.eventsDirectory, `${String(revision).padStart(8, "0")}.json`);
+  }
+  async latestEvent() {
+    let names;
+    try {
+      names = (await readdir(this.eventsDirectory)).filter((name2) => /^[0-9]{8}\.json$/.test(name2)).sort();
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return null;
+      throw new EmpiricalError("INVALID_EVENT", `Could not inspect ${this.eventsDirectory}`, error);
+    }
+    const name = names.at(-1);
+    if (!name)
+      return null;
+    const path = join(this.eventsDirectory, name);
+    if (await isSymbolicLink(path)) {
+      throw new EmpiricalError("UNSAFE_SPEC_PATH", `Feature storage cannot use symbolic links: ${path}`);
+    }
+    return normalizeEvent(await readJson(path, "INVALID_EVENT"));
+  }
+  async commitInitialState(state, actor, summary) {
+    const event = {
+      schemaVersion: SCHEMA_VERSION,
+      revision: state.revision,
+      previousRevision: -1,
+      actor,
+      summary,
+      createdAt: state.updatedAt,
+      state
+    };
+    await writeJsonAtomic(this.eventPath(state.revision), event);
+    await writeJsonAtomic(this.statePath, state);
+  }
+  async withLock(operation) {
+    return withFileLock(join(this.stateDirectory, "state.lock"), operation);
+  }
+  requireFeature() {
+    if (!this.feature) {
+      throw new EmpiricalError("FEATURE_REQUIRED", "This operation requires a feature-scoped store");
+    }
+    return this.feature;
+  }
+  async assertCapabilityPathSafe(capability) {
+    const paths = [
+      this.capabilitiesDirectory,
+      ...capability ? [this.capabilityDirectory(capability), this.capabilitySpecPath(capability)] : []
+    ];
+    for (const path of paths) {
+      if (await isSymbolicLink(path)) {
+        throw new EmpiricalError("UNSAFE_CAPABILITY_PATH", `Capability storage cannot use symbolic links: ${path}`);
+      }
+    }
+  }
+  async assertFeaturePathSafe(feature, additional = []) {
+    assertFeatureId(feature);
+    const paths = [
+      this.directory,
+      join(this.directory, "specs"),
+      this.specDirectory(feature),
+      ...additional
+    ];
+    for (const path of paths) {
+      if (await isSymbolicLink(path)) {
+        throw new EmpiricalError("UNSAFE_SPEC_PATH", `Feature storage cannot use symbolic links: ${path}`);
+      }
+    }
+  }
+  async assertProjectPathSafe() {
+    const paths = [
+      this.directory,
+      join(this.directory, "specs"),
+      this.capabilitiesDirectory,
+      this.configPath,
+      this.policyPath
+    ];
+    for (const path of paths) {
+      if (await isSymbolicLink(path)) {
+        throw new EmpiricalError("UNSAFE_PROJECT_PATH", `Empirical storage cannot use symbolic links: ${path}`);
+      }
+    }
+  }
+  async ensureProjectMetadata() {
+    await this.assertProjectPathSafe();
+    await mkdir(this.directory, { recursive: true });
+    if (!await isFile(this.policyPath)) {
+      await this.withResourceLock("policy", async () => {
+        if (!await isFile(this.policyPath))
+          await writeJsonAtomic(this.policyPath, defaultPolicy());
+      });
+    }
+  }
+  async ensureCurrentConfigSchema() {
+    const raw = await readJson(this.configPath, "PROJECT_NOT_INITIALIZED");
+    schemaVersion(raw);
+    const normalized = normalizeConfig(raw);
+    if (JSON.stringify(raw) !== JSON.stringify(normalized)) {
+      await writeJsonAtomic(this.configPath, normalized);
+    }
+  }
+}
+async function withFileLock(lockPath, operation) {
+  await mkdir(dirname(lockPath), { recursive: true });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  const token = randomUUID();
+  let handle;
+  let lastError;
+  while (!handle) {
+    try {
+      handle = await open(lockPath, "wx");
+      await handle.writeFile(`${JSON.stringify({ pid: process.pid, token })}
+`, "utf8");
+      await handle.sync();
+      break;
+    } catch (error) {
+      lastError = error;
+      if (handle) {
+        const incomplete = handle;
+        handle = undefined;
+        const details = await incomplete.stat().catch(() => null);
+        const observed = details ? await inspectLock(lockPath).catch(() => null) : null;
+        await incomplete.close().catch(() => {
+          return;
+        });
+        if (details && observed && details.dev === observed.dev && details.ino === observed.ino) {
+          await removeLockIfUnchanged(lockPath, observed);
+        }
+        throw error;
+      }
+      const code = error.code;
+      if (!isRetryableLockOpenError(error))
+        throw error;
+      if (code === "EEXIST") {
+        try {
+          const observed = await inspectLock(lockPath);
+          if (observed && Date.now() - observed.mtimeMs > LOCK_STALE_AFTER_MS && (observed.pid === null || !processIsAlive(observed.pid)) && await recoverStaleLock(lockPath, observed)) {
+            continue;
+          }
+        } catch {}
+      }
+      if (Date.now() >= deadline) {
+        throw new EmpiricalError("PROJECT_BUSY", "Another Empirical client is updating this repository; retry shortly", lastError);
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, 10));
+    }
+  }
+  const heartbeat = setInterval(() => {
+    const now = new Date;
+    handle?.utimes(now, now).catch(() => {
+      return;
+    });
+  }, LOCK_STALE_AFTER_MS / 3);
+  heartbeat.unref();
+  try {
+    return await operation();
+  } finally {
+    clearInterval(heartbeat);
+    const owned = await handle.stat().catch(() => null);
+    await handle.close();
+    if (owned) {
+      await removeLockIfUnchanged(lockPath, {
+        dev: owned.dev,
+        ino: owned.ino,
+        mtimeMs: owned.mtimeMs,
+        token,
+        pid: process.pid
+      });
+    }
+  }
+}
+function isRetryableLockOpenError(error, platform = process.platform) {
+  const code = error.code;
+  return code === "EEXIST" || platform === "win32" && (code === "EPERM" || code === "EACCES");
+}
+async function inspectLock(path) {
+  let handle;
+  try {
+    handle = await open(path, "r");
+    const details = await handle.stat();
+    const raw = await handle.readFile("utf8");
+    let token = null;
+    let pid = null;
+    try {
+      const owner = JSON.parse(raw);
+      if (typeof owner.token === "string")
+        token = owner.token;
+      if (typeof owner.pid === "number" && Number.isSafeInteger(owner.pid) && owner.pid > 0) {
+        pid = owner.pid;
+      }
+    } catch {}
+    return { dev: details.dev, ino: details.ino, mtimeMs: details.mtimeMs, token, pid };
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+async function removeLockIfUnchanged(path, expected) {
+  const current = await inspectLock(path);
+  if (!current || !sameLock(current, expected))
+    return false;
+  await rm(path, { force: true });
+  return true;
+}
+async function recoverStaleLock(path, expected) {
+  const recoveryPath = `${path}.recovery`;
+  const recoveryToken = randomUUID();
+  let recoveryHandle;
+  try {
+    recoveryHandle = await open(recoveryPath, "wx");
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      const abandoned = await inspectLock(recoveryPath);
+      if (abandoned && Date.now() - abandoned.mtimeMs > LOCK_STALE_AFTER_MS && (abandoned.pid === null || !processIsAlive(abandoned.pid))) {
+        await removeLockIfUnchanged(recoveryPath, abandoned);
+      }
+      return false;
+    }
+    throw error;
+  }
+  let recoveryOwner = null;
+  try {
+    await recoveryHandle.writeFile(`${JSON.stringify({ pid: process.pid, token: recoveryToken })}
+`, "utf8");
+    await recoveryHandle.sync();
+    const details = await recoveryHandle.stat();
+    recoveryOwner = {
+      dev: details.dev,
+      ino: details.ino,
+      mtimeMs: details.mtimeMs,
+      token: recoveryToken,
+      pid: process.pid
+    };
+    const current = await inspectLock(path);
+    if (!current || !sameLock(current, expected) || Date.now() - current.mtimeMs <= LOCK_STALE_AFTER_MS || current.pid !== null && processIsAlive(current.pid)) {
+      return false;
+    }
+    await rm(path, { force: true });
+    return true;
+  } finally {
+    await recoveryHandle.close().catch(() => {
+      return;
+    });
+    if (recoveryOwner)
+      await removeLockIfUnchanged(recoveryPath, recoveryOwner);
+    else
+      await rm(recoveryPath, { force: true });
+  }
+}
+function sameLock(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.token === right.token && left.pid === right.pid;
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function discoverProject(start) {
+  let current = resolve(start);
+  while (true) {
+    const store = new ProjectStore(current);
+    if (await store.exists())
+      return store;
+    const parent = dirname(current);
+    if (parent === current)
+      break;
+    current = parent;
+  }
+  throw new EmpiricalError("PROJECT_NOT_INITIALIZED", "No .empirical project found; run empirical init or empirical adopt");
+}
+async function writeJsonAtomic(path, value) {
+  await writeTextAtomic(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+async function writeTextAtomic(path, contents) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const existingMode = await stat(path).then((details) => details.mode & 4095, () => null);
+  try {
+    await writeFile(temporary, contents, "utf8");
+    if (existingMode !== null)
+      await chmod(temporary, existingMode);
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+async function isSymbolicLink(path) {
+  try {
+    return (await lstat(path)).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+async function legacyEventNames(directory) {
+  try {
+    return (await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isFile() || entry.isSymbolicLink()).map((entry) => entry.name).filter((name) => /^[0-9]{8}\.json$/.test(name)).sort();
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return [];
+    throw error;
+  }
+}
+async function readJson(path, code = "INVALID_JSON") {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    throw new EmpiricalError(code, `Could not read ${path}`, error);
+  }
+}
+function assertFeatureId(feature) {
+  if (!isFeatureId(feature)) {
+    throw new EmpiricalError("INVALID_FEATURE", `Invalid feature id: ${feature}`);
+  }
+}
+function isFeatureId(value) {
+  return /^[a-z0-9][a-z0-9-]*$/.test(value) && value.length <= 80;
+}
+function assertCapabilityId(capability) {
+  if (!isCapabilityId(capability)) {
+    throw new EmpiricalError("INVALID_CAPABILITY", `Invalid capability '${capability}'; use lowercase kebab-case`);
+  }
+}
+function isCapabilityId(value) {
+  return /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
+function defaultPolicy() {
+  return { schemaVersion: POLICY_SCHEMA_VERSION, context: [], phases: {} };
+}
+function normalizePolicy(policy) {
+  if (policy.schemaVersion !== POLICY_SCHEMA_VERSION || !Array.isArray(policy.context) || !isRecord(policy.phases)) {
+    throw new EmpiricalError("INVALID_POLICY", "Unsupported or malformed project policy");
+  }
+  const context = policy.context.map((item) => requiredPolicyText(item, "context"));
+  const phases = {};
+  const validPhases = new Set([
+    "idle",
+    "shape",
+    "specify",
+    "design",
+    "plan",
+    "implement",
+    "verify",
+    "review",
+    "archive",
+    "done"
+  ]);
+  for (const [phase, guidance] of Object.entries(policy.phases)) {
+    if (!validPhases.has(phase) || !Array.isArray(guidance)) {
+      throw new EmpiricalError("INVALID_POLICY", `Invalid policy phase '${phase}'`);
+    }
+    phases[phase] = guidance.map((item) => requiredPolicyText(item, phase));
+  }
+  return { schemaVersion: POLICY_SCHEMA_VERSION, context, phases };
+}
+function requiredPolicyText(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new EmpiricalError("INVALID_POLICY", `Policy ${field} entries must be non-empty strings`);
+  }
+  return value.trim();
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeConfig(config) {
+  assertSupportedSchema(config);
+  const value = config;
+  const isolation = isRecord(value.isolation) ? value.isolation : {};
+  const decisions = isRecord(value.decisions) ? value.decisions : {};
+  const mode = isolation.mode === "off" ? "off" : "ask";
+  const baseBranch = typeof isolation.baseBranch === "string" && isolation.baseBranch.trim() ? isolation.baseBranch.trim() : "auto";
+  const worktreePath = typeof isolation.worktreePath === "string" && isolation.worktreePath.trim() ? isolation.worktreePath.trim() : "../{repo}-{feature}";
+  const branchPattern = typeof isolation.branchPattern === "string" && isolation.branchPattern.trim() ? isolation.branchPattern.trim() : "{type}/{feature}";
+  validateWorktreeTemplates(worktreePath, branchPattern);
+  return {
+    ...config,
+    schemaVersion: SCHEMA_VERSION,
+    profile: normalizeProfile(config.profile),
+    isolation: { mode, baseBranch, worktreePath, branchPattern },
+    decisions: { complexRecords: decisions.complexRecords === "off" ? "off" : "required" },
+    setupComplete: typeof value.setupComplete === "boolean" ? value.setupComplete : false
+  };
+}
+function normalizeState(state) {
+  assertSupportedSchema(state);
+  return {
+    ...state,
+    schemaVersion: SCHEMA_VERSION,
+    profile: normalizeProfile(state.profile),
+    specDigest: typeof state.specDigest === "string" ? state.specDigest : null,
+    capabilityArchiveRequired: typeof state.capabilityArchiveRequired === "boolean" ? state.capabilityArchiveRequired : false,
+    capabilityDeltaDigest: typeof state.capabilityDeltaDigest === "string" ? state.capabilityDeltaDigest : null,
+    evidence: Array.isArray(state.evidence) ? state.evidence : []
+  };
+}
+function validateWorktreeTemplates(worktreePath, branchPattern) {
+  if (!worktreePath.includes("{feature}")) {
+    throw new EmpiricalError("INVALID_CONFIG", "Worktree path template must contain {feature}");
+  }
+  if (!branchPattern.includes("{feature}") || !branchPattern.includes("{type}")) {
+    throw new EmpiricalError("INVALID_CONFIG", "Branch pattern must contain {type} and {feature}");
+  }
+  const allowed = (value) => value.replaceAll("{repo}", "").replaceAll("{feature}", "").replaceAll("{type}", "");
+  if (/[\0\r\n]/.test(worktreePath) || /[\0\r\n]/.test(branchPattern) || /[{}]/.test(allowed(worktreePath)) || /[{}]/.test(allowed(branchPattern))) {
+    throw new EmpiricalError("INVALID_CONFIG", "Worktree templates contain unsupported placeholders or control characters");
+  }
+}
+function idleState(profile) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    revision: 0,
+    activeFeature: null,
+    request: null,
+    profile,
+    phase: "idle",
+    status: "idle",
+    repairAttempts: 0,
+    message: null,
+    implementationActor: null,
+    specDigest: null,
+    capabilityArchiveRequired: false,
+    capabilityDeltaDigest: null,
+    evidence: [],
+    updatedAt: new Date(0).toISOString()
+  };
+}
+function normalizeProfile(profile) {
+  if (profile === "strong")
+    return "complex";
+  if (profile === "fast" || profile === "complex" || profile === "quick")
+    return profile;
+  throw new EmpiricalError("INVALID_PROFILE", `Unknown persisted workflow '${String(profile)}'`);
+}
+function normalizeEvent(event) {
+  assertSupportedSchema(event);
+  return {
+    ...event,
+    schemaVersion: SCHEMA_VERSION,
+    state: normalizeState(event.state)
+  };
+}
+function assertSupportedSchema(value) {
+  if (value.schemaVersion !== 1 && value.schemaVersion !== 2 && value.schemaVersion !== 3 && value.schemaVersion !== SCHEMA_VERSION) {
+    throw new EmpiricalError("MIGRATION_REQUIRED", `Project schema ${String(value.schemaVersion)} is not supported; run empirical migrate`);
+  }
+}
+function schemaVersion(value) {
+  assertSupportedSchema(value);
+  return value.schemaVersion;
+}
+
+// src/integrations.ts
+var START = "<!-- empirical-sdd:start -->";
+var END = "<!-- empirical-sdd:end -->";
+var MANAGED_FILE_MARKER = "empirical-sdd:managed-file";
+var SOCRATIC_AGENT_GUIDANCE = `For genuinely vague work, retrieve repository and living-spec context with empirical_explore or empirical explore "<problem>", then conduct the original five Socratic passes in the current conversation: problem/user, observable outcome, boundaries/non-goals, failure/risk, and verification. Ask one question at a time, add only a material follow-up, show the complete refined contract, and wait for explicit human approval before starting Fast or Complex. Do not merely repeat the packet's generic questions.`;
+var COMMAND_REFERENCE = `Command reference:
+- Socratic discovery: \`empirical explore "<idea>"\`
+- Socratic discovery, then launch Codex: \`empirical explore "<idea>" --agent codex\`
+- Direct tiny change: \`empirical fast "<request>"\`
+- Direct substantial or UI change: \`empirical complex "<request>"\`
+- Approved unrelated work: \`empirical worktree create "<request>" --workflow fast|complex\`
+- Resume active work: \`empirical loop\`
+- Explain state and accepted decisions: \`empirical explain\`
+
+The \`--agent codex\` form is a human terminal entrypoint. Agents must continue in
+their current runtime and use the MCP equivalents when available.`;
+var ENTRYPOINT_NAMES = [
+  "empirical",
+  "empirical-explore",
+  "empirical-fast",
+  "empirical-complex",
+  "empirical-loop"
+];
+var DEDICATED_ENTRYPOINTS = [
+  {
+    name: "empirical-explore",
+    description: "Conduct Empirical's five-pass Socratic discovery before starting work.",
+    instructions: `Treat the text attached to this invocation as the initial idea. If it is empty,
+ask for the idea first. Retrieve repository and living-spec context with
+empirical_explore or \`empirical explore "<idea>" --no-interview\`, then conduct
+the original five Socratic passes in this conversation: problem/user,
+observable outcome, boundaries/non-goals, failure/risk, and verification. Ask
+one question at a time and add only a material follow-up. Save or preserve the
+answers when the host supports it, show the complete refined request, and wait
+for explicit human approval. After approval, choose Fast only for explicit,
+tiny, localized, reversible, low-risk non-UI work; choose Complex otherwise.
+Start through empirical_fast or empirical_complex (CLI fallback: \`empirical
+fast "<request>"\` or \`empirical complex "<request>"\`) and consume every
+returned action until Done, Blocked, or awaiting human input.`
+  },
+  {
+    name: "empirical-fast",
+    description: "Run an eligible tiny change through Empirical Fast.",
+    instructions: `Treat the text attached to this invocation as the requested change. Fast is
+allowed only when the behavior is explicit and the change is tiny, localized,
+reversible, low-risk, and non-UI. If any condition is false or unclear, use
+Empirical Complex instead and explain the routing. Otherwise start with
+empirical_fast or \`empirical fast "<request>"\`. Execute the returned action,
+provide its focused test and diff-review evidence, complete the exact revision,
+and consume the response until Done, Blocked, or awaiting human input.`
+  },
+  {
+    name: "empirical-complex",
+    description: "Run a substantial or UI change through Empirical Complex.",
+    instructions: `Treat the text attached to this invocation as the requested change. Start with
+empirical_complex or \`empirical complex "<request>"\`. Execute the returned
+Specify, Design, Plan, Implement, Verify, Review, and Archive actions in order,
+complete each exact revision with all required evidence, and consume every
+response directly until Done, Blocked, or awaiting human input. Maintain the
+feature decision record and never weaken acceptance criteria or verification gates.`
+  },
+  {
+    name: "empirical-loop",
+    description: "Resume the active Empirical workflow without starting new work.",
+    instructions: `Resume the active workflow with empirical_loop or \`empirical loop\`. Loop takes
+no new request or profile. Execute the exact current action, complete its
+revision with every required artifact and evidence
+item, and consume each response directly until Done, Blocked, or awaiting human
+input. Never replace the active feature with text attached to this invocation.`
+  }
+];
+var PROJECT_ENTRYPOINT_REPORTS = [
+  {
+    id: "codex",
+    agent: "Codex",
+    kind: "skill",
+    artifactRoot: ".agents/skills",
+    invocations: ENTRYPOINT_NAMES.map((name) => `$${name}`),
+    reload: "Restart or reopen Codex so it rescans project skills; invoke them with $."
+  },
+  {
+    id: "claude",
+    agent: "Claude Code",
+    kind: "slash-command",
+    artifactRoot: ".claude/skills",
+    invocations: ENTRYPOINT_NAMES.map((name) => `/${name}`),
+    reload: "Restart Claude Code if .claude/skills was created after the session started."
+  },
+  {
+    id: "cursor",
+    agent: "Cursor",
+    kind: "slash-command",
+    artifactRoot: ".cursor/commands",
+    invocations: ENTRYPOINT_NAMES.map((name) => `/${name}`),
+    reload: "Open a new chat or reload the workspace, then type / to discover commands."
+  },
+  {
+    id: "gemini",
+    agent: "Gemini CLI",
+    kind: "slash-command",
+    artifactRoot: ".gemini/commands",
+    invocations: ENTRYPOINT_NAMES.map((name) => `/${name}`),
+    reload: "Run /commands reload, then /commands list."
+  },
+  {
+    id: "windsurf",
+    agent: "Windsurf",
+    kind: "slash-command",
+    artifactRoot: ".windsurf/workflows",
+    invocations: ENTRYPOINT_NAMES.map((name) => `/${name}`),
+    reload: "Start a new Cascade session or reload the workspace, then type /."
+  }
+];
+var GUIDANCE = `${START}
+## Empirical SDD
+
+Automatically use Empirical when the user asks to build, add, implement, change,
+fix, refactor, remove, migrate, upgrade, update tests, or continue repository
+work. The user does not need to mention Empirical.
+
+1. Use the current agent; never launch another AI runtime.
+2. ${SOCRATIC_AGENT_GUIDANCE}
+3. For concrete new work, choose Fast only when it is explicit, tiny, localized,
+   reversible, low-risk, and non-UI. Choose Complex for everything else.
+4. Start through \`empirical_fast\` or \`empirical_complex\`. Without MCP, run
+   \`empirical fast "<the user's request>"\` or
+   \`empirical complex "<the user's request>"\`.
+5. Resume active work through \`empirical_loop\` or \`empirical loop\`; loop
+   takes no request or profile.
+6. If unrelated work returns a worktree proposal, show its base, branch, path,
+   and command; wait for explicit human approval, then execute the returned
+   worktree creation operation. Execute each action and complete its exact revision
+   with all required evidence. Each completion response is already the next action; do not call
+   status, next, or loop redundantly.
+7. When Review returns Archive, apply its validated capability deltas with the
+   returned archive operation. Continue until Done, Blocked, or genuinely awaiting
+   human input. For Fast, trust the criterion in the returned packet, inspect only relevant project
+   files, combine the focused test and diff review, and use the returned
+   completion command. Do not reread Empirical internals or add redundant checks.
+
+${COMMAND_REFERENCE}
+
+Quick exists only for legacy compatibility. Do not select it for new work or
+add profile/JSON controls to the normal workflow.
+
+Do not invent workflow state or weaken verification evidence. The committed
+\`.empirical/\` directory is the source of truth.
+${END}`;
+var SKILL = `---
+name: empirical
+description: Automatically run this repository's Empirical workflow for requests to build, add, implement, change, fix, refactor, remove, migrate, upgrade, test, or continue code. Resume unfinished work; skip read-only explanation or inspection.
+---
+
+<!-- ${MANAGED_FILE_MARKER} -->
+# Empirical workflow
+
+Use the current host agent to execute the work. Never launch another AI agent,
+daemon, or runtime.
+
+1. Treat the user's ordinary coding request as the workflow request. The user
+   does not choose a command or profile.
+2. ${SOCRATIC_AGENT_GUIDANCE}
+3. For concrete work, choose Fast only when the behavior is explicit and the change
+   is tiny, localized, reversible, low-risk, and non-UI. Choose Complex otherwise,
+   including UI, security, authentication, permissions, payments, destructive
+   operations, migrations, dependencies, public APIs, infrastructure,
+   architecture, or cross-cutting work.
+4. Start new work with \`empirical_fast\` or \`empirical_complex\`. If MCP is
+   unavailable, run \`empirical fast "<request>"\` or
+   \`empirical complex "<request>"\`.
+5. If work is already active, resume it with \`empirical_loop\` or
+   \`empirical loop\`. Loop takes no request or profile.
+6. If unrelated work returns a worktree proposal, show its base, branch, path,
+   and command, wait for explicit human approval, then call the returned creation
+   operation. Execute the action and complete the exact revision with every
+   required evidence item. For Fast, trust the generated criterion in the
+   packet, inspect only relevant project files, implement directly, combine the
+   focused test and diff review when practical, and use the returned completion
+   command. Do not reread Empirical state/spec files or add redundant checks.
+7. Treat each Fast, Complex, Complete, or Archive response as the next action.
+   After Review, archive validated deltas into living capability specifications.
+8. Stop only at \`done\`, \`blocked\`, or \`awaiting_human\`. Explain a blocker or
+   required decision clearly. Keep Fast updates and checks proportional.
+
+${COMMAND_REFERENCE}
+
+Quick exists only to resume legacy workflow state. Do not choose it for new
+work or add profile/JSON controls to the normal path.
+
+Never replace unrelated active work, invent state, or weaken acceptance criteria
+or evidence. The committed \`.empirical/\` directory is the source of truth.
+`;
+var CURSOR_COMMAND = `<!-- ${MANAGED_FILE_MARKER} -->
+# Empirical
+
+Run the request attached to this command through the repository's Empirical
+workflow. If there is no new request, resume the active feature.
+
+Use the current Cursor agent. ${SOCRATIC_AGENT_GUIDANCE} For concrete work,
+choose Fast only for explicit, tiny,
+localized, reversible, low-risk non-UI changes and Complex otherwise. Start with
+\`empirical_fast\` or \`empirical_complex\`; fall back to
+\`empirical fast "<request>"\` or \`empirical complex "<request>"\`. Resume active
+work with \`empirical_loop\` or \`empirical loop\`. Execute
+each returned action, complete exact revisions with evidence, archive after Review, and consume the
+response directly as the next action. Never select legacy Quick for new work,
+add profile/JSON controls, or launch another AI runtime.
+
+${COMMAND_REFERENCE}
+`;
+var GEMINI_COMMAND = `# ${MANAGED_FILE_MARKER}
+description = "Start or resume Empirical and continue in the current agent until a terminal state."
+prompt = """
+Run the request attached to this command through the repository's Empirical workflow. If there is no new request, resume the active feature.
+
+Use the current Gemini agent. ${SOCRATIC_AGENT_GUIDANCE} For concrete work, choose Fast only for explicit, tiny, localized, reversible, low-risk non-UI changes and Complex otherwise. Start with empirical_fast or empirical_complex; fall back to empirical fast "<request>" or empirical complex "<request>". If unrelated work returns a worktree proposal, show it and wait for explicit approval before creation. Resume active work with empirical_loop or empirical loop. Complete exact revisions with evidence, archive after Review, and consume every response directly. Never select legacy Quick for new work, add profile/JSON controls, or launch another AI runtime.
+
+${COMMAND_REFERENCE}
+"""
+`;
+var WINDSURF_WORKFLOW = `<!-- ${MANAGED_FILE_MARKER} -->
+# Empirical
+
+Start or resume the repository's Empirical workflow for the current request.
+
+1. Use the current Cascade agent; never launch another AI runtime.
+2. ${SOCRATIC_AGENT_GUIDANCE}
+3. For concrete work, choose Fast only for explicit, tiny, localized, reversible,
+   low-risk non-UI changes and Complex otherwise.
+4. Start with \`empirical_fast\` or \`empirical_complex\`; fall back to
+   \`empirical fast "<request>"\` or \`empirical complex "<request>"\`.
+5. Resume active work with \`empirical_loop\` or \`empirical loop\`.
+6. If unrelated work returns a worktree proposal, show it and wait for explicit
+   approval before creation. Execute the action and complete its exact revision
+   with all required evidence.
+7. Archive validated capability deltas after Review and consume every response.
+8. Stop only at Done, Blocked, or awaiting human input.
+
+${COMMAND_REFERENCE}
+
+Never select legacy Quick for new work or add profile/JSON controls to the
+normal workflow.
+`;
+function renderAgentSkill(entrypoint) {
+  return `---
+name: ${entrypoint.name}
+description: ${entrypoint.description}
+---
+
+<!-- ${MANAGED_FILE_MARKER} -->
+# ${entrypoint.name}
+
+Use the current host agent; never launch another AI runtime.
+
+${entrypoint.instructions}
+`;
+}
+function renderCursorCommand(entrypoint) {
+  return `<!-- ${MANAGED_FILE_MARKER} -->
+# ${entrypoint.name}
+
+Use the current Cursor agent; never launch another AI runtime.
+
+${entrypoint.instructions}
+`;
+}
+function renderGeminiCommand(entrypoint) {
+  return `# ${MANAGED_FILE_MARKER}
+description = "${entrypoint.description}"
+prompt = """
+Use the current Gemini agent; never launch another AI runtime.
+
+${entrypoint.instructions}
+
+Invocation arguments:
+{{args}}
+"""
+`;
+}
+function renderWindsurfWorkflow(entrypoint) {
+  return `<!-- ${MANAGED_FILE_MARKER} -->
+# ${entrypoint.name}
+
+Use the current Cascade agent; never launch another AI runtime.
+
+${entrypoint.instructions}
+`;
+}
+function projectEntrypointReports() {
+  return PROJECT_ENTRYPOINT_REPORTS.map((entrypoint) => ({
+    ...entrypoint,
+    invocations: [...entrypoint.invocations]
+  }));
+}
+var MCP_SERVER = {
+  command: "empirical",
+  args: ["mcp"]
+};
+async function installProjectIntegrations(root) {
+  const report = {
+    scope: "project",
+    created: [],
+    updated: [],
+    preserved: [],
+    entrypoints: projectEntrypointReports()
+  };
+  await mergeMarkdown(root, join2(root, "AGENTS.md"), GUIDANCE, report);
+  await mergeMarkdown(root, join2(root, "CLAUDE.md"), GUIDANCE, report);
+  await mergeMarkdown(root, join2(root, "GEMINI.md"), GUIDANCE, report);
+  await writeManagedFile(root, join2(root, ".agents", "skills", "empirical", "SKILL.md"), SKILL, report);
+  await writeManagedFile(root, join2(root, ".claude", "skills", "empirical", "SKILL.md"), SKILL, report);
+  await writeManagedFile(root, join2(root, ".cursor", "commands", "empirical.md"), CURSOR_COMMAND, report);
+  await writeManagedFile(root, join2(root, ".gemini", "commands", "empirical.toml"), GEMINI_COMMAND, report);
+  await writeManagedFile(root, join2(root, ".windsurf", "workflows", "empirical.md"), WINDSURF_WORKFLOW, report);
+  for (const entrypoint of DEDICATED_ENTRYPOINTS) {
+    await writeManagedFile(root, join2(root, ".agents", "skills", entrypoint.name, "SKILL.md"), renderAgentSkill(entrypoint), report);
+    await writeManagedFile(root, join2(root, ".claude", "skills", entrypoint.name, "SKILL.md"), renderAgentSkill(entrypoint), report);
+    await writeManagedFile(root, join2(root, ".cursor", "commands", `${entrypoint.name}.md`), renderCursorCommand(entrypoint), report);
+    await writeManagedFile(root, join2(root, ".gemini", "commands", `${entrypoint.name}.toml`), renderGeminiCommand(entrypoint), report);
+    await writeManagedFile(root, join2(root, ".windsurf", "workflows", `${entrypoint.name}.md`), renderWindsurfWorkflow(entrypoint), report);
+  }
+  await mergeMcpJson(root, join2(root, ".mcp.json"), report);
+  await mergeMcpJson(root, join2(root, ".cursor", "mcp.json"), report);
+  await mergeMcpJson(root, join2(root, ".gemini", "settings.json"), report, { cwd: "." });
+  await mergeCodexToml(root, join2(root, ".codex", "config.toml"), report);
+  return report;
+}
+var GLOBAL_AGENT_SKILL_ROOTS = [
+  {
+    id: "codex",
+    agent: "Codex",
+    segments: [".codex", "skills"],
+    invocations: ENTRYPOINT_NAMES.map((name) => `$${name}`),
+    reload: "Restart or reopen Codex so it rescans user skills; invoke them with $."
+  },
+  {
+    id: "claude",
+    agent: "Claude Code",
+    segments: [".claude", "skills"],
+    invocations: ENTRYPOINT_NAMES.map((name) => `/${name}`),
+    reload: "Restart Claude Code if the skills were installed during the current session."
+  },
+  {
+    id: "cursor",
+    agent: "Cursor",
+    segments: [".cursor", "skills"],
+    invocations: [...ENTRYPOINT_NAMES],
+    reload: "Reload Cursor, open Agent chat, and ask normally; Cursor discovers the installed Agent Skills."
+  },
+  {
+    id: "gemini",
+    agent: "Gemini CLI",
+    segments: [".gemini", "skills"],
+    invocations: [...ENTRYPOINT_NAMES],
+    reload: "Run /skills reload and /skills list; Gemini activates matching skills from your request."
+  },
+  {
+    id: "windsurf",
+    agent: "Windsurf",
+    segments: [".codeium", "windsurf", "skills"],
+    invocations: ENTRYPOINT_NAMES.map((name) => `@${name}`),
+    reload: "Start a new Cascade session or reload Windsurf; invoke a skill with @."
+  }
+];
+async function installGlobalAgentSkills(homeRoot = homedir()) {
+  const home = validateHomeRoot(homeRoot);
+  const report = {
+    scope: "global",
+    created: [],
+    updated: [],
+    preserved: [],
+    entrypoints: GLOBAL_AGENT_SKILL_ROOTS.map((agent) => ({
+      id: agent.id,
+      agent: agent.agent,
+      kind: "skill",
+      artifactRoot: join2(home, ...agent.segments),
+      invocations: [...agent.invocations],
+      reload: agent.reload
+    }))
+  };
+  for (const agent of GLOBAL_AGENT_SKILL_ROOTS) {
+    const skillRoot = join2(home, ...agent.segments);
+    await writeManagedFile(home, join2(skillRoot, "empirical", "SKILL.md"), SKILL, report);
+    for (const entrypoint of DEDICATED_ENTRYPOINTS) {
+      await writeManagedFile(home, join2(skillRoot, entrypoint.name, "SKILL.md"), renderAgentSkill(entrypoint), report);
+    }
+  }
+  return report;
+}
+function validateHomeRoot(homeRoot) {
+  if (!homeRoot.trim()) {
+    throw new EmpiricalError("INVALID_ARGUMENT", "Global integration requires a user home directory");
+  }
+  const home = resolve2(homeRoot);
+  if (dirname2(home) === home) {
+    throw new EmpiricalError("INVALID_ARGUMENT", "Global integration refuses a filesystem root as the user home");
+  }
+  return home;
+}
+async function writeManagedFile(root, path, managed, report) {
+  if (await preserveUnsafeTarget(root, path, report))
+    return;
+  const desired = managed.endsWith(`
+`) ? managed : `${managed}
+`;
+  if (!await isFile(path)) {
+    await writeTextAtomic(path, desired);
+    report.created.push(relativeLabel(root, path));
+    return;
+  }
+  const current = await readFile2(path, "utf8");
+  if (!current.includes(MANAGED_FILE_MARKER)) {
+    report.preserved.push(`${relativeLabel(root, path)} (existing unmanaged file)`);
+    return;
+  }
+  if (current !== desired) {
+    await writeTextAtomic(path, desired);
+    report.updated.push(relativeLabel(root, path));
+  }
+}
+async function mergeMarkdown(root, path, managed, report) {
+  if (await preserveUnsafeTarget(root, path, report))
+    return;
+  if (!await isFile(path)) {
+    await writeTextAtomic(path, `${managed}
+`);
+    report.created.push(relativeLabel(root, path));
+    return;
+  }
+  const current = await readFile2(path, "utf8");
+  const starts = markerIndexes(current, START);
+  const ends = markerIndexes(current, END);
+  if (starts.length === 1 && ends.length === 1 && ends[0] >= starts[0]) {
+    const start = starts[0];
+    const end = ends[0];
+    const next = `${current.slice(0, start)}${managed}${current.slice(end + END.length)}`;
+    if (next !== current) {
+      await writeTextAtomic(path, next);
+      report.updated.push(relativeLabel(root, path));
+    }
+    return;
+  }
+  if (starts.length > 0 || ends.length > 0) {
+    report.preserved.push(`${relativeLabel(root, path)} (unmatched Empirical marker)`);
+    return;
+  }
+  const separator = current.endsWith(`
+`) ? `
+` : `
+
+`;
+  await writeTextAtomic(path, `${current}${separator}${managed}
+`);
+  report.updated.push(relativeLabel(root, path));
+}
+async function mergeMcpJson(root, path, report, extra = {}) {
+  if (await preserveUnsafeTarget(root, path, report))
+    return;
+  let document = {};
+  const existed = await isFile(path);
+  if (existed) {
+    try {
+      document = await readJson(path);
+    } catch {
+      report.preserved.push(`${relativeLabel(root, path)} (invalid JSON)`);
+      return;
+    }
+  }
+  if (document.mcpServers !== undefined && !isRecord2(document.mcpServers)) {
+    report.preserved.push(`${relativeLabel(root, path)} (invalid mcpServers value)`);
+    return;
+  }
+  const servers = isRecord2(document.mcpServers) ? document.mcpServers : {};
+  const existing = servers.empirical;
+  const desired = { ...MCP_SERVER, ...extra };
+  if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(desired)) {
+    report.preserved.push(`${relativeLabel(root, path)} (existing empirical MCP entry)`);
+    return;
+  }
+  if (existing !== undefined)
+    return;
+  document.mcpServers = { ...servers, empirical: desired };
+  await writeJsonAtomic(path, document);
+  (existed ? report.updated : report.created).push(relativeLabel(root, path));
+}
+async function mergeCodexToml(root, path, report) {
+  if (await preserveUnsafeTarget(root, path, report))
+    return;
+  const start = "# empirical-sdd:mcp:start";
+  const end = "# empirical-sdd:mcp:end";
+  const block = `${start}
+[mcp_servers.empirical]
+command = "empirical"
+args = ["mcp"]
+${end}`;
+  if (!await isFile(path)) {
+    await writeTextAtomic(path, `${block}
+`);
+    report.created.push(relativeLabel(root, path));
+    return;
+  }
+  const current = await readFile2(path, "utf8");
+  const starts = markerIndexes(current, start);
+  const ends = markerIndexes(current, end);
+  if (starts.length === 1 && ends.length === 1 && ends[0] >= starts[0]) {
+    const blockStart = starts[0];
+    const blockEnd = ends[0];
+    const next = `${current.slice(0, blockStart)}${block}${current.slice(blockEnd + end.length)}`;
+    if (next !== current) {
+      await writeTextAtomic(path, next);
+      report.updated.push(relativeLabel(root, path));
+    }
+    return;
+  }
+  if (starts.length > 0 || ends.length > 0) {
+    report.preserved.push(`${relativeLabel(root, path)} (unmatched Empirical marker)`);
+    return;
+  }
+  if (/^\s*\[mcp_servers\.empirical\]\s*$/m.test(current)) {
+    report.preserved.push(`${relativeLabel(root, path)} (existing empirical MCP table)`);
+    return;
+  }
+  const separator = current.endsWith(`
+`) ? `
+` : `
+
+`;
+  await writeTextAtomic(path, `${current}${separator}${block}
+`);
+  report.updated.push(relativeLabel(root, path));
+}
+async function preserveUnsafeTarget(root, path, report) {
+  const rootPath = resolve2(root);
+  const targetPath = resolve2(path);
+  const label = relativeLabel(rootPath, targetPath);
+  if (!label || label === ".." || label.startsWith("../") || isAbsolute(label)) {
+    throw new EmpiricalError("INVALID_ARGUMENT", `Integration target escapes its root: ${path}`);
+  }
+  const segments = label.split("/");
+  let current = rootPath;
+  for (let index = 0;index < segments.length; index += 1) {
+    current = join2(current, segments[index]);
+    let details;
+    try {
+      details = await lstat2(current);
+    } catch (error) {
+      if (isMissingPathError(error))
+        return false;
+      throw error;
+    }
+    if (details.isSymbolicLink()) {
+      const suffix = index === segments.length - 1 ? "symbolic link" : `symbolic link ancestor ${relativeLabel(rootPath, current)}`;
+      report.preserved.push(`${label} (${suffix})`);
+      return true;
+    }
+    if (index < segments.length - 1 && !details.isDirectory()) {
+      report.preserved.push(`${label} (non-directory ancestor ${relativeLabel(rootPath, current)})`);
+      return true;
+    }
+    if (index === segments.length - 1 && !details.isFile()) {
+      report.preserved.push(`${label} (existing non-file)`);
+      return true;
+    }
+  }
+  return false;
+}
+function isMissingPathError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function markerIndexes(contents, marker) {
+  const indexes = [];
+  let offset = 0;
+  while (offset < contents.length) {
+    const index = contents.indexOf(marker, offset);
+    if (index < 0)
+      break;
+    indexes.push(index);
+    offset = index + marker.length;
+  }
+  return indexes;
+}
+function relativeLabel(root, path) {
+  return relative(root, path).replaceAll("\\", "/");
+}
+
+// src/decisions.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+var REQUIRED_SECTIONS = [
+  "Evidence",
+  "Options",
+  "Chosen approach",
+  "Trade-offs and risks",
+  "Verification"
+];
+function decisionPath(store, feature) {
+  return join3(store.specDirectory(feature), "decisions.md");
+}
+async function createDecisionTemplate(store, feature) {
+  const path = decisionPath(store, feature);
+  await store.assertFeaturePathSafe(feature, [path]);
+  if (await isFile(path))
+    return;
+  await writeTextAtomic(path, renderDecisionTemplate(feature));
+}
+async function validateDecisions(store, feature, requireAccepted = true) {
+  const path = decisionPath(store, feature);
+  await store.assertFeaturePathSafe(feature, [path]);
+  if (!await isFile(path)) {
+    return { valid: false, decisions: [], issues: [`Create ${path}`] };
+  }
+  return parseDecisions(await readFile3(path, "utf8"), requireAccepted);
+}
+function parseDecisions(markdown, requireAccepted = true) {
+  const issues = [];
+  if (/^#{1,6}\s+.*(?:chain[- ]of[- ]thought|private reasoning|prompt transcript|scratchpad|credentials?|secrets?)\b/im.test(markdown)) {
+    issues.push("Decision records cannot contain hidden-reasoning, prompt, credential, or secret sections");
+  }
+  const heading = /^##\s+(D-\d{3}):\s*(.+?)\s*$/gim;
+  const matches = [...markdown.matchAll(heading)];
+  const parsed = [];
+  const seen = new Set;
+  for (let index = 0;index < matches.length; index += 1) {
+    const match = matches[index];
+    const id = match[1].toUpperCase();
+    const title = match[2].trim();
+    const start = (match.index ?? 0) + match[0].length;
+    const end = matches[index + 1]?.index ?? markdown.length;
+    const body = markdown.slice(start, end);
+    if (seen.has(id))
+      issues.push(`${id} is duplicated`);
+    seen.add(id);
+    const statusMatch = /^Status:\s*(Proposed|Accepted|Superseded)\s*$/im.exec(body);
+    if (!statusMatch) {
+      issues.push(`${id} needs Status: Proposed, Accepted, or Superseded`);
+      continue;
+    }
+    const sections = new Map;
+    for (const name of REQUIRED_SECTIONS)
+      sections.set(name, section(body, name));
+    for (const name of REQUIRED_SECTIONS) {
+      const value = sections.get(name) ?? "";
+      if (!meaningful(value))
+        issues.push(`${id} has an empty ${name} section`);
+    }
+    const supersedes = /^Supersedes:\s*(.+)$/im.exec(body)?.[1]?.split(",").map((value) => value.trim().toUpperCase()).filter(Boolean) ?? [];
+    const supersededBy = /^Superseded by:\s*(D-\d{3})\s*$/im.exec(body)?.[1]?.toUpperCase() ?? null;
+    const status = statusMatch[1];
+    if (status === "Superseded" && !supersededBy)
+      issues.push(`${id} is Superseded but has no Superseded by link`);
+    if (status !== "Superseded" && supersededBy)
+      issues.push(`${id} has Superseded by but is not Superseded`);
+    parsed.push({
+      id,
+      title,
+      status,
+      evidence: sections.get("Evidence") ?? "",
+      options: sections.get("Options") ?? "",
+      chosenApproach: sections.get("Chosen approach") ?? "",
+      tradeoffs: sections.get("Trade-offs and risks") ?? "",
+      verification: sections.get("Verification") ?? "",
+      supersedes,
+      supersededBy
+    });
+  }
+  if (parsed.length === 0)
+    issues.push("Add at least one material decision entry");
+  if (requireAccepted && !parsed.some((decision) => decision.status === "Accepted")) {
+    issues.push("Accept at least one material decision before completing Design");
+  }
+  const byId = new Map(parsed.map((decision) => [decision.id, decision]));
+  for (const decision of parsed) {
+    for (const previousId of decision.supersedes) {
+      const previous = byId.get(previousId);
+      if (!previous)
+        issues.push(`${decision.id} supersedes missing ${previousId}`);
+      else if (previous.status !== "Superseded" || previous.supersededBy !== decision.id) {
+        issues.push(`${decision.id} and ${previousId} need reciprocal supersession links`);
+      }
+    }
+    if (decision.supersededBy) {
+      const replacement = byId.get(decision.supersededBy);
+      if (!replacement || !replacement.supersedes.includes(decision.id)) {
+        issues.push(`${decision.id} points to ${decision.supersededBy} without a reciprocal Supersedes link`);
+      }
+    }
+  }
+  const decisions = parsed.filter((decision) => decision.status !== "Proposed").map((decision) => ({
+    id: decision.id,
+    title: decision.title,
+    status: decision.status,
+    chosenApproach: summarize(decision.chosenApproach),
+    supersedes: decision.supersedes,
+    supersededBy: decision.supersededBy
+  }));
+  return { valid: issues.length === 0, decisions, issues };
+}
+async function requireValidDecisions(store, feature) {
+  const report = await validateDecisions(store, feature, true);
+  if (!report.valid) {
+    throw new EmpiricalError("DECISIONS_REQUIRED", `Decision record is incomplete: ${report.issues.join("; ")}`);
+  }
+  return report.decisions;
+}
+function section(body, title) {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`^###\\s+${escaped}\\s*$`, "im").exec(body);
+  if (!match)
+    return "";
+  const start = (match.index ?? 0) + match[0].length;
+  const next = /^###\s+/m.exec(body.slice(start));
+  return body.slice(start, next?.index === undefined ? body.length : start + next.index).trim();
+}
+function meaningful(value) {
+  const clean = value.replace(/<!--[^]*?-->/g, "").replace(/[-*#>`_\s]/g, "").trim();
+  return clean.length >= 3 && !/^(todo|tbd|none|n\/a|fillthisin)$/i.test(clean);
+}
+function summarize(value) {
+  return value.replace(/^[-*]\s+/gm, "").replace(/\s+/g, " ").trim().slice(0, 500);
+}
+function renderDecisionTemplate(feature) {
+  return `# Decisions: ${title(feature)}
+
+Record concise, externally reviewable evidence and choices here. Do not store
+private chain-of-thought, prompts, credentials, secrets, or scratchpad text.
+
+## D-001: Select the implementation approach
+
+Status: Proposed
+
+### Evidence
+
+<!-- Repository facts, user constraints, or measured behavior. -->
+
+### Options
+
+<!-- Two or more viable approaches. -->
+
+### Chosen approach
+
+<!-- Change Status to Accepted and state the chosen approach. -->
+
+### Trade-offs and risks
+
+<!-- Costs, limitations, failure modes, and mitigations. -->
+
+### Verification
+
+<!-- Checks that will prove the decision was implemented correctly. -->
+`;
+}
+function title(feature) {
+  return feature.split("-").filter(Boolean).map((word) => `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`).join(" ");
+}
+
+// src/worktrees.ts
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstat as lstat3 } from "node:fs/promises";
+import { basename, dirname as dirname3, isAbsolute as isAbsolute2, relative as relative2, resolve as resolve3, sep } from "node:path";
+function inferChangeType(request) {
+  if (/\b(fix|bug|broken|regression|repair|crash|error|incorrect)\b/i.test(request))
+    return "fix";
+  if (/\b(chore|docs?|test|release|upgrade|update|maintenance|refactor|cleanup|migrate)\b/i.test(request))
+    return "chore";
+  return "feature";
+}
+function featureSlug(request) {
+  const slug = request.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").split("-").slice(0, 10).join("-").slice(0, 72).replace(/-$/, "");
+  return slug || "feature";
+}
+function proposeWorktree(root, request, workflow, activeFeature, config, overrides = {}) {
+  const cleanRequest = request.trim();
+  if (!cleanRequest)
+    throw new EmpiricalError("REQUEST_REQUIRED", "A non-empty feature request is required");
+  const repoRoot = git(root, ["rev-parse", "--show-toplevel"]);
+  const feature = overrides.feature ?? featureSlug(cleanRequest);
+  assertFeature(feature);
+  const changeType = overrides.changeType ?? inferChangeType(cleanRequest);
+  const base = overrides.base ?? (config.baseBranch === "auto" ? detectBase(repoRoot) : config.baseBranch);
+  const baseCommit = resolveBase(repoRoot, base);
+  const repo = basename(repoRoot);
+  const branch = overrides.branch ?? renderTemplate(config.branchPattern, { repo, feature, type: changeType });
+  assertBranch(repoRoot, branch);
+  const pathValue = overrides.path ?? renderTemplate(config.worktreePath, { repo, feature, type: changeType });
+  const path = resolve3(isAbsolute2(pathValue) ? pathValue : resolve3(repoRoot, pathValue));
+  assertSafeTarget(repoRoot, path);
+  const approvedFields = {
+    root: repoRoot,
+    request: cleanRequest,
+    workflow,
+    changeType,
+    feature,
+    branch,
+    path,
+    base,
+    baseCommit,
+    activeFeature
+  };
+  return {
+    kind: "worktree_proposal",
+    protocol: "empirical-sdd",
+    schemaVersion: SCHEMA_VERSION,
+    ...approvedFields,
+    approvalToken: createHash("sha256").update(JSON.stringify(approvedFields)).digest("hex"),
+    command: ["git", "worktree", "add", "-b", branch, path, baseCommit],
+    requiresApproval: true
+  };
+}
+async function createGitWorktree(proposal) {
+  const repoRoot = git(proposal.root, ["rev-parse", "--show-toplevel"]);
+  if (resolve3(repoRoot) !== resolve3(proposal.root)) {
+    throw new EmpiricalError("STALE_WORKTREE_PROPOSAL", "The proposal repository root changed");
+  }
+  const status = git(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"], true);
+  if (status.trim()) {
+    throw new EmpiricalError("DIRTY_CHECKOUT", "Commit, stash, or remove current changes before Empirical creates a worktree");
+  }
+  assertFeature(proposal.feature);
+  const currentBaseCommit = resolveBase(repoRoot, proposal.base);
+  if (currentBaseCommit !== proposal.baseCommit) {
+    throw new EmpiricalError("STALE_WORKTREE_PROPOSAL", `Base ${proposal.base} moved from ${proposal.baseCommit} to ${currentBaseCommit}; review a new proposal`);
+  }
+  assertBranch(repoRoot, proposal.branch);
+  assertSafeTarget(repoRoot, proposal.path);
+  if (await pathExists2(proposal.path)) {
+    throw new EmpiricalError("WORKTREE_PATH_EXISTS", `Worktree path already exists: ${proposal.path}`);
+  }
+  const worktrees = parseWorktreePaths(git(repoRoot, ["worktree", "list", "--porcelain"]));
+  if (worktrees.some((path) => resolve3(path) === resolve3(proposal.path))) {
+    throw new EmpiricalError("WORKTREE_PATH_EXISTS", `Worktree path is already registered: ${proposal.path}`);
+  }
+  const existingBranch = runGit(repoRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${proposal.branch}`]);
+  if (existingBranch.status === 0) {
+    throw new EmpiricalError("WORKTREE_BRANCH_EXISTS", `Branch already exists: ${proposal.branch}`);
+  }
+  const result = runGit(repoRoot, ["worktree", "add", "-b", proposal.branch, proposal.path, proposal.baseCommit]);
+  if (result.status !== 0 || result.error) {
+    throw new EmpiricalError("WORKTREE_CREATE_FAILED", result.error?.message || result.stderr.trim() || `git exited with ${String(result.status)}`);
+  }
+}
+function detectBase(root) {
+  const originHead = runGit(root, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  if (originHead.status === 0 && originHead.stdout.trim())
+    return originHead.stdout.trim();
+  for (const candidate of ["main", "master"]) {
+    if (runGit(root, ["rev-parse", "--verify", "--quiet", candidate]).status === 0)
+      return candidate;
+    const remote = `origin/${candidate}`;
+    if (runGit(root, ["rev-parse", "--verify", "--quiet", remote]).status === 0)
+      return remote;
+  }
+  throw new EmpiricalError("BASE_BRANCH_REQUIRED", "Empirical could not detect origin/HEAD, main, or master; provide --base <ref>");
+}
+function resolveBase(root, base) {
+  if (!base.trim() || /[\0\r\n]/.test(base))
+    throw new EmpiricalError("INVALID_BASE", "Git base ref is invalid");
+  const result = runGit(root, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]);
+  if (result.status !== 0 || !result.stdout.trim()) {
+    throw new EmpiricalError("BASE_NOT_FOUND", `Git base does not resolve to a commit: ${base}`);
+  }
+  return result.stdout.trim();
+}
+function assertBranch(root, branch) {
+  if (!branch.trim() || runGit(root, ["check-ref-format", "--branch", branch]).status !== 0) {
+    throw new EmpiricalError("INVALID_BRANCH", `Invalid Git branch: ${branch}`);
+  }
+  if (!/^(feature|fix|chore)\//.test(branch)) {
+    throw new EmpiricalError("INVALID_BRANCH", "Worktree branches must begin with feature/, fix/, or chore/");
+  }
+}
+function assertFeature(feature) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(feature) || feature.length > 80) {
+    throw new EmpiricalError("INVALID_FEATURE", `Invalid feature id: ${feature}`);
+  }
+}
+function assertSafeTarget(repoRoot, target) {
+  const root = resolve3(repoRoot);
+  const path = resolve3(target);
+  if (path === root || root.startsWith(`${path}${sep}`)) {
+    throw new EmpiricalError("INVALID_WORKTREE_PATH", "Worktree path cannot be the repository or its ancestor");
+  }
+  if (path.startsWith(`${root}${sep}`)) {
+    throw new EmpiricalError("INVALID_WORKTREE_PATH", "Worktree path must be outside the current checkout");
+  }
+  if (!relative2(dirname3(root), path)) {
+    throw new EmpiricalError("INVALID_WORKTREE_PATH", "Worktree path must identify a new checkout");
+  }
+}
+function renderTemplate(template, values) {
+  const rendered = template.replaceAll("{repo}", values.repo).replaceAll("{feature}", values.feature).replaceAll("{type}", values.type);
+  if (/[{}\0\r\n]/.test(rendered)) {
+    throw new EmpiricalError("INVALID_CONFIG", `Template did not resolve safely: ${template}`);
+  }
+  return rendered;
+}
+function git(root, args, allowEmpty = false) {
+  const result = runGit(root, args);
+  if (result.status !== 0 || result.error) {
+    throw new EmpiricalError("GIT_REQUIRED", result.error?.message || result.stderr.trim() || `git ${args[0]} failed`);
+  }
+  const output = result.stdout.trim();
+  if (!allowEmpty && !output)
+    throw new EmpiricalError("GIT_REQUIRED", `git ${args.join(" ")} returned no value`);
+  return output;
+}
+function runGit(root, args) {
+  return spawnSync("git", args, { cwd: root, encoding: "utf8", shell: false });
+}
+function parseWorktreePaths(output) {
+  return output.split(/\r?\n/).filter((line) => line.startsWith("worktree ")).map((line) => line.slice(9));
+}
+async function pathExists2(path) {
+  try {
+    await lstat3(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+
+// src/specifications.ts
+import { readFile as readFile4, readdir as readdir2 } from "node:fs/promises";
+import { createHash as createHash2 } from "node:crypto";
+import { join as join4, relative as relative3 } from "node:path";
+async function loadCapabilityDeltas(store, feature) {
+  const directory = store.deltaDirectory(feature);
+  if (await isSymbolicLink(directory)) {
+    throw new EmpiricalError("INVALID_DELTA", `Capability delta storage cannot use symbolic links: ${directory}`);
+  }
+  let entries;
+  try {
+    entries = await readdir2(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return [];
+    throw new EmpiricalError("INVALID_DELTA", `Could not read ${directory}`, error);
+  }
+  const deltas = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isFile() || !entry.name.endsWith(".md"))
+      continue;
+    const capability = entry.name.slice(0, -3);
+    assertCapabilityId(capability);
+    const path = join4(directory, entry.name);
+    deltas.push(parseCapabilityDelta(capability, await readFile4(path, "utf8"), portableRelative(store.root, path)));
+  }
+  return deltas;
+}
+function parseCapabilityDelta(capability, markdown, source = `${capability}.md`) {
+  assertCapabilityId(capability);
+  const purpose = sectionContents(markdown, "Purpose");
+  const requirements = [];
+  const sectionPattern = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/gim;
+  const sections = [...markdown.matchAll(sectionPattern)];
+  for (let index = 0;index < sections.length; index += 1) {
+    const match = sections[index];
+    const label = match[1].toLowerCase();
+    if (label === "renamed") {
+      throw new EmpiricalError("INVALID_DELTA", `${source}: RENAMED requirements are not supported; use add/remove with migration text`);
+    }
+    const operation = label;
+    const start = (match.index ?? 0) + match[0].length;
+    const end = sections[index + 1]?.index ?? markdown.length;
+    const body = markdown.slice(start, end);
+    const blocks = requirementBlocks(body);
+    if (blocks.length === 0) {
+      throw new EmpiricalError("INVALID_DELTA", `${source}: ${match[1]} Requirements has no requirement blocks`);
+    }
+    for (const block of blocks) {
+      if (!/^####\s+Scenario:\s*\S+/im.test(block.contents)) {
+        throw new EmpiricalError("INVALID_DELTA", `${source}: requirement '${block.name}' needs at least one #### Scenario`);
+      }
+      requirements.push({ operation, name: block.name, contents: block.contents.trim() });
+    }
+  }
+  if (requirements.length === 0) {
+    throw new EmpiricalError("INVALID_DELTA", `${source}: no ADDED, MODIFIED, or REMOVED requirements found`);
+  }
+  return { capability, purpose: purpose?.trim() || null, requirements, source };
+}
+async function validateFeatureDeltas(store, feature) {
+  try {
+    const deltas = await loadCapabilityDeltas(store, feature);
+    if (deltas.length === 0) {
+      return {
+        valid: false,
+        capabilities: [],
+        operations: 0,
+        issues: [`Create at least one ${portableRelative(store.root, store.deltaDirectory(feature))}/<capability>.md delta`],
+        digest: null
+      };
+    }
+    const planned = await buildProjections(store, deltas);
+    return {
+      valid: planned.issues.length === 0,
+      capabilities: [...new Set(deltas.map((delta) => delta.capability))],
+      operations: deltas.reduce((total, delta) => total + delta.requirements.length, 0),
+      issues: planned.issues,
+      digest: digestCapabilityDeltas(deltas)
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      capabilities: [],
+      operations: 0,
+      issues: [error instanceof Error ? error.message : String(error)],
+      digest: null
+    };
+  }
+}
+async function capabilityDeltaDigest(store, feature) {
+  const deltas = await loadCapabilityDeltas(store, feature);
+  return deltas.length === 0 ? null : digestCapabilityDeltas(deltas);
+}
+async function planCapabilityArchive(store, feature) {
+  const deltas = await loadCapabilityDeltas(store, feature);
+  if (deltas.length === 0) {
+    throw new EmpiricalError("DELTA_REQUIRED", `Complex change ${feature} has no capability deltas`);
+  }
+  const planned = await buildProjections(store, deltas);
+  if (planned.issues.length > 0) {
+    throw new EmpiricalError("INVALID_DELTA", `Capability archive is invalid: ${planned.issues.join("; ")}`);
+  }
+  const counts = { added: 0, modified: 0, removed: 0 };
+  for (const delta of deltas) {
+    for (const requirement of delta.requirements)
+      counts[requirement.operation] += 1;
+  }
+  return {
+    report: {
+      capabilities: planned.projections.map((projection) => projection.capability),
+      ...counts
+    },
+    commit: async () => {
+      const applied = [];
+      const rollback = async () => {
+        for (const projection of [...applied].reverse()) {
+          if (projection.original === null)
+            await store.removeCapability(projection.capability);
+          else
+            await store.writeCapability(projection.capability, projection.original);
+        }
+      };
+      try {
+        for (const projection of planned.projections) {
+          await store.writeCapability(projection.capability, projection.next);
+          applied.push(projection);
+        }
+      } catch (error) {
+        try {
+          await rollback();
+        } catch (rollbackError) {
+          throw new EmpiricalError("ARCHIVE_ROLLBACK_FAILED", "Capability archive failed and could not fully restore its earlier writes", {
+            error: error instanceof Error ? error.message : String(error),
+            rollbackError: rollbackError instanceof Error ? rollbackError.message : String(rollbackError)
+          });
+        }
+        throw error;
+      }
+      return rollback;
+    }
+  };
+}
+async function listCapabilities(store) {
+  const summaries = [];
+  for (const name of await store.listCapabilityNames()) {
+    const path = store.capabilitySpecPath(name);
+    if (!await isFile(path))
+      continue;
+    const contents = await readFile4(path, "utf8");
+    summaries.push({
+      name,
+      path: portableRelative(store.root, path),
+      requirements: requirementBlocks(contents).length
+    });
+  }
+  return summaries;
+}
+function portableRelative(from, to) {
+  return relative3(from, to).replaceAll("\\", "/");
+}
+async function buildProjections(store, deltas) {
+  const grouped = new Map;
+  for (const delta of deltas) {
+    const group = grouped.get(delta.capability) ?? [];
+    group.push(delta);
+    grouped.set(delta.capability, group);
+  }
+  const projections = [];
+  const issues = [];
+  for (const [capability, capabilityDeltas] of [...grouped].sort(([left], [right]) => left.localeCompare(right))) {
+    const original = await store.readCapability(capability);
+    const current = new Map(requirementBlocks(original ?? "").map((block) => [normalizedName(block.name), block]));
+    const touched = new Set;
+    let purpose = original ? sectionContents(original, "Purpose") : null;
+    for (const delta of capabilityDeltas) {
+      if (!purpose && delta.purpose)
+        purpose = delta.purpose;
+      for (const requirement of delta.requirements) {
+        const key = normalizedName(requirement.name);
+        if (touched.has(key)) {
+          issues.push(`${delta.source}: requirement '${requirement.name}' is changed more than once`);
+          continue;
+        }
+        touched.add(key);
+        const existing = current.get(key);
+        if (requirement.operation === "added") {
+          if (existing)
+            issues.push(`${delta.source}: cannot add existing requirement '${requirement.name}'`);
+          else
+            current.set(key, { name: requirement.name, contents: requirement.contents });
+        } else if (requirement.operation === "modified") {
+          if (!existing)
+            issues.push(`${delta.source}: cannot modify missing requirement '${requirement.name}'`);
+          else
+            current.set(key, { name: requirement.name, contents: requirement.contents });
+        } else if (!existing) {
+          issues.push(`${delta.source}: cannot remove missing requirement '${requirement.name}'`);
+        } else {
+          current.delete(key);
+        }
+      }
+    }
+    if (!original && (!purpose || purpose.trim().length < 20)) {
+      issues.push(`${capability}: new capability needs a meaningful ## Purpose`);
+    }
+    projections.push({
+      capability,
+      original,
+      next: renderCapability(capability, purpose, [...current.values()].map((block) => block.contents))
+    });
+  }
+  return { projections, issues };
+}
+function requirementBlocks(markdown) {
+  const pattern = /^###\s+Requirement:\s*(.+?)\s*$/gim;
+  const matches = [...markdown.matchAll(pattern)];
+  return matches.map((match, index) => {
+    const start = match.index ?? 0;
+    const end = matches[index + 1]?.index ?? nextSecondLevelHeading(markdown, start + match[0].length);
+    return { name: match[1].trim(), contents: markdown.slice(start, end).trim() };
+  });
+}
+function nextSecondLevelHeading(markdown, start) {
+  const match = /^##\s+/m.exec(markdown.slice(start));
+  return match?.index === undefined ? markdown.length : start + match.index;
+}
+function sectionContents(markdown, title2) {
+  const pattern = new RegExp(`^##\\s+${escapeRegExp(title2)}\\s*$`, "im");
+  const match = pattern.exec(markdown);
+  if (!match)
+    return null;
+  const start = (match.index ?? 0) + match[0].length;
+  const end = nextSecondLevelHeading(markdown, start);
+  return markdown.slice(start, end).trim();
+}
+function renderCapability(capability, purpose, requirements) {
+  const title2 = capability.split("-").map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" ");
+  const body = requirements.length > 0 ? `${requirements.join(`
+
+`)}
+` : `_No current requirements._
+`;
+  return `# ${title2} Specification
+
+## Purpose
+
+${purpose?.trim() ?? `Current behavior for ${title2}.`}
+
+## Requirements
+
+${body}`;
+}
+function normalizedName(name) {
+  return name.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function digestCapabilityDeltas(deltas) {
+  return createHash2("sha256").update(JSON.stringify(deltas)).digest("hex");
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/core.ts
+var FAST_PHASES = ["implement", "done"];
+var QUICK_PHASES = ["shape", "implement", "verify", "review", "done"];
+var COMPLEX_PHASES = [
+  "specify",
+  "design",
+  "plan",
+  "implement",
+  "verify",
+  "review",
+  "archive",
+  "done"
+];
+
+class EmpiricalProject {
+  store;
+  readOnly;
+  constructor(store, readOnly = false) {
+    this.store = store;
+    this.readOnly = readOnly;
+  }
+  static async open(start = process.cwd(), options = {}) {
+    const base = await discoverProject(start);
+    const migrate = options.migrate !== false;
+    if (migrate)
+      await base.migrateSchema();
+    const active = await base.activeFeature(migrate);
+    return new EmpiricalProject(active ? base.forFeature(active) : base);
+  }
+  static async openReadOnly(start = process.cwd()) {
+    const base = await discoverProject(start);
+    await base.assertCurrentSchemaReadOnly();
+    const active = await base.activeFeature(false);
+    return new EmpiricalProject(active ? base.forFeature(active) : base, true);
+  }
+  static async initialize(root = process.cwd(), options = {}) {
+    const absoluteRoot = resolve4(root);
+    await mkdir2(absoluteRoot, { recursive: true });
+    const store = new ProjectStore(absoluteRoot);
+    if (await store.exists()) {
+      const integrations2 = options.integrations === false ? emptyIntegrationReport() : await installProjectIntegrations(absoluteRoot);
+      await store.migrateSchema();
+      const active = await store.activeFeature();
+      const project = new EmpiricalProject(active ? store.forFeature(active) : store);
+      return { project, state: await project.store.loadState(), integrations: integrations2 };
+    }
+    if (await isFile(join5(absoluteRoot, "ai", "STATE.md"))) {
+      throw new EmpiricalError("LEGACY_PROJECT", "An Empirical v1 ai/ workspace already exists; run empirical adopt");
+    }
+    const profile = options.profile ?? "complex";
+    assertWorkflow(profile);
+    const config = defaultConfig(profile, null, options);
+    const state = initialState(profile);
+    await store.writeInitial(config);
+    const integrations = options.integrations === false ? emptyIntegrationReport() : await installProjectIntegrations(absoluteRoot);
+    return { project: new EmpiricalProject(store), state, integrations };
+  }
+  static async adopt(root = process.cwd(), options = {}) {
+    const absoluteRoot = resolve4(root);
+    const store = new ProjectStore(absoluteRoot);
+    if (await store.exists()) {
+      const integrations2 = options.integrations === false ? emptyIntegrationReport() : await installProjectIntegrations(absoluteRoot);
+      await store.migrateSchema();
+      const active = await store.activeFeature();
+      const project2 = new EmpiricalProject(active ? store.forFeature(active) : store);
+      return { project: project2, state: await project2.store.loadState(), integrations: integrations2 };
+    }
+    const legacyStatePath = join5(absoluteRoot, "ai", "STATE.md");
+    if (!await isFile(legacyStatePath)) {
+      throw new EmpiricalError("LEGACY_NOT_FOUND", "No ai/STATE.md was found; use empirical init for a new repository");
+    }
+    const legacy = await readFile5(legacyStatePath, "utf8");
+    const feature = legacyField(legacy, "current_spec") ?? legacyField(legacy, "currentSpec");
+    const legacyPhase = legacyField(legacy, "current_phase") ?? legacyField(legacy, "currentPhase") ?? legacyField(legacy, "phase");
+    const profile = options.profile ?? "complex";
+    assertWorkflow(profile);
+    const phase = feature ? mapLegacyPhase(legacyPhase, profile) : "idle";
+    const now = new Date().toISOString();
+    const state = {
+      ...initialState(profile),
+      activeFeature: feature,
+      phase,
+      status: phase === "idle" ? "idle" : phase === "done" ? "done" : "waiting",
+      updatedAt: now,
+      message: "Adopted non-destructively from ai/"
+    };
+    await store.writeInitial(defaultConfig(profile, "ai", options));
+    if (feature) {
+      const legacySpec = join5(absoluteRoot, "ai", "specs", feature, "spec.md");
+      if (await isFile(legacySpec)) {
+        await store.writeSpec(feature, await readFile5(legacySpec, "utf8"));
+      } else {
+        const request = `Adopted v1 feature ${feature}`;
+        await store.writeSpec(feature, profile === "fast" ? renderFastSpec(feature, request) : renderSpec(feature, request));
+      }
+      await store.forFeature(feature).writeInitialFeature(state, "empirical-adopt", "Adopted Empirical v1 state");
+    }
+    const integrations = options.integrations === false ? emptyIntegrationReport() : await installProjectIntegrations(absoluteRoot);
+    const project = new EmpiricalProject(feature ? store.forFeature(feature) : store);
+    return { project, state, integrations };
+  }
+  async status() {
+    return this.store.loadState(!this.readOnly);
+  }
+  async config() {
+    return this.store.loadConfig();
+  }
+  async configure(input) {
+    const current = await this.store.loadConfig();
+    return this.store.configure({
+      ...current,
+      isolation: { ...current.isolation, ...input.isolation },
+      decisions: { ...current.decisions, ...input.decisions },
+      setupComplete: input.setupComplete ?? true
+    });
+  }
+  async policy() {
+    return this.store.loadPolicy();
+  }
+  async explore(problem) {
+    const cleanProblem = problem.trim();
+    if (!cleanProblem)
+      throw new EmpiricalError("REQUEST_REQUIRED", "A non-empty problem is required");
+    const policy = await this.store.loadPolicy();
+    const capabilities = await listCapabilities(this.store);
+    return {
+      protocol: "empirical-sdd",
+      schemaVersion: SCHEMA_VERSION,
+      root: this.store.root,
+      problem: cleanProblem,
+      instructions: [
+        "Use the current host agent only. Inspect the relevant code and living capability specifications; do not write implementation code yet.",
+        "Identify the observed problem, affected users, current behavior, smallest useful outcome, constraints, risks, and two or three viable approaches.",
+        "Ask only questions whose answers materially change scope or architecture, then restate the refined request in observable terms.",
+        "Choose Fast only when the refined change is explicit, tiny, localized, reversible, low-risk, and non-UI; choose Complex otherwise."
+      ],
+      questions: [
+        "Who experiences the problem and what observable behavior should change?",
+        "What is the smallest useful outcome, and what is explicitly out of scope?",
+        "Which assumption, dependency, or risk could change the implementation approach?"
+      ],
+      projectContext: policy.context,
+      capabilityContext: capabilities.map((capability) => capability.path),
+      next: {
+        fast: `empirical fast ${JSON.stringify(cleanProblem)}`,
+        complex: `empirical complex ${JSON.stringify(cleanProblem)}`
+      }
+    };
+  }
+  async capabilities() {
+    return listCapabilities(this.store);
+  }
+  async capability(name) {
+    return this.store.readCapability(name);
+  }
+  async start(request, options = {}) {
+    const cleanRequest = request.trim();
+    if (!cleanRequest) {
+      throw new EmpiricalError("REQUEST_REQUIRED", "A non-empty feature request is required");
+    }
+    const configuredProfile = (await this.store.loadConfig()).profile;
+    const profile = options.profile ?? (configuredProfile === "quick" ? "complex" : configuredProfile);
+    assertWorkflow(profile);
+    const base = new ProjectStore(this.store.root);
+    const active = await base.activeFeature();
+    if (active) {
+      const current = await base.forFeature(active).loadState();
+      if (current.request?.trim() === cleanRequest) {
+        this.store = base.forFeature(active);
+        return assertStartAction(await this.next(), cleanRequest, profile, options);
+      }
+      return this.proposeWorktree(cleanRequest, profile, { ...options.id ? { feature: options.id } : {} });
+    }
+    const started = await base.withResourceLock("specs", async () => {
+      const raced = await base.activeFeature();
+      if (raced) {
+        const current = await base.forFeature(raced).loadState();
+        if (current.request?.trim() === cleanRequest) {
+          return { existing: true, store: base.forFeature(raced), state: current, spec: await base.readSpec(raced) };
+        }
+        return { proposal: await this.proposeWorktree(cleanRequest, profile, { ...options.id ? { feature: options.id } : {} }) };
+      }
+      const feature = options.id ?? featureSlug(cleanRequest);
+      if ((await base.listFeatureIds()).includes(feature)) {
+        throw new EmpiricalError("FEATURE_EXISTS", `Feature ${feature} already exists; choose a distinct --id`);
+      }
+      const spec = profile === "fast" ? renderFastSpec(titleFromFeature(feature), cleanRequest) : renderSpec(titleFromFeature(feature), cleanRequest);
+      await base.writeSpec(feature, spec);
+      if (profile === "complex")
+        await createDecisionTemplate(base, feature);
+      const state = {
+        ...initialState(profile),
+        revision: 1,
+        activeFeature: feature,
+        request: cleanRequest,
+        phase: firstPhase(profile),
+        status: "waiting",
+        specDigest: digest(spec),
+        capabilityArchiveRequired: profile === "complex",
+        updatedAt: new Date().toISOString()
+      };
+      const scoped = base.forFeature(feature);
+      await scoped.writeInitialFeature(state);
+      return { existing: false, store: scoped, state, spec };
+    });
+    if ("proposal" in started)
+      return started.proposal;
+    this.store = started.store;
+    return this.packet(started.state, parseCriteria(started.spec));
+  }
+  async fast(request, options = {}) {
+    return this.begin(request, "fast", options);
+  }
+  async complex(request, options = {}) {
+    return this.begin(request, "complex", options);
+  }
+  async loop() {
+    if (arguments.length > 0) {
+      throw new EmpiricalError("INVALID_ARGUMENT", "Loop only resumes current work; start new work with empirical fast or empirical complex");
+    }
+    return this.next();
+  }
+  async begin(request, profile, options) {
+    const base = new ProjectStore(this.store.root);
+    const activeFeature = await base.activeFeature();
+    const current = activeFeature ? await base.forFeature(activeFeature).loadState() : await base.loadState();
+    const cleanRequest = request.trim();
+    if (!cleanRequest) {
+      throw new EmpiricalError("REQUEST_REQUIRED", "A non-empty feature request is required");
+    }
+    const currentRequest = current.request?.trim();
+    const active = current.activeFeature !== null && current.phase !== "done";
+    if (active) {
+      if (currentRequest !== cleanRequest) {
+        return this.proposeWorktree(cleanRequest, profile, { ...options.id ? { feature: options.id } : {} });
+      }
+      if (profile !== current.profile) {
+        throw new EmpiricalError("PROFILE_CONFLICT", `The active feature uses profile ${current.profile}, not ${profile}`);
+      }
+      if (options.id && options.id !== current.activeFeature) {
+        throw new EmpiricalError("FEATURE_ACTIVE", `The active feature is ${current.activeFeature}, not ${options.id}`);
+      }
+      this.store = base.forFeature(current.activeFeature);
+      return assertStartAction(await this.next(), cleanRequest, profile, options);
+    }
+    try {
+      return await this.start(cleanRequest, { profile, ...options });
+    } catch (error) {
+      if (error instanceof EmpiricalError && (error.code === "FEATURE_ACTIVE" || error.code === "PROJECT_BUSY")) {
+        const latest = await EmpiricalProject.open(this.store.root);
+        const action = await latest.next();
+        if (action.request === cleanRequest) {
+          this.store = latest.store;
+          return assertStartAction(action, cleanRequest, profile, options);
+        }
+      }
+      throw error;
+    }
+  }
+  async proposeWorktree(request, workflow, overrides = {}) {
+    const base = new ProjectStore(this.store.root);
+    const activeFeature = await base.activeFeature(!this.readOnly);
+    if (!activeFeature) {
+      throw new EmpiricalError("WORKTREE_NOT_NEEDED", "This checkout has no active feature; start the request here");
+    }
+    const config = await base.loadConfig();
+    if (config.isolation.mode === "off") {
+      throw new EmpiricalError("FEATURE_ACTIVE", `Feature ${activeFeature} is active and automatic worktree proposals are disabled`);
+    }
+    return proposeWorktree(base.root, request, workflow, activeFeature, config.isolation, overrides);
+  }
+  async createWorktree(input) {
+    if (input.approved !== true) {
+      throw new EmpiricalError("WORKTREE_APPROVAL_REQUIRED", "Worktree creation requires approved: true");
+    }
+    const proposal = await this.proposeWorktree(input.request, input.workflow, {
+      ...input.changeType ? { changeType: input.changeType } : {},
+      ...input.feature ? { feature: input.feature } : {},
+      ...input.branch ? { branch: input.branch } : {},
+      ...input.path ? { path: input.path } : {},
+      ...input.base ? { base: input.base } : {}
+    });
+    if (proposal.activeFeature !== input.activeFeature) {
+      throw new EmpiricalError("STALE_WORKTREE_PROPOSAL", `The active feature changed from ${input.activeFeature} to ${proposal.activeFeature}; review a new proposal`);
+    }
+    if (proposal.baseCommit !== input.baseCommit) {
+      throw new EmpiricalError("STALE_WORKTREE_PROPOSAL", `Base ${proposal.base} moved after approval; review a new proposal`);
+    }
+    if (proposal.approvalToken !== input.approvalToken) {
+      throw new EmpiricalError("STALE_WORKTREE_PROPOSAL", "The approved worktree fields changed; review and approve a new proposal");
+    }
+    await createGitWorktree(proposal);
+    try {
+      let project;
+      try {
+        project = await EmpiricalProject.open(proposal.path);
+      } catch (error) {
+        if (!(error instanceof EmpiricalError) || error.code !== "PROJECT_NOT_INITIALIZED")
+          throw error;
+        project = (await EmpiricalProject.initialize(proposal.path, { integrations: false })).project;
+      }
+      const result = proposal.workflow === "fast" ? await project.fast(proposal.request, { id: proposal.feature }) : await project.complex(proposal.request, { id: proposal.feature });
+      if (result.kind !== "action") {
+        throw new EmpiricalError("WORKTREE_HANDOFF_FAILED", `The new checkout already contains active feature ${result.activeFeature}`);
+      }
+      return {
+        kind: "worktree_handoff",
+        protocol: "empirical-sdd",
+        schemaVersion: SCHEMA_VERSION,
+        root: proposal.root,
+        path: proposal.path,
+        branch: proposal.branch,
+        base: proposal.base,
+        baseCommit: proposal.baseCommit,
+        feature: result.feature,
+        revision: result.revision,
+        workflow: proposal.workflow,
+        resume: `cd ${JSON.stringify(proposal.path)} && empirical loop`,
+        action: result
+      };
+    } catch (error) {
+      throw new EmpiricalError("WORKTREE_HANDOFF_FAILED", `Git created ${proposal.path}, but Empirical handoff failed: ${error instanceof Error ? error.message : String(error)}`, { path: proposal.path, branch: proposal.branch, base: proposal.base, baseCommit: proposal.baseCommit });
+    }
+  }
+  async explain() {
+    const state = await this.store.loadState(!this.readOnly);
+    const criteria = state.activeFeature ? parseCriteria(await this.store.readSpec(state.activeFeature)) : [];
+    const packet = await this.packet(state, criteria);
+    const decisions = state.activeFeature && state.profile === "complex" ? (await validateDecisions(this.store, state.activeFeature, false)).decisions.filter((decision) => decision.status === "Accepted") : [];
+    return {
+      protocol: "empirical-sdd",
+      schemaVersion: SCHEMA_VERSION,
+      root: this.store.root,
+      feature: state.activeFeature,
+      phase: state.phase,
+      status: state.status,
+      revision: state.revision,
+      rationale: packet.rationale,
+      decisions
+    };
+  }
+  async next() {
+    const state = await this.store.loadState(!this.readOnly);
+    const criteria = state.activeFeature ? parseCriteria(await this.store.readSpec(state.activeFeature)) : [];
+    return this.packet(state, criteria);
+  }
+  async complete(input) {
+    assertCompletionInput(input);
+    const summary = input.summary.trim();
+    if (!summary)
+      throw new EmpiricalError("SUMMARY_REQUIRED", "Completion summary cannot be blank");
+    const actor = input.actor?.trim() || "agent";
+    const completed = await this.store.transaction(async (current) => {
+      if (input.revision !== current.revision) {
+        throw new EmpiricalError("STALE_REVISION", `Expected revision ${input.revision}, but the project is at ${current.revision}`);
+      }
+      if (!current.activeFeature || current.phase === "idle" || current.phase === "done") {
+        throw new EmpiricalError("NO_ACTIVE_PHASE", "There is no active phase to complete");
+      }
+      if (current.phase === "archive") {
+        throw new EmpiricalError("ARCHIVE_REQUIRED", "Use empirical archive for the reviewed revision");
+      }
+      if (current.status === "blocked") {
+        throw new EmpiricalError("WORKFLOW_BLOCKED", "Resolve the blocker and run empirical retry");
+      }
+      if (current.status === "awaiting_human") {
+        throw new EmpiricalError("AWAITING_HUMAN", "Run empirical retry after the decision is provided");
+      }
+      const specBefore = await this.store.readSpec(current.activeFeature);
+      const specBeforeDigest = digest(specBefore);
+      if (current.specDigest && current.specDigest !== specBeforeDigest && current.phase !== "shape" && current.phase !== "specify") {
+        throw new EmpiricalError("SPEC_CHANGED", "The specification changed after it was approved; restore it or start a new feature");
+      }
+      await this.assertCapabilityDeltasUnchanged(current);
+      const criteria = parseCriteria(specBefore);
+      const config = await this.store.loadConfig();
+      let approvedDeltaDigest = null;
+      if (input.outcome === "passed") {
+        approvedDeltaDigest = await this.validatePhasePass(current, input, criteria, config);
+      }
+      const state = structuredClone(current);
+      state.specDigest = specBeforeDigest;
+      if (input.outcome === "awaiting_human") {
+        state.status = "awaiting_human";
+        state.message = summary;
+      } else if (input.outcome === "blocked") {
+        state.status = "blocked";
+        state.message = summary;
+      } else if (input.outcome === "failed") {
+        routeFailure(state, summary, config.maxRepairAttempts);
+      } else {
+        if (current.phase === "specify" && current.capabilityArchiveRequired) {
+          state.capabilityDeltaDigest = approvedDeltaDigest;
+        }
+        if (state.phase === "implement")
+          state.implementationActor = actor;
+        if (input.evidence?.length)
+          state.evidence.push(...input.evidence);
+        state.phase = followingPhase(state.profile, state.phase);
+        state.status = state.phase === "done" ? "done" : "waiting";
+        state.message = summary;
+        if (state.phase === "done")
+          state.repairAttempts = 0;
+      }
+      return {
+        actor,
+        summary,
+        state,
+        value: specBefore,
+        validate: async () => {
+          if (await this.store.readSpec(current.activeFeature) !== specBefore) {
+            throw new EmpiricalError("SPEC_CHANGED", "The specification changed during completion; read the latest action and retry");
+          }
+          if (approvedDeltaDigest && await capabilityDeltaDigest(this.store, current.activeFeature) !== approvedDeltaDigest) {
+            throw new EmpiricalError("DELTA_CHANGED", "Capability deltas changed during completion; read the latest action and retry");
+          }
+        }
+      };
+    });
+    return this.packet(completed.state, parseCriteria(completed.value));
+  }
+  async archive(expectedRevision, actor = "agent") {
+    const current = await this.store.loadState();
+    if (!current.activeFeature)
+      throw new EmpiricalError("NO_ACTIVE_PHASE", "There is no feature to archive");
+    if (current.phase === "done" && current.status === "done" && current.profile === "complex" && current.revision === expectedRevision + 1 && current.message?.startsWith("Archived")) {
+      return {
+        action: await this.next(),
+        report: {
+          feature: current.activeFeature,
+          capabilities: [],
+          added: 0,
+          modified: 0,
+          removed: 0,
+          converged: true
+        }
+      };
+    }
+    if (current.phase === "done" && current.status === "done") {
+      throw new EmpiricalError("STALE_REVISION", `Archive revision ${expectedRevision} does not identify the latest completed archive`);
+    }
+    if (current.phase !== "archive" || current.status !== "waiting") {
+      throw new EmpiricalError("ARCHIVE_NOT_READY", "Complex work must pass review before archive");
+    }
+    if (current.revision !== expectedRevision) {
+      throw new EmpiricalError("STALE_REVISION", `Expected revision ${expectedRevision}, but the project is at ${current.revision}`);
+    }
+    return this.store.withResourceLock("capabilities", async () => {
+      await this.assertCapabilityDeltasUnchanged(current);
+      const deltas = await loadCapabilityDeltas(this.store, current.activeFeature);
+      const plan = deltas.length > 0 ? await planCapabilityArchive(this.store, current.activeFeature) : null;
+      if (!plan && current.capabilityArchiveRequired) {
+        throw new EmpiricalError("DELTA_REQUIRED", `Complex change ${current.activeFeature} has no capability deltas`);
+      }
+      const archived = await this.store.transaction(async (latest) => {
+        if (latest.revision !== expectedRevision) {
+          throw new EmpiricalError("STALE_REVISION", `Expected revision ${expectedRevision}, but the project is at ${latest.revision}`);
+        }
+        if (latest.phase !== "archive" || latest.status !== "waiting") {
+          throw new EmpiricalError("ARCHIVE_NOT_READY", "Complex work must pass review before archive");
+        }
+        const state = structuredClone(latest);
+        state.phase = "done";
+        state.status = "done";
+        state.message = plan ? `Archived capability changes: ${plan.report.capabilities.join(", ")}` : "Archived legacy change without capability deltas";
+        state.repairAttempts = 0;
+        return {
+          actor: actor.trim() || "agent",
+          summary: state.message,
+          state,
+          value: latest.activeFeature,
+          ...plan ? { effect: plan.commit } : {}
+        };
+      });
+      return {
+        action: await this.packet(archived.state, parseCriteria(await this.store.readSpec(archived.value))),
+        report: {
+          feature: archived.value,
+          capabilities: plan?.report.capabilities ?? [],
+          added: plan?.report.added ?? 0,
+          modified: plan?.report.modified ?? 0,
+          removed: plan?.report.removed ?? 0,
+          converged: false
+        }
+      };
+    });
+  }
+  async retry(expectedRevision, actor = "human") {
+    const current = await this.store.loadState();
+    if (!["blocked", "awaiting_human"].includes(current.status)) {
+      throw new EmpiricalError("NOT_PAUSED", "The workflow is not blocked or awaiting human input");
+    }
+    const state = await this.store.transition(expectedRevision, actor, "Resumed workflow", (state2) => ({
+      ...state2,
+      status: "waiting",
+      message: null
+    }));
+    const criteria = state.activeFeature ? parseCriteria(await this.store.readSpec(state.activeFeature)) : [];
+    return this.packet(state, criteria);
+  }
+  async verify() {
+    const state = await this.store.loadState(!this.readOnly);
+    if (!state.activeFeature) {
+      return { valid: false, phase: state.phase, criteria: 0, missing: ["No active feature"] };
+    }
+    const spec = await this.store.readSpec(state.activeFeature);
+    const criteria = parseCriteria(spec);
+    const config = await this.store.loadConfig();
+    const missing = validateEvidence(criteria, state.evidence, config, state.phase === "review" || state.phase === "archive" || state.phase === "done");
+    if (state.specDigest && state.specDigest !== digest(spec)) {
+      missing.push("Specification changed after the last completed revision");
+    }
+    if (state.capabilityArchiveRequired && state.capabilityDeltaDigest) {
+      try {
+        if (await capabilityDeltaDigest(this.store, state.activeFeature) !== state.capabilityDeltaDigest) {
+          missing.push("Capability deltas changed after Specify approval");
+        }
+      } catch {
+        missing.push("Capability deltas are malformed or unreadable after Specify approval");
+      }
+    }
+    for (const record of state.evidence) {
+      if (record.kind === "screenshot" && record.passed && record.artifact && !await isFile(join5(this.store.root, record.artifact))) {
+        missing.push(`Screenshot artifact does not exist: ${record.artifact}`);
+      }
+    }
+    return { valid: missing.length === 0, phase: state.phase, criteria: criteria.length, missing };
+  }
+  async integrations() {
+    return installProjectIntegrations(this.store.root);
+  }
+  async migrate() {
+    const migration = await new ProjectStore(this.store.root).migrateSchema();
+    return {
+      ...migration,
+      version: PRODUCT_VERSION,
+      schemaVersion: SCHEMA_VERSION
+    };
+  }
+  async doctor() {
+    const state = await this.store.loadState(!this.readOnly);
+    const config = await this.store.loadConfig();
+    return {
+      ok: true,
+      version: PRODUCT_VERSION,
+      schemaVersion: SCHEMA_VERSION,
+      root: this.store.root,
+      state,
+      config,
+      activeFeature: await new ProjectStore(this.store.root).activeFeature(!this.readOnly),
+      policy: await this.store.loadPolicy(),
+      capabilities: await this.capabilities(),
+      runtime: "node",
+      bunUsedForDevelopment: true,
+      mcpCommand: "empirical mcp",
+      canonicalStore: ".empirical"
+    };
+  }
+  async validatePhasePass(state, input, criteria, config) {
+    let approvedDeltaDigest = null;
+    if ((state.phase === "shape" || state.phase === "specify") && criteria.length === 0) {
+      throw new EmpiricalError("CRITERIA_REQUIRED", `Add at least one '- [ ] [AC-1] observable behavior' to ${relativeSpec(state.activeFeature)}`);
+    }
+    if (state.phase === "specify" && state.profile === "complex" && state.capabilityArchiveRequired) {
+      const report = await validateFeatureDeltas(this.store, state.activeFeature);
+      if (!report.valid) {
+        throw new EmpiricalError("DELTA_REQUIRED", `Capability deltas are incomplete: ${report.issues.join("; ")}`);
+      }
+      approvedDeltaDigest = report.digest;
+    }
+    if (state.phase === "design") {
+      await requireArtifact(this.store.specDirectory(state.activeFeature), "design.md");
+      if (config.decisions.complexRecords === "required" && state.profile === "complex") {
+        await requireValidDecisions(this.store, state.activeFeature);
+      }
+    }
+    if (state.phase === "plan") {
+      await requireArtifact(this.store.specDirectory(state.activeFeature), "plan.md");
+    }
+    if (state.phase === "verify") {
+      const evidence = input.evidence ?? [];
+      const missing = validateEvidence(criteria, evidence, config, false);
+      if (missing.length > 0) {
+        throw new EmpiricalError("EVIDENCE_REQUIRED", `Verification is incomplete: ${missing.join("; ")}`);
+      }
+      await validateEvidenceArtifacts(this.store.root, evidence);
+    }
+    if (state.phase === "review" && config.evidence.codeReview) {
+      if (config.decisions.complexRecords === "required" && state.profile === "complex") {
+        await requireValidDecisions(this.store, state.activeFeature);
+      }
+      const review = input.evidence?.some((record) => record.kind === "review" && record.passed);
+      if (!review) {
+        throw new EmpiricalError("REVIEW_REQUIRED", "Review completion needs passing review evidence");
+      }
+    }
+    if (state.profile === "fast" && state.phase === "implement") {
+      if (criteria.length === 0) {
+        throw new EmpiricalError("CRITERIA_REQUIRED", `Add at least one '- [ ] [AC-1] observable behavior' to ${relativeSpec(state.activeFeature)}`);
+      }
+      const evidence = input.evidence ?? [];
+      const missing = validateEvidence(criteria, evidence, config, true);
+      if (missing.length > 0) {
+        throw new EmpiricalError("EVIDENCE_REQUIRED", `Fast completion is incomplete: ${missing.join("; ")}`);
+      }
+      await validateEvidenceArtifacts(this.store.root, evidence);
+    }
+    return approvedDeltaDigest;
+  }
+  async assertCapabilityDeltasUnchanged(state) {
+    if (!state.capabilityArchiveRequired || !state.capabilityDeltaDigest || !state.activeFeature)
+      return;
+    try {
+      if (await capabilityDeltaDigest(this.store, state.activeFeature) === state.capabilityDeltaDigest)
+        return;
+    } catch {}
+    throw new EmpiricalError("DELTA_CHANGED", "Capability deltas changed after Specify approval; restore the approved deltas before continuing");
+  }
+  async packet(state, criteria) {
+    const policy = await this.store.loadPolicy();
+    const config = await this.store.loadConfig();
+    const capabilities = await listCapabilities(this.store);
+    const artifacts = expectedArtifacts(state, config.decisions.complexRecords === "required");
+    const missingArtifacts = [];
+    for (const artifact of artifacts) {
+      if (artifact.includes("deltas/<capability>.md") && state.activeFeature) {
+        if (!(await validateFeatureDeltas(this.store, state.activeFeature)).valid)
+          missingArtifacts.push(artifact);
+      } else if (artifact.endsWith("/decisions.md") && state.activeFeature) {
+        if (!(await validateDecisions(this.store, state.activeFeature, state.phase === "design" || state.phase === "review")).valid) {
+          missingArtifacts.push(artifact);
+        }
+      } else if (artifact.includes("<capability>")) {
+        missingArtifacts.push(artifact);
+      } else if (!await isFile(join5(this.store.root, artifact))) {
+        missingArtifacts.push(artifact);
+      }
+    }
+    return actionPacket(this.store.root, state, criteria, policy, capabilities.map((capability) => capability.path), artifacts, missingArtifacts);
+  }
+}
+function parseCriteria(markdown) {
+  const criteria = [];
+  let inComment = false;
+  let activeCriterion = null;
+  for (const line of markdown.split(/\r?\n/)) {
+    if (line.includes("<!--")) {
+      inComment = true;
+      activeCriterion = null;
+    }
+    if (inComment) {
+      if (line.includes("-->"))
+        inComment = false;
+      continue;
+    }
+    const match = /^\s*-\s*\[([ xX])\]\s*\[([^\]]+)\]\s*(.+?)\s*$/.exec(line);
+    if (match?.[2] && match[3]) {
+      const id = match[2].trim();
+      const text = match[3].trim();
+      activeCriterion = {
+        id,
+        text,
+        ui: /\[UI\]/i.test(text),
+        checked: match[1]?.toLowerCase() === "x"
+      };
+      criteria.push(activeCriterion);
+      continue;
+    }
+    if (activeCriterion && /^\s{2,}\S/.test(line)) {
+      activeCriterion.text = `${activeCriterion.text} ${line.trim()}`;
+      activeCriterion.ui = /\[UI\]/i.test(activeCriterion.text);
+      continue;
+    }
+    activeCriterion = null;
+  }
+  return criteria;
+}
+function defaultConfig(profile, legacySource, options = {}) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    profile,
+    maxRepairAttempts: 2,
+    evidence: {
+      required: true,
+      browserForUi: true,
+      screenshotForUi: true,
+      codeReview: true
+    },
+    isolation: {
+      mode: options.isolation?.mode ?? "ask",
+      baseBranch: options.isolation?.baseBranch ?? "auto",
+      worktreePath: options.isolation?.worktreePath ?? "../{repo}-{feature}",
+      branchPattern: options.isolation?.branchPattern ?? "{type}/{feature}"
+    },
+    decisions: {
+      complexRecords: options.decisions?.complexRecords ?? "required"
+    },
+    setupComplete: options.setupComplete ?? true,
+    legacySource
+  };
+}
+function initialState(profile) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    revision: 0,
+    activeFeature: null,
+    request: null,
+    profile,
+    phase: "idle",
+    status: "idle",
+    repairAttempts: 0,
+    message: null,
+    implementationActor: null,
+    specDigest: null,
+    capabilityArchiveRequired: false,
+    capabilityDeltaDigest: null,
+    evidence: [],
+    updatedAt: new Date().toISOString()
+  };
+}
+function renderSpec(title2, request) {
+  return `# ${title2}
+
+## Request
+
+${renderRequest(request)}
+
+## Goal
+
+Describe the observable result.
+
+## Acceptance Criteria
+
+<!-- Replace this comment with observable criteria such as:
+- [ ] [AC-1] The user can complete the intended action.
+- [ ] [AC-UI-1] [UI] The result is visible in the browser.
+-->
+
+## Scope
+
+## Non-goals
+
+## Verification
+
+## Capability Deltas
+
+Create one or more files under deltas/<capability>.md using ADDED, MODIFIED, or
+REMOVED Requirements sections, named Requirement blocks, and concrete Scenario
+examples. These merge into living specifications
+after verification and review.
+`;
+}
+function renderFastSpec(title2, request) {
+  const criterion = request.replace(/<!--/g, "&lt;!--").replace(/-->/g, "--&gt;").replace(/\s+/g, " ").trim();
+  return `# ${title2}
+
+## Request
+
+${renderRequest(request)}
+
+## Goal
+
+${criterion}
+
+## Acceptance Criteria
+
+- [ ] [AC-1] ${criterion}
+
+## Scope
+
+Small, localized, and reversible changes required by the request.
+
+## Non-goals
+
+Unrequested behavior or broader architectural changes.
+
+## Verification
+
+Run the smallest real check that proves AC-1 and inspect the resulting diff.
+`;
+}
+function renderRequest(request) {
+  return request.replace(/<!--/g, "&lt;!--").replace(/-->/g, "--&gt;").split(/\r?\n/).map((line) => `> ${line}`).join(`
+`);
+}
+function actionPacket(root, state, criteria, policy, capabilityContext, artifacts, missingArtifacts) {
+  const evidence = requiredEvidence(state, criteria);
+  const completionAvailable = state.status === "waiting" && state.phase !== "idle" && state.phase !== "done";
+  const fastCliEvidence = state.profile === "fast" && evidence.length === 2 && evidence.includes("test") && evidence.includes("review") ? ' --test "<test result>" --review "<diff review>"' : null;
+  const archive = state.phase === "archive";
+  return {
+    kind: "action",
+    protocol: "empirical-sdd",
+    schemaVersion: SCHEMA_VERSION,
+    root,
+    feature: state.activeFeature,
+    request: state.request,
+    profile: state.profile,
+    phase: state.phase,
+    status: state.status,
+    revision: state.revision,
+    instructions: instructionsFor(state, policy),
+    rationale: rationaleFor(state, artifacts, missingArtifacts, evidence),
+    acceptanceCriteria: criteria,
+    requiredEvidence: evidence,
+    artifacts,
+    projectContext: policy.context,
+    capabilityContext,
+    completion: {
+      available: completionAvailable,
+      mcpTool: archive ? "empirical_archive" : "empirical_complete",
+      cli: completionAvailable ? archive ? `empirical archive --revision ${state.revision}` : `empirical complete --revision ${state.revision} --outcome passed --summary "<what you did>"${fastCliEvidence ?? (evidence.length > 0 ? " --evidence <evidence.json>" : "")}` : "",
+      requiredFields: completionAvailable ? archive ? ["revision"] : ["revision", "outcome", "summary", ...evidence.length > 0 ? ["evidence"] : []] : []
+    }
+  };
+}
+function rationaleFor(state, artifacts, missingArtifacts, evidence) {
+  const currentState = `${state.phase}/${state.status} at revision ${state.revision}`;
+  const nextAction = state.status === "blocked" || state.status === "awaiting_human" ? "Resolve the stated gate, then retry the exact revision" : state.phase === "idle" ? "Start an approved Fast or Complex feature" : state.phase === "done" ? "Report completion" : state.phase === "archive" ? "Archive the reviewed capability deltas" : `Complete ${state.phase} at revision ${state.revision}`;
+  const reason = state.phase === "idle" ? "No non-terminal feature state exists in this checkout." : state.phase === "done" ? "All workflow gates have completed." : state.status === "blocked" || state.status === "awaiting_human" ? state.message ?? "The workflow state machine has an unresolved stop condition." : `The ${state.profile} state machine advances from ${state.phase} only after its artifacts and evidence pass.`;
+  return {
+    currentState,
+    nextAction,
+    reason,
+    requiredContext: [...artifacts, ...evidence.map((kind) => `${kind} evidence`)],
+    missingContext: [...missingArtifacts, ...evidence.map((kind) => `${kind} evidence`)],
+    gate: state.status === "blocked" || state.status === "awaiting_human" ? "stop" : "proceed"
+  };
+}
+function assertStartAction(action, request, profile, options) {
+  if (action.request?.trim() !== request) {
+    throw new EmpiricalError("FEATURE_ACTIVE", action.feature ? `Feature ${action.feature} belongs to a different request` : "The requested feature is no longer active");
+  }
+  if (profile !== action.profile) {
+    throw new EmpiricalError("PROFILE_CONFLICT", `The feature uses profile ${action.profile}, not ${profile}`);
+  }
+  if (options.id && options.id !== action.feature) {
+    throw new EmpiricalError("FEATURE_ACTIVE", `The active feature is ${action.feature ?? "none"}, not ${options.id}`);
+  }
+  return action;
+}
+function instructionsFor(state, policy) {
+  if (state.status === "blocked")
+    return appendPolicy(`Stop. Resolve this blocker before retrying: ${state.message ?? "unknown"}`, state, policy);
+  if (state.status === "awaiting_human")
+    return appendPolicy(`Stop and ask the user: ${state.message ?? "a decision is required"}`, state, policy);
+  if (state.phase === "idle")
+    return appendPolicy("No feature is active. Explore genuinely vague work first; otherwise start it with empirical_fast or empirical_complex. Use empirical loop only to resume current work.", state, policy);
+  if (state.phase === "done")
+    return appendPolicy("The feature passed verification, review, and required capability archive. Report completion; delivery is manual.", state, policy);
+  const feature = state.activeFeature ?? "current feature";
+  const instructions = {
+    shape: `Read the request, edit ${relativeSpec(feature)}, and define concise observable acceptance criteria. Do not implement yet.`,
+    specify: `Refine ${relativeSpec(feature)} into a complete contract with observable acceptance criteria, scope, non-goals, risks, and verification. Declare current-behavior changes in .empirical/specs/${feature}/deltas/<capability>.md using ADDED, MODIFIED, or REMOVED requirement blocks with scenarios.`,
+    design: `Design the solution in .empirical/specs/${feature}/design.md and maintain .empirical/specs/${feature}/decisions.md with accepted evidence, options, the chosen approach, trade-offs/risks, and verification. Record concise reviewable decisions, never private chain-of-thought.`,
+    plan: `Break the approved design into an executable plan in .empirical/specs/${feature}/plan.md.`,
+    implement: state.profile === "fast" ? "Fast lane: the packet already contains the complete generated criterion. Inspect only the relevant project files, implement in one focused pass, combine the smallest real test and diff review when practical, then run the returned completion command. Do not reread Empirical state or add redundant checks. If the work is no longer small and low-risk, report failure so Empirical can escalate it." : "Implement the current acceptance criteria. Preserve unrelated work and run focused checks while editing.",
+    verify: "Run real tests for every criterion. For [UI] criteria, use a real browser and capture a screenshot. Return structured evidence.",
+    review: `Review the implementation against every criterion, the diff, and accepted decisions in .empirical/specs/${feature}/decisions.md. Contradictions require an explicit accepted superseding entry. Return passing review evidence or route failures back to implementation.`,
+    archive: "Apply the reviewed capability deltas to the living specifications with the returned empirical_archive operation. Do not edit capability specs manually during archive."
+  };
+  return appendPolicy(instructions[state.phase], state, policy);
+}
+function appendPolicy(base, state, policy) {
+  const sections = [base];
+  if (policy.context.length > 0)
+    sections.push(`Project context:
+- ${policy.context.join(`
+- `)}`);
+  const phaseGuidance = policy.phases[state.phase] ?? [];
+  if (phaseGuidance.length > 0) {
+    sections.push(`Additional project guidance (mandatory Empirical gates still apply):
+- ${phaseGuidance.join(`
+- `)}`);
+  }
+  return sections.join(`
+
+`);
+}
+function expectedArtifacts(state, decisionsRequired) {
+  if (!state.activeFeature)
+    return [];
+  const base = `.empirical/specs/${state.activeFeature}`;
+  if (state.phase === "shape")
+    return [`${base}/spec.md`];
+  if (state.phase === "specify")
+    return [`${base}/spec.md`, `${base}/deltas/<capability>.md`];
+  if (state.phase === "design")
+    return [`${base}/design.md`, ...decisionsRequired ? [`${base}/decisions.md`] : []];
+  if (state.phase === "plan")
+    return [`${base}/plan.md`];
+  if (state.phase === "review")
+    return decisionsRequired ? [`${base}/decisions.md`] : [];
+  if (state.phase === "archive")
+    return [".empirical/capabilities/<capability>/spec.md"];
+  return [];
+}
+function requiredEvidence(state, criteria) {
+  const fast = state.profile === "fast" && state.phase === "implement";
+  if (state.phase !== "verify" && state.phase !== "review" && !fast)
+    return [];
+  const kinds = new Set;
+  if (state.phase === "verify" || fast)
+    kinds.add("test");
+  if ((state.phase === "verify" || fast) && criteria.some((criterion) => criterion.ui)) {
+    kinds.add("browser");
+    kinds.add("screenshot");
+  }
+  if (state.phase === "review" || fast)
+    kinds.add("review");
+  return [...kinds];
+}
+function validateEvidence(criteria, evidence, config, includeReview) {
+  if (!config.evidence.required)
+    return [];
+  const missing = [];
+  if (criteria.length === 0)
+    missing.push("No acceptance criteria are defined");
+  for (const criterion of criteria) {
+    const records = evidence.filter((record) => record.criterionId === criterion.id && record.passed);
+    if (!records.some((record) => record.kind === "test")) {
+      missing.push(`${criterion.id} has no passing test evidence`);
+    }
+    if (criterion.ui && config.evidence.browserForUi && !records.some((record) => record.kind === "browser")) {
+      missing.push(`${criterion.id} has no browser evidence`);
+    }
+    if (criterion.ui && config.evidence.screenshotForUi && !records.some((record) => record.kind === "screenshot" && record.artifact)) {
+      missing.push(`${criterion.id} has no screenshot artifact`);
+    }
+  }
+  if (includeReview && config.evidence.codeReview && !evidence.some((record) => record.kind === "review" && record.passed)) {
+    missing.push("No passing code review evidence");
+  }
+  return missing;
+}
+function routeFailure(state, summary, maxRepairAttempts) {
+  state.message = summary;
+  if (state.profile === "fast" && state.phase === "implement") {
+    state.profile = "complex";
+    state.phase = "specify";
+    state.capabilityArchiveRequired = true;
+    state.capabilityDeltaDigest = null;
+    state.repairAttempts = 0;
+    state.evidence = [];
+    state.status = "waiting";
+    return state;
+  }
+  if (state.phase === "verify" || state.phase === "review") {
+    state.repairAttempts += 1;
+    state.evidence = [];
+    if (state.repairAttempts > maxRepairAttempts) {
+      state.status = "blocked";
+      return state;
+    }
+    state.phase = "implement";
+    state.status = "waiting";
+    return state;
+  }
+  state.status = "waiting";
+  return state;
+}
+function firstPhase(profile) {
+  if (profile === "fast")
+    return "implement";
+  return profile === "quick" ? "shape" : "specify";
+}
+function followingPhase(profile, phase) {
+  const sequence = profile === "fast" ? FAST_PHASES : profile === "quick" ? QUICK_PHASES : COMPLEX_PHASES;
+  const index = sequence.indexOf(phase);
+  if (index < 0)
+    throw new EmpiricalError("INVALID_PHASE", `Phase ${phase} is not valid for ${profile}`);
+  return sequence[index + 1] ?? "done";
+}
+function mapLegacyPhase(value, profile) {
+  const phase = value?.toLowerCase() ?? "";
+  if (/done|complete|ready/.test(phase))
+    return "done";
+  if (profile === "fast")
+    return "implement";
+  if (/review/.test(phase))
+    return "review";
+  if (/test|verify|qa/.test(phase))
+    return "verify";
+  if (/develop|implement|dev/.test(phase))
+    return "implement";
+  if (profile === "quick")
+    return "shape";
+  if (/plan/.test(phase))
+    return "plan";
+  if (/architect|design/.test(phase))
+    return "design";
+  return "specify";
+}
+function legacyField(contents, field) {
+  const match = new RegExp(`^\\s*${field}\\s*:\\s*([^#\\r\\n]+)`, "im").exec(contents);
+  const value = match?.[1]?.trim();
+  if (!value || /<none|none|null/i.test(value))
+    return null;
+  return value.replace(/^['"]|['"]$/g, "");
+}
+function titleFromFeature(feature) {
+  const withoutNumber = feature.replace(/^\d+-/, "");
+  return withoutNumber.split(/[-_]/).filter(Boolean).map((word) => `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`).join(" ") || basename2(feature);
+}
+function relativeSpec(feature) {
+  return `.empirical/specs/${feature ?? "<feature>"}/spec.md`;
+}
+async function requireArtifact(directory, name) {
+  const path = join5(directory, name);
+  if (!await isFile(path) || (await readFile5(path, "utf8")).trim().length === 0) {
+    throw new EmpiricalError("ARTIFACT_REQUIRED", `Create the non-empty artifact ${path}`);
+  }
+}
+async function validateEvidenceArtifacts(root, evidence) {
+  for (const record of evidence) {
+    if (record.kind === "screenshot" && record.passed && record.artifact && !await isFile(join5(root, record.artifact))) {
+      throw new EmpiricalError("EVIDENCE_REQUIRED", `Screenshot artifact does not exist: ${record.artifact}`);
+    }
+  }
+}
+function digest(contents) {
+  return createHash3("sha256").update(contents).digest("hex");
+}
+function emptyIntegrationReport() {
+  return { scope: "project", created: [], updated: [], preserved: [], entrypoints: [] };
+}
+function assertWorkflow(profile) {
+  if (profile !== "fast" && profile !== "complex") {
+    throw new EmpiricalError("INVALID_PROFILE", `Workflow must be fast or complex, not '${profile}'`);
+  }
+}
+function assertCompletionInput(input) {
+  if (!Number.isSafeInteger(input.revision) || input.revision < 0) {
+    throw new EmpiricalError("INVALID_REVISION", "Completion revision must be a non-negative integer");
+  }
+  if (!"passed failed awaiting_human blocked".split(" ").includes(input.outcome)) {
+    throw new EmpiricalError("INVALID_OUTCOME", `Unsupported completion outcome '${String(input.outcome)}'`);
+  }
+  for (const record of input.evidence ?? []) {
+    if (!record.criterionId?.trim() || !record.summary?.trim() || typeof record.passed !== "boolean") {
+      throw new EmpiricalError("INVALID_EVIDENCE", "Evidence needs criterionId, summary, kind, and passed");
+    }
+    if (!"test browser screenshot review human".split(" ").includes(record.kind)) {
+      throw new EmpiricalError("INVALID_EVIDENCE", `Unsupported evidence kind '${String(record.kind)}'`);
+    }
+    if (record.artifact && (record.artifact.startsWith("/") || /^[A-Za-z]:[\\/]/.test(record.artifact) || record.artifact.split(/[\\/]/).includes(".."))) {
+      throw new EmpiricalError("INVALID_EVIDENCE", "Evidence artifact paths must stay inside the repository");
+    }
+  }
+}
+export {
+  validateFeatureDeltas,
+  planCapabilityArchive,
+  parseCriteria,
+  parseCapabilityDelta,
+  loadCapabilityDeltas,
+  listCapabilities,
+  installProjectIntegrations,
+  installGlobalAgentSkills,
+  discoverProject,
+  capabilityDeltaDigest,
+  SCHEMA_VERSION,
+  ProjectStore,
+  PRODUCT_VERSION,
+  POLICY_SCHEMA_VERSION,
+  EmpiricalProject,
+  EmpiricalError
+};