@supporterino/ai-factory 0.2.0 → 0.3.1

package/dist/cli.js

@@ -14682,7 +14682,7 @@ var require_dist = __commonJS(function(exports, module) {
 });
 
 // src/cli/main.ts
-import { resolve as resolve5 } from "node:path";
+import { resolve as resolve6 } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 // src/cli/exit-codes.ts
@@ -14743,7 +14743,7 @@ class TransientError extends Error {
 }
 
 // src/version.ts
-var FACTORY_VERSION = "0.2.0";
+var FACTORY_VERSION = "0.3.1";
 var PACKAGE_NAME = "@supporterino/ai-factory";
 var runVersion = (version) => `npx ${PACKAGE_NAME}@${version}`;
 
@@ -22304,13 +22304,49 @@ var PONYTAIL = {
 };
 
 // src/config/schema.ts
-var CONFIG_SCHEMA_VERSION = 2;
+var CONFIG_SCHEMA_VERSION = 3;
 var CONFIG_FILE = "factory.config.jsonc";
-var LANGUAGES = ["typescript", "react", "python", "go", "rust", "helm", "tauri"];
+var LANGUAGES = [
+  "typescript",
+  "react",
+  "python",
+  "go",
+  "rust",
+  "helm",
+  "tauri",
+  "swift"
+];
 var Language = _enum(LANGUAGES);
+var ROLES = [
+  "orchestrator",
+  "architect",
+  "reviewer",
+  "contractReviewer",
+  "implementer",
+  "tester",
+  "explorer"
+];
+var AGENT_PHASES = [
+  "orchestrator",
+  "architect",
+  "explorer",
+  "reviewer",
+  "contract-reviewer",
+  "tester",
+  "implementer"
+];
 var GATE_TYPES = ["format", "lint", "types", "test", "testAffected"];
 var GateType = _enum(GATE_TYPES);
-var CONTRACT_KINDS = ["openapi", "proto", "json-schema", "helm-values"];
+var CONTRACT_KINDS = [
+  "openapi",
+  "proto",
+  "json-schema",
+  "helm-values",
+  "generated",
+  "crd",
+  "ipc",
+  "custom"
+];
 var ContractKind = _enum(CONTRACT_KINDS);
 var RepoName = string2().regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits and dashes, starting alphanumeric");
 var RelPath = string2().min(1).refine((p) => p === "." || !p.startsWith("/") && !p.includes("\\") && !p.split("/").includes(".."), "must be '.' or a relative POSIX path inside the workspace");
@@ -22330,6 +22366,7 @@ var RepoConfig = strictObject({
 var repoLanguages = (repo) => [
   ...new Set([...repo.languages, ...(repo.subPaths ?? []).flatMap((s) => s.languages)])
 ];
+var ModelByRole = partialRecord(_enum(ROLES), ModelId);
 var ModelsConfig = strictObject({
   orchestrator: ModelId,
   architect: ModelId,
@@ -22337,7 +22374,54 @@ var ModelsConfig = strictObject({
   contractReviewer: ModelId.optional(),
   implementer: ModelId,
   tester: ModelId,
-  explorer: ModelId
+  explorer: ModelId,
+  roles: ModelByRole.default({}),
+  repos: record(string2(), ModelByRole).default({}),
+  agents: record(string2(), ModelId).default({}),
+  fallback: array(ModelId).default([])
+});
+var InstructionsConfig = strictObject({
+  workspace: array(RelPath).default([]),
+  repos: record(string2(), array(RelPath)).default({})
+});
+var SkillsConfig = strictObject({
+  sources: array(RelPath).default([".opencode/skills"]),
+  roles: partialRecord(_enum(ROLES), array(string2().min(1))).default({}),
+  repos: record(string2(), array(string2().min(1))).default({})
+});
+var McpConfig = strictObject({
+  roles: partialRecord(_enum(ROLES), array(string2().min(1))).default({})
+});
+var CustomAgent = strictObject({
+  id: string2().regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits and dashes, starting alphanumeric"),
+  phase: _enum(AGENT_PHASES),
+  description: string2().min(1).default("custom ai-factory agent"),
+  model: ModelId.optional(),
+  mode: _enum(["primary", "subagent", "all"]).default("subagent"),
+  prompt: string2().min(1).optional(),
+  promptFile: RelPath.optional(),
+  skills: array(string2().min(1)).default([]),
+  edits: array(string2().min(1)).default([]),
+  shell: array(string2().min(1)).default([]),
+  web: boolean2().default(false),
+  mcp: array(string2().min(1)).default([])
+});
+var RoutingRule = strictObject({
+  paths: array(string2().min(1)).min(1),
+  agent: string2().min(1)
+});
+var ExtraGate = strictObject({
+  name: string2().regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits and dashes, starting alphanumeric"),
+  type: _enum(GATE_TYPES).default("test"),
+  phases: array(_enum(["task", "full"])).default(["task", "full"]),
+  when: strictObject({ changed: array(string2().min(1)).default([]) }).default({ changed: [] }),
+  cwd: RelPath.default("."),
+  command: string2().min(1),
+  env: record(string2(), string2()).default({}),
+  setup: string2().min(1).optional(),
+  outputs: array(RelPath).default([]),
+  checkOnly: boolean2().default(true),
+  timeoutMs: int().min(1).optional()
 });
 var GateCommands = partialRecord(GateType, string2().min(1));
 var GatesConfig = strictObject({
@@ -22349,13 +22433,16 @@ var GatesConfig = strictObject({
     test: "test",
     testAffected: "test:affected"
   }),
-  overrides: record(string2(), GateCommands).default({})
+  overrides: record(string2(), GateCommands).default({}),
+  extra: array(ExtraGate).default([])
 });
 var ContractConfig = strictObject({
   kind: ContractKind,
   provider: RepoName,
   path: RelPath,
   consumers: array(RepoName),
+  command: string2().min(1).optional(),
+  outputs: array(RelPath).optional(),
   allowBreaking: boolean2().optional(),
   validate: record(RepoName, string2().min(1)).optional()
 });
@@ -22400,12 +22487,32 @@ var SecurityConfig = strictObject({
 var GraphConfig = strictObject({
   exclude: array(string2().min(1)).default([...DEFAULT_GRAPH_EXCLUDE])
 });
+var CommitsConfig = strictObject({
+  style: _enum(["conventional", "gitmoji"]).default("conventional"),
+  scopes: boolean2().default(false)
+});
+var QuickConfig = strictObject({
+  enabled: boolean2().default(true),
+  branchPrefix: string2().min(1).default("task/")
+});
+var WorkflowConfig = strictObject({
+  refine: boolean2().default(true),
+  quick: QuickConfig.prefault({})
+});
+var ReleaseConfig = strictObject({
+  detect: boolean2().default(true)
+});
 var FactoryConfigBase = strictObject({
   $schema: string2().optional(),
-  schemaVersion: literal(CONFIG_SCHEMA_VERSION),
+  schemaVersion: union([literal(2), literal(CONFIG_SCHEMA_VERSION)]),
   layout: _enum(["single", "submodules"]),
   repos: array(RepoConfig).min(1),
   models: ModelsConfig,
+  instructions: InstructionsConfig.prefault({}),
+  skills: SkillsConfig.prefault({}),
+  mcp: McpConfig.prefault({}),
+  agents: array(CustomAgent).default([]),
+  routing: array(RoutingRule).default([]),
   gates: GatesConfig.prefault({}),
   contracts: array(ContractConfig).default([]),
   parallel: ParallelConfig.prefault({}),
@@ -22414,6 +22521,9 @@ var FactoryConfigBase = strictObject({
   logs: LogsConfig.prefault({}),
   graph: GraphConfig.prefault({}),
   security: SecurityConfig.prefault({}),
+  commits: CommitsConfig.prefault({}),
+  workflow: WorkflowConfig.prefault({}),
+  release: ReleaseConfig.prefault({}),
   unmanaged: array(RelPath).default([])
 });
 var FactoryConfig = FactoryConfigBase.superRefine((cfg, ctx) => {
@@ -22465,17 +22575,126 @@ var FactoryConfig = FactoryConfigBase.superRefine((cfg, ctx) => {
         issue(["contracts", i, "consumers", j], "a provider cannot consume its own contract");
       }
     });
+    if (["generated", "crd", "ipc", "custom"].includes(contract.kind) && contract.command === undefined) {
+      issue(["contracts", i, "command"], `${contract.kind} contracts need a command`);
+    }
   });
   for (const repoName of Object.keys(cfg.gates.overrides)) {
     if (!codeRepos.has(repoName)) {
       issue(["gates", "overrides", repoName], `unknown code repo "${repoName}"`);
     }
   }
+  for (const key of ["instructions", "skills"]) {
+    for (const repoName of Object.keys(cfg[key].repos)) {
+      if (!codeRepos.has(repoName)) {
+        issue([key, "repos", repoName], `unknown code repo "${repoName}"`);
+      }
+    }
+  }
+  for (const repoName of Object.keys(cfg.models.repos)) {
+    if (!codeRepos.has(repoName)) {
+      issue(["models", "repos", repoName], `unknown code repo "${repoName}"`);
+    }
+  }
+  const agentIds = new Set;
+  for (const [i, agent] of cfg.agents.entries()) {
+    if (agentIds.has(agent.id))
+      issue(["agents", i, "id"], `duplicate agent id "${agent.id}"`);
+    if (agent.prompt === undefined && agent.promptFile === undefined) {
+      issue(["agents", i], "a custom agent needs `prompt` or `promptFile`");
+    }
+    if (agent.prompt !== undefined && agent.promptFile !== undefined) {
+      issue(["agents", i], "use either `prompt` or `promptFile`, not both");
+    }
+    agentIds.add(agent.id);
+  }
+  const builtin = new Set([
+    "orchestrator",
+    "architect",
+    "explorer",
+    "reviewer",
+    "contract-reviewer",
+    "tester",
+    ...cfg.repos.filter((r) => r.role === "code").map((r) => `implementer-${r.name}`)
+  ]);
+  for (const [i, agent] of cfg.agents.entries()) {
+    if (builtin.has(agent.id)) {
+      issue(["agents", i, "id"], `"${agent.id}" is a built-in agent id; choose another id`);
+    }
+  }
+  for (const [i, rule] of cfg.routing.entries()) {
+    if (!agentIds.has(rule.agent) && !builtin.has(rule.agent)) {
+      issue(["routing", i, "agent"], `unknown agent "${rule.agent}"`);
+    }
+  }
+  for (const agentId of Object.keys(cfg.models.agents)) {
+    if (!agentIds.has(agentId)) {
+      issue(["models", "agents", agentId], `unknown custom agent "${agentId}"`);
+    }
+  }
 });
-function modelFor(config, role) {
-  if (role === "contractReviewer")
-    return config.models.contractReviewer ?? config.models.reviewer;
-  return config.models[role];
+function modelFor(config, role, options = {}) {
+  const flat = role === "contractReviewer" ? config.models.contractReviewer ?? config.models.reviewer : config.models[role];
+  if (options.agent !== undefined) {
+    const agent = config.models.agents[options.agent];
+    if (agent !== undefined)
+      return agent;
+  }
+  if (options.repo !== undefined) {
+    const repo = config.models.repos[options.repo]?.[role];
+    if (repo !== undefined)
+      return repo;
+  }
+  return config.models.roles[role] ?? flat;
+}
+function modelEntries(config) {
+  const out = [];
+  for (const role of ROLES) {
+    if (role === "contractReviewer")
+      continue;
+    const model = config.models[role];
+    if (typeof model === "string")
+      out.push([role, model]);
+  }
+  if (config.models.contractReviewer !== undefined)
+    out.push(["contractReviewer", config.models.contractReviewer]);
+  for (const [role, model] of Object.entries(config.models.roles)) {
+    if (model !== undefined)
+      out.push([`${role} (role)`, model]);
+  }
+  for (const [repo, byRole] of Object.entries(config.models.repos)) {
+    for (const [role, model] of Object.entries(byRole)) {
+      if (model !== undefined)
+        out.push([`${role} (${repo})`, model]);
+    }
+  }
+  for (const [agent, model] of Object.entries(config.models.agents)) {
+    out.push([`agent ${agent}`, model]);
+  }
+  return out;
+}
+function allModels(config) {
+  const out = new Set;
+  for (const role of ROLES) {
+    const flat = config.models[role];
+    if (typeof flat === "string")
+      out.add(flat);
+  }
+  if (config.models.contractReviewer !== undefined)
+    out.add(config.models.contractReviewer);
+  for (const model of Object.values(config.models.roles))
+    if (model !== undefined)
+      out.add(model);
+  for (const byRole of Object.values(config.models.repos)) {
+    for (const model of Object.values(byRole))
+      if (model !== undefined)
+        out.add(model);
+  }
+  for (const model of Object.values(config.models.agents))
+    out.add(model);
+  for (const model of config.models.fallback)
+    out.add(model);
+  return [...out].sort();
 }
 
 // src/config/load.ts
@@ -22515,9 +22734,12 @@ function parseConfigText(text, file) {
     throw new ConfigError(`${file} is not valid JSONC`, errors);
   }
   const version = value?.schemaVersion;
-  if (typeof version === "number" && version < CONFIG_SCHEMA_VERSION) {
+  if (typeof version === "number" && version < 2) {
     throw new ConfigError(`${file} uses config schemaVersion ${version}; this factory needs ${CONFIG_SCHEMA_VERSION}`, ["run `ai-factory update` to migrate it"]);
   }
+  if (typeof version === "number" && version > CONFIG_SCHEMA_VERSION) {
+    throw new ConfigError(`${file} uses config schemaVersion ${version}, newer than this factory (${CONFIG_SCHEMA_VERSION})`, ["install a newer ai-factory"]);
+  }
   const parsed = FactoryConfig.safeParse(value);
   if (!parsed.success) {
     throw new ConfigError(`${file} is invalid`, formatZodIssues(parsed.error));
@@ -23208,7 +23430,7 @@ function benchCommand(cli) {
 
 // src/cli/commands/detect.ts
 import { existsSync as existsSync13, renameSync as renameSync5, writeFileSync as writeFileSync7 } from "node:fs";
-import { join as join16 } from "node:path";
+import { join as join17 } from "node:path";
 
 // src/detect/contracts.ts
 import { readFileSync as readFileSync5 } from "node:fs";
@@ -23360,6 +23582,57 @@ function findProvided(repo) {
   const chartDirs = new Set(candidates.filter((f) => baseOf(f.path) === "Chart.yaml").map((f) => dirOf(f.path)));
   const protoDirs = [];
   const protoPackages = new Set;
+  const pkgText = read(repo.root, "package.json");
+  let scripts = {};
+  if (pkgText !== undefined) {
+    try {
+      scripts = JSON.parse(pkgText).scripts ?? {};
+    } catch {
+      scripts = {};
+    }
+  }
+  const runner = /bun\.lockb?/.test(repo.files.map((f) => f.path).join(`
+`)) ? "bun run" : "npm run";
+  for (const binding of ["src/bindings.ts", "bindings.ts"]) {
+    if (candidates.some((f) => f.path === binding) && typeof scripts["gen:bindings"] === "string") {
+      found.push({
+        kind: "ipc",
+        path: binding,
+        needles: [binding],
+        command: `${runner} gen:bindings`,
+        outputs: [binding]
+      });
+    }
+  }
+  if (candidates.some((f) => f.path === "src/routeTree.gen.ts") && typeof scripts.build === "string") {
+    found.push({
+      kind: "generated",
+      path: "src/routeTree.gen.ts",
+      needles: ["src/routeTree.gen.ts"],
+      command: `${runner} build`,
+      outputs: ["src/routeTree.gen.ts"]
+    });
+  }
+  for (const dir of ["operator/config/crd/bases", "config/crd/bases"]) {
+    if (!candidates.some((f) => f.path.startsWith(`${dir}/`)))
+      continue;
+    const taskfile = read(repo.root, "Taskfile.yml") ?? read(repo.root, "Taskfile.yaml");
+    if (taskfile !== undefined && /^ {2}manifests:/m.test(taskfile)) {
+      const root = dir.includes("/config/crd/bases") ? dir.slice(0, dir.indexOf("/config/crd/bases")) : ".";
+      const outputs = [
+        dir,
+        ...["config/rbac", "api/v1alpha1/zz_generated.deepcopy.go"].map((path) => root === "." ? path : `${root}/${path}`)
+      ].filter((path) => candidates.some((f) => f.path === path || f.path.startsWith(`${path}/`)));
+      found.push({
+        kind: "crd",
+        path: dir,
+        needles: [],
+        command: "task manifests generate",
+        outputs
+      });
+      break;
+    }
+  }
   for (const file of candidates) {
     const name = baseOf(file.path);
     if (name === "values.schema.json" && chartDirs.has(dirOf(file.path))) {
@@ -23413,7 +23686,10 @@ function detectContracts(repos) {
         kind: found.kind,
         provider: provider.name,
         path: found.path,
-        consumers: consumers.sort()
+        consumers: consumers.sort(),
+        ...found.command === undefined ? {} : { command: found.command },
+        ...found.outputs === undefined ? {} : { outputs: found.outputs },
+        ...found.validate === undefined ? {} : { validate: found.validate }
       });
     }
   }
@@ -23456,7 +23732,7 @@ function applyChanges(text, config, changes) {
 }
 
 // src/detect/workspace.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync7 } from "node:fs";
 import { basename, join as join9 } from "node:path";
 
 // src/detect/languages.ts
@@ -23605,6 +23881,62 @@ async function defaultBranchOf(dir) {
 function isInitialized(dir) {
   return existsSync6(join9(dir, ".git"));
 }
+function readScripts(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync7(join9(dir, "package.json"), "utf8"));
+    return Object.fromEntries(Object.entries(pkg.scripts ?? {}).filter((entry) => typeof entry[1] === "string"));
+  } catch {
+    return {};
+  }
+}
+function packageRunner(dir) {
+  if (existsSync6(join9(dir, "bun.lock")) || existsSync6(join9(dir, "bun.lockb")))
+    return "bun run";
+  if (existsSync6(join9(dir, "pnpm-lock.yaml")))
+    return "pnpm run";
+  if (existsSync6(join9(dir, "yarn.lock")))
+    return "yarn";
+  return "npm run";
+}
+function e2eScript(dir) {
+  const scripts = readScripts(dir);
+  const name = scripts["test:e2e"] !== undefined ? "test:e2e" : scripts.e2e !== undefined ? "e2e" : undefined;
+  return name === undefined ? undefined : `${packageRunner(dir)} ${name}`;
+}
+function taskNames(dir) {
+  for (const file of ["Taskfile.yml", "Taskfile.yaml"]) {
+    const path = join9(dir, file);
+    if (!existsSync6(path))
+      continue;
+    try {
+      const doc = $parse(readFileSync7(path, "utf8"), { logLevel: "silent" });
+      return Object.keys(doc?.tasks ?? {}).sort();
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+function readInstructions(dir) {
+  for (const file of [
+    "opencode.json",
+    "opencode.jsonc",
+    ".opencode/opencode.json",
+    ".opencode/opencode.jsonc"
+  ]) {
+    if (!existsSync6(join9(dir, file)))
+      continue;
+    try {
+      const text = readFileSync7(join9(dir, file), "utf8");
+      const value = parseJsonc(text).value;
+      const list = Array.isArray(value?.instructions) ? value.instructions : [];
+      return list.filter((v) => typeof v === "string" && !v.startsWith("/") && !v.startsWith("~") && !v.includes("://") && !v.split("/").includes(".."));
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
 function withOptional(base, subPaths, defaultBranch) {
   return {
     ...base,
@@ -23617,6 +23949,12 @@ async function detectWorkspace(root) {
   const repos = [];
   const scanned = [];
   const taken = new Set;
+  const instructions = {
+    workspace: readInstructions(root),
+    repos: {}
+  };
+  const e2e = [];
+  const tasks = [];
   const submodules = existsSync6(join9(root, ".gitmodules")) ? await readSubmodules(root) : [];
   const layout = submodules.length > 0 ? "submodules" : "single";
   if (layout === "single") {
@@ -23625,6 +23963,10 @@ async function detectWorkspace(root) {
     const name = uniqueName(repoNameFrom(root), taken);
     repos.push(withOptional({ name, path: ".", role: "code", languages, initialized: true }, subPaths, await defaultBranchOf(root)));
     scanned.push({ name, root, files });
+    const singleE2e = e2eScript(root);
+    if (singleE2e !== undefined)
+      e2e.push({ repo: name, command: singleE2e });
+    tasks.push({ repo: name, names: taskNames(root) });
     if (languages.length === 0)
       notes.push("no language markers found in the repository");
   } else {
@@ -23643,10 +23985,25 @@ async function detectWorkspace(root) {
       if (languages.length === 0)
         notes.push(`no language markers found in ${sub.path}`);
       repos.push(withOptional({ name, path: sub.path, role: "code", languages, initialized: true }, subPaths, await defaultBranchOf(dir)));
+      const inherited = readInstructions(dir);
+      if (inherited.length > 0)
+        instructions.repos[name] = inherited;
+      const repoE2e = e2eScript(dir);
+      if (repoE2e !== undefined)
+        e2e.push({ repo: name, command: repoE2e });
+      tasks.push({ repo: name, names: taskNames(dir) });
       scanned.push({ name, root: dir, files });
     }
   }
-  return { layout, repos, contracts: detectContracts(scanned), notes };
+  return {
+    layout,
+    repos,
+    contracts: detectContracts(scanned),
+    instructions,
+    e2e,
+    tasks,
+    notes
+  };
 }
 function toRepoConfig(repo) {
   const { initialized: _initialized, ...rest } = repo;
@@ -23750,7 +24107,7 @@ function formatChange(change) {
 }
 
 // src/lock/lock.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync8 } from "node:fs";
 import { join as join10 } from "node:path";
 
 // src/tools.ts
@@ -23888,7 +24245,7 @@ function readLock(root) {
     return;
   let value;
   try {
-    value = JSON.parse(readFileSync7(file, "utf8"));
+    value = JSON.parse(readFileSync8(file, "utf8"));
   } catch (err) {
     throw new ConfigError(`${LOCK_FILE} is not valid JSON`, [String(err)]);
   }
@@ -23910,7 +24267,7 @@ function ensureNotNewer(lock, allow = false) {
 
 // src/workspace/sync.ts
 import { existsSync as existsSync12, writeFileSync as writeFileSync6 } from "node:fs";
-import { join as join15 } from "node:path";
+import { join as join16 } from "node:path";
 
 // templates/addons/ponytail/.opencode/command/ponytail-review.md
 var ponytail_review_default = `---
@@ -24258,11 +24615,24 @@ var TYPE_BY_VERB = [
   [/^(bump|upgrade|pin)\b/i, "chore"],
   [/^(speed up|optimi[sz]e|cache)\b/i, "perf"]
 ];
-function conventionalSubject(title, type) {
+var GITMOJI = {
+  feat: "✨",
+  fix: "\uD83D\uDC1B",
+  test: "✅",
+  refactor: "♻️",
+  docs: "\uD83D\uDCDD",
+  chore: "\uD83D\uDD27",
+  perf: "⚡️",
+  ci: "\uD83D\uDC77",
+  build: "\uD83D\uDD27"
+};
+function conventionalSubject(title, type, options = {}) {
   const clean = title.trim().replace(/\s+/g, " ").replace(/\.$/, "");
   const kind = type ?? TYPE_BY_VERB.find(([re]) => re.test(clean))?.[1] ?? "feat";
   const lowered = clean.charAt(0).toLowerCase() + clean.slice(1);
-  return `${kind}: ${lowered}`;
+  const scope = options.scope === undefined ? "" : `(${options.scope})`;
+  const emoji = options.style === "gitmoji" ? `${GITMOJI[kind] ?? "\uD83D\uDD27"} ` : "";
+  return `${kind}${scope}: ${emoji}${lowered}`;
 }
 function message(subject, trailers) {
   const block = Object.entries(trailers).map(([k, v]) => `${k}: ${v}`);
@@ -24292,12 +24662,15 @@ async function commitPaths(dir, paths, subject, trailers = {}) {
   });
   return gitOk(["rev-parse", "HEAD"], { cwd: dir });
 }
-function commitTask(worktree, id, task, title, type) {
-  return commitAll(worktree, conventionalSubject(title, type), { "Change-Id": id, Task: task });
+function commitTask(worktree, id, task, title, type, style = {}) {
+  return commitAll(worktree, conventionalSubject(title, type, style), {
+    "Change-Id": id,
+    Task: task
+  });
 }
 
 // src/git/hooks.ts
-import { chmodSync, existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync as renameSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { chmodSync, existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync9, renameSync as renameSync3, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join12, relative as relative2 } from "node:path";
 var HOOK_MARKER = "# ai-factory-hook v1";
 var CHAINED_HOOK = "pre-push.ai-factory-chained";
@@ -24341,7 +24714,7 @@ async function installPrePush(repoDir) {
   const path = join12(hooks, "pre-push");
   let status = "installed";
   if (existsSync9(path)) {
-    const current = readFileSync8(path, "utf8");
+    const current = readFileSync9(path, "utf8");
     if (current === PRE_PUSH_HOOK)
       return { status: "unchanged", path };
     if (current.includes(HOOK_MARKER)) {
@@ -24370,7 +24743,7 @@ async function prePushState(repoDir) {
   const path = join12(hooks, "pre-push");
   if (!existsSync9(path))
     return "missing";
-  const text = readFileSync8(path, "utf8");
+  const text = readFileSync9(path, "utf8");
   if (text === PRE_PUSH_HOOK)
     return "installed";
   return text.includes("# ai-factory-hook") ? "outdated" : "missing";
@@ -24392,13 +24765,17 @@ import {
   existsSync as existsSync10,
   mkdirSync as mkdirSync5,
   mkdtempSync as mkdtempSync2,
-  readFileSync as readFileSync9,
+  readFileSync as readFileSync11,
   renameSync as renameSync4,
   rmSync as rmSync3,
   writeFileSync as writeFileSync5
 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
-import { dirname as dirname4, join as join13 } from "node:path";
+import { dirname as dirname4, join as join14 } from "node:path";
+
+// src/render/workspace.ts
+import { readFileSync as readFileSync10 } from "node:fs";
+import { join as join13 } from "node:path";
 
 // templates/agents/architect.md
 var architect_default = "# Role: architect\n\nYou write the OpenSpec change for an approved intake: proposal, delta specs with scenarios, design and tasks. You do not write code.\n\n## Inputs\n\nThe task message contains the change id, the request summary, explorer summaries per repo, the workspace repos and the contracts. Start from those; query the graph for anything they do not cover.\n\n## Where you may write\n\nOnly `openspec/changes/<change-id>/` and `.factory/context/<change-id>/`. Everything else is read-only for you.\n\n## Proposal (`proposal.md`)\n\n`## Why` (the problem, 2–5 sentences), `## What Changes` (bullets), `## Capabilities` (`### New Capabilities` / `### Modified Capabilities`), `## Impact` (repos, APIs, contracts, data).\n\n## Specs (`specs/<capability>/spec.md`)\n\n- Use `## ADDED|MODIFIED|REMOVED Requirements`, `### Requirement: <name>` with SHALL/MUST, and at least one `#### Scenario: <name>` per requirement with `- **WHEN** …` / `- **THEN** …` lines.\n- Scenarios are concrete and testable: inputs, observable outputs, error cases. Every scenario will get a test.\n\n## Design (`design.md`)\n\nContext, decisions with the alternatives you rejected, contract changes, risks. Keep it short.\n\n## Tasks (`tasks.md`)\n\nGroup by repo. Every task is one checkbox line followed by three metadata lines, exactly:\n```\n## 1. backend\n- [ ] 1.1 Add health handler\n  - repo: backend\n  - deps: none\n  - touches: internal/http/**, cmd/server/main.go\n```\n\n- Each task names exactly one repo from the workspace list.\n- `deps` lists task ids it needs (`1.1, 2.3`) or `none`. No cycles.\n- `touches` lists the file globs (relative to that repo) the task may change. Tasks in the same repo with overlapping globs run one after another, so keep globs tight.\n- Contract changes (API schemas, events, Helm values) are their own tasks, first, and consumer tasks depend on them so they can run in parallel.\n- Size tasks so one agent can finish one in a single focused session. Tests for a task's behaviour belong to that task.\n- Never put `[ ]` anywhere except on the task line itself.\n\n## Context packs (after approval only)\n\nWhen asked to write context packs, write one file per task to `.factory/context/<change-id>/<task-id>.md`, under the token cap in the task message, containing: the task, the spec scenarios it covers, the contract excerpts it needs, the target symbols with file paths (line ranges are hints only), and the gate commands.\n\nUse `task: \"design\"` or `task: \"context-packs\"` in your handoff and list every file you wrote.\n";
@@ -27252,6 +27629,31 @@ export {
 };
 `;
 
+// src/config/instructions.ts
+import { relative as relative3 } from "node:path";
+var repoOf = (config, name) => config.repos.find((r) => r.name === name)?.path ?? name;
+function instructionPaths(config, repo) {
+  const repoPaths = repo === undefined ? [] : (config.instructions.repos[repo] ?? []).map((path) => {
+    const base = repoOf(config, repo);
+    return base === "." ? path : `${base}/${path}`;
+  });
+  return [...new Set([...config.instructions.workspace, ...repoPaths])];
+}
+function sessionInstructionPaths(config, repoName, repoPath) {
+  return instructionPaths(config, repoName).map((path) => {
+    const rel = relative3(repoPath, path);
+    return rel === "" ? path : rel;
+  });
+}
+function allInstructionPaths(config) {
+  return [
+    ...new Set([
+      ...config.instructions.workspace,
+      ...Object.keys(config.instructions.repos).flatMap((repo) => instructionPaths(config, repo))
+    ])
+  ];
+}
+
 // src/handoff/schema.ts
 var Finding = strictObject({
   severity: _enum(["must", "should", "nice"]),
@@ -27374,7 +27776,7 @@ var READ_TOOLS = [
   rule("glob", "*", "allow"),
   rule("grep", "*", "allow")
 ];
-function agentRules(role, testGlobs = []) {
+function agentRules(role, testGlobs = [], options = {}) {
   const rules = ACTIONS.map((a) => rule(a, "*", "deny"));
   switch (role) {
     case "orchestrator":
@@ -27384,6 +27786,7 @@ function agentRules(role, testGlobs = []) {
       break;
     case "architect":
       rules.push(...READ_TOOLS, ...allowAll("shell", GRAPH_QUERY_COMMANDS), rule("edit", "openspec/changes/*", "allow"));
+      rules.push(...optionalTools(options));
       return [...rules, ...alwaysDeny([".factory/context/*"])];
     case "reviewer":
     case "contract-reviewer":
@@ -27396,8 +27799,32 @@ function agentRules(role, testGlobs = []) {
       rules.push(...READ_TOOLS, rule("shell", "*", "allow"), rule("edit", "*", "allow"));
       break;
   }
+  rules.push(...optionalTools(options));
   return [...rules, ...alwaysDeny()];
 }
+function customAgentRules(phase, options) {
+  const rules = ACTIONS.map((a) => rule(a, "*", "deny"));
+  rules.push(...READ_TOOLS);
+  if (phase === "reviewer" || phase === "contract-reviewer") {
+    rules.push(...allowAll("shell", [...GRAPH_QUERY_COMMANDS, ...READ_ONLY_GIT]));
+  } else {
+    rules.push(rule("shell", "*", "allow"));
+  }
+  rules.push(...allowAll("shell", options.shell ?? []));
+  rules.push(...allowAll("edit", options.edits ?? []));
+  rules.push(...optionalTools(options));
+  return [...rules, ...alwaysDeny()];
+}
+function optionalTools(options) {
+  const out = [];
+  if (options.skills === true)
+    out.push(rule("skill", "*", "allow"));
+  if (options.web === true)
+    out.push(rule("webfetch", "*", "allow"), rule("websearch", "*", "allow"));
+  for (const action of options.mcp ?? [])
+    out.push(rule(action, "*", "allow"));
+  return out;
+}
 function alwaysDeny(reallow = []) {
   return [
     ...denyAll("edit", PROTECTED_PATHS),
@@ -28105,6 +28532,84 @@ var rust_default = `# Rust standard
 - One behaviour per \`#[test]\`; every spec scenario maps to at least one test named after it (\`fn rejects_expired_token()\`). <!-- factory -->
 `;
 
+// templates/standards/swift.md
+var swift_default = `# Swift standard
+
+<!-- Sources:
+[api] Swift API Design Guidelines — https://www.swift.org/documentation/api-design-guidelines/
+[style] Swift.org: Swift Style Guide — https://www.swift.org/documentation/api-design-guidelines/#fundamentals
+[format] SwiftFormat rules — https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md
+[lint] SwiftLint rules — https://realm.github.io/SwiftLint/rule-directory.html
+[testing] Swift Testing — https://developer.apple.com/documentation/testing
+[xcode] Xcode Build Settings Reference — https://developer.apple.com/documentation/xcode/build-settings-reference
+-->
+
+## Summary
+
+- Keep the package/plugin layout and deployment target the repository already declares.
+- \`swiftformat --lint\` and \`swiftlint\` are gates; never suppress a rule without a reason.
+- Names read as prose at the call site; types are nouns, methods are verbs, booleans are assertions.
+- Prefer values and \`let\`; use \`var\` only when mutation is part of the design.
+- Handle errors with \`throws\`/\`Result\`; do not trap or force-unwrap outside tests and proven invariants.
+- Public APIs have documentation comments and explicit access control; implementation stays internal.
+- Test behaviour with Swift Testing (or the repo's XCTest suite); one test per spec scenario.
+
+## Layout and access
+
+<!-- [api] Fundamentals; [xcode] Packaging -->
+- Keep the repository's existing package and plugin directories; don't introduce a second source root. <!-- factory -->
+- One primary type per file, file named after the type; extensions that add protocol conformance live beside it.
+- Default to \`internal\`. Add \`public\` only for the module's real surface; mark implementation details \`private\` or \`fileprivate\`.
+- Keep platform code behind \`#if os(iOS)\` / \`#if os(macOS)\` and shared code platform-neutral. <!-- factory -->
+
+## Naming and API shape
+
+<!-- [api] Naming; [style] Naming -->
+- Types and protocols are \`UpperCamelCase\`; functions, properties and cases are \`lowerCamelCase\`.
+- Methods read as a sentence at the call site: \`move(from:to:)\`, not \`moveFromTo(_:_:)\`.
+- Booleans assert a fact: \`isEnabled\`, \`hasPermission\`, \`canRetry\`.
+- Omit needless words; the argument label carries the role (\`add(_ element:)\`, \`remove(at:)\`).
+- Acronyms keep a single case (\`URLSession\`, \`userID\`); don't abbreviate domain words.
+
+## Values, optionals and errors
+
+<!-- [api] Fundamentals; [testing] Error Handling -->
+- Prefer \`let\`; use \`var\` only where mutation is required and scoped.
+- Avoid force unwrap (\`!\`), \`try!\` and \`as!\` outside tests; use \`guard let\`, \`if let\`, or throw.
+- Use \`throws\` for recoverable failure and typed errors for cases callers branch on; never discard an error.
+- \`fatalError\` only for a broken invariant at startup, with a message naming the invariant. <!-- factory -->
+
+## Concurrency
+
+<!-- [api] Concurrency; [lint] Concurrency rules -->
+- Keep UI work on the main actor; mark views and view models \`@MainActor\` where the framework expects it.
+- Use structured concurrency (\`async let\`, task groups); do not detach a task without an owner and cancellation path.
+- Shared mutable state is an actor or guarded by a lock; document the isolation boundary.
+- Never block the main actor with file, network or database I/O. <!-- factory -->
+
+## Tauri plugins and iOS/macOS glue
+
+<!-- [xcode] Frameworks; [api] Documentation -->
+- A Tauri plugin exposes a typed Rust API; Swift stays behind that boundary and never becomes the public contract.
+- Request permission strings and entitlements from the security owner; do not edit capability files here. <!-- factory -->
+- Verify the host build and the iOS target compile; report which SDK/target you used. <!-- factory -->
+
+## Testing
+
+<!-- [testing] Test declarations; [lint] Test rules -->
+- Use Swift Testing (\`@Test\`, \`#expect\`) in new code; keep the repo's XCTest suite where it already exists.
+- Test behaviour through the public API; avoid snapshot-only tests and sleeps.
+- Name tests after the scenario they cover; one scenario can have several focused tests.
+- Keep tests deterministic: inject clocks, file systems and network clients at the boundary. <!-- factory -->
+
+## Formatting and verification
+
+<!-- [format] Rules; [lint] Configuration -->
+- \`swiftformat --lint\` must pass; do not reformat code outside the task.
+- \`swiftlint lint\` must pass with the repository's config; fix the cause instead of adding \`// swiftlint:disable\`.
+- \`swift build\` (and the iOS target build where relevant) must pass before the task is done. <!-- factory -->
+`;
+
 // templates/standards/tauri.md
 var tauri_default = `# Tauri v2 standard
 
@@ -28527,6 +29032,24 @@ var PROFILES = {
     },
     install: [{ lockfile: "go.sum", command: "go mod download" }]
   },
+  swift: {
+    id: "swift",
+    title: "Swift",
+    prose: swift_default,
+    testGlobs: ["*Tests.swift", "*/Tests/*", "Tests/*"],
+    markers: ["Package.swift"],
+    targets: "dir",
+    extensions: [".swift"],
+    binDirs: [],
+    gates: {
+      format: [{ command: "swiftformat --lint .", scoped: "swiftformat --lint {files}" }],
+      lint: [{ command: "swiftlint lint", scoped: "swiftlint lint --path {files}" }],
+      types: [{ command: "swift build" }],
+      test: [{ command: "swift test" }],
+      testAffected: [{ command: "swift test" }]
+    },
+    install: [{ lockfile: "Package.resolved", command: "swift package resolve" }]
+  },
   rust: {
     id: "rust",
     title: "Rust",
@@ -28699,9 +29222,9 @@ var AGENTS = [
 function frontmatter(spec) {
   const data = {
     description: spec.description,
-    mode: "primary",
+    mode: spec.mode ?? "primary",
     model: spec.model,
-    permissions: agentRules(spec.role, spec.testGlobs)
+    permissions: spec.permissions ?? agentRules(spec.role, spec.testGlobs)
   };
   const doc = new $Document(data);
   const rules = doc.get("permissions", true);
@@ -28721,10 +29244,55 @@ ${parts.sections.map((s) => s.trim()).join(`
 `)}
 `;
 }
+var ROLE_FOR_PHASE = {
+  orchestrator: "orchestrator",
+  architect: "architect",
+  explorer: "explorer",
+  reviewer: "reviewer",
+  "contract-reviewer": "contractReviewer",
+  tester: "tester",
+  implementer: "implementer"
+};
+function skillNames(config, role, repo) {
+  return [
+    ...new Set([
+      ...config.skills.roles[role] ?? [],
+      ...repo === undefined ? [] : config.skills.repos[repo] ?? []
+    ])
+  ];
+}
+function skillsSection(names) {
+  if (names.length === 0)
+    return;
+  return `## Skills
+
+Load these skills first: ${names.map((n) => `\`${n}\``).join(", ")}. Use the skill tool before you start; follow the loaded skill over your own habits.`;
+}
+function instructionsSection(config, repo) {
+  const paths = instructionPaths(config, repo);
+  if (paths.length === 0)
+    return;
+  return `## Project instructions
+
+Read these files before you change anything; they are the project's own bar and take precedence over your general knowledge. Paths are workspace-relative; from a worktree or repo checkout, open \`$AI_FACTORY_WORKSPACE/<path>\`:
+${paths.map((p) => `- \`${p}\``).join(`
+`)}`;
+}
+function sharedSections(role) {
+  return role === "orchestrator" ? [untrusted_default, handoff_default] : [untrusted_default, graph_default, handoff_default];
+}
 function renderAgent(config, spec) {
-  const shared = spec.role === "orchestrator" ? [untrusted_default, handoff_default] : [untrusted_default, graph_default, handoff_default];
+  const skillList = skillNames(config, spec.modelRole);
+  const web = spec.role === "reviewer" || spec.role === "contract-reviewer";
+  const options = {
+    ...skillList.length > 0 ? { skills: true } : {},
+    ...web ? { web: true } : {},
+    ...config.mcp.roles[spec.modelRole] === undefined ? {} : { mcp: config.mcp.roles[spec.modelRole] }
+  };
   const section = spec.role === "reviewer" ? ponytailSection(config, "reviewer") : undefined;
   const addon = section === undefined ? [] : [section];
+  const skills = skillsSection(skillList);
+  const instructions = instructionsSection(config);
   return {
     path: `.opencode/agents/${spec.id}.md`,
     template: `agents/${spec.id}`,
@@ -28734,9 +29302,16 @@ function renderAgent(config, spec) {
         description: spec.description,
         model: modelFor(config, spec.modelRole),
         role: spec.role,
-        ...spec.role === "tester" ? { testGlobs: workspaceTestGlobs(config) } : {}
+        ...spec.role === "tester" ? { testGlobs: workspaceTestGlobs(config) } : {},
+        permissions: agentRules(spec.role, spec.role === "tester" ? workspaceTestGlobs(config) : [], options)
       }),
-      sections: [spec.body, ...addon, ...shared]
+      sections: [
+        spec.body,
+        ...instructions === undefined ? [] : [instructions],
+        ...skills === undefined ? [] : [skills],
+        ...addon,
+        ...sharedSections(spec.role)
+      ]
     })
   };
 }
@@ -28752,6 +29327,8 @@ function renderImplementer(config, repo) {
   const standards = profilesFor(languages).map((p) => renderStandard(p, { comments: false }));
   const langs = languages.length > 0 ? languages.join(", ") : "none detected";
   const addon = ponytailSection(config, "implementer");
+  const skills = skillsSection(skillNames(config, "implementer", repo.name));
+  const instructions = instructionsSection(config, repo.name);
   return {
     path: `.opencode/agents/implementer-${repo.name}.md`,
     template: "agents/implementer",
@@ -28759,11 +29336,19 @@ function renderImplementer(config, repo) {
     content: agentFile({
       head: frontmatter({
         description: `ai-factory implementer for ${repo.name} (${repo.path}; ${langs}).`,
-        model: modelFor(config, "implementer"),
-        role: "implementer"
+        model: modelFor(config, "implementer", { repo: repo.name }),
+        role: "implementer",
+        ...skills === undefined && config.mcp.roles.implementer === undefined ? {} : {
+          permissions: agentRules("implementer", [], {
+            skills: skills !== undefined,
+            ...config.mcp.roles.implementer === undefined ? {} : { mcp: config.mcp.roles.implementer }
+          })
+        }
       }),
       sections: [
         implementer_default.replaceAll("{{repo}}", repo.name),
+        ...instructions === undefined ? [] : [instructions],
+        ...skills === undefined ? [] : [skills],
         ...standards,
         ...addon === undefined ? [] : [addon],
         untrusted_default,
@@ -28773,6 +29358,41 @@ function renderImplementer(config, repo) {
     })
   };
 }
+function renderCustomAgent(config, agent, root) {
+  const role = ROLE_FOR_PHASE[agent.phase] ?? "implementer";
+  const agentRole = agent.phase;
+  const body = agent.prompt ?? (agent.promptFile !== undefined && root !== undefined ? readFileSync10(join13(root, agent.promptFile), "utf8") : `# Role: ${agent.id}
+
+${agent.description}`);
+  const skills = skillsSection(agent.skills);
+  const instructions = instructionsSection(config);
+  return {
+    path: `.opencode/agents/${agent.id}.md`,
+    template: `agents/custom/${agent.id}`,
+    mode: "file",
+    content: agentFile({
+      head: frontmatter({
+        description: agent.description,
+        model: agent.model ?? modelFor(config, role, { agent: agent.id }),
+        role: agentRole,
+        mode: agent.mode,
+        permissions: customAgentRules(agentRole, {
+          edits: agent.edits,
+          shell: agent.shell,
+          skills: agent.skills.length > 0,
+          web: agent.web,
+          mcp: agent.mcp
+        })
+      }),
+      sections: [
+        body,
+        ...instructions === undefined ? [] : [instructions],
+        ...skills === undefined ? [] : [skills],
+        ...sharedSections(agentRole)
+      ]
+    })
+  };
+}
 function renderAgentsMd(config) {
   const markers = BLOCK_MARKERS["AGENTS.md"];
   if (markers === undefined)
@@ -28811,8 +29431,13 @@ ${config.graph.exclude.join(`
 `)}
 `;
 }
-function renderOpencodeConfig() {
-  const config = { $schema: "https://opencode.ai/config.json", update: "disable" };
+function renderOpencodeConfig(factory) {
+  const instructions = allInstructionPaths(factory);
+  const config = {
+    $schema: "https://opencode.ai/config.json",
+    update: "disable",
+    ...instructions.length > 0 ? { instructions } : {}
+  };
   return `// ${MANAGED_HEADER}
 // Agents and their permissions are in .opencode/agents/.
 ${JSON.stringify(config, null, 2)}
@@ -28881,7 +29506,7 @@ function ponytailFiles(config) {
     }
   ];
 }
-function renderWorkspace(config) {
+function renderWorkspace(config, options = {}) {
   const files = [
     { path: "AGENTS.md", template: "agents-md", mode: "block", content: renderAgentsMd(config) },
     { path: ".gitignore", template: "gitignore", mode: "block", content: renderGitignore() },
@@ -28895,7 +29520,7 @@ function renderWorkspace(config) {
       path: ".opencode/opencode.jsonc",
       template: "opencode-config",
       mode: "file",
-      content: renderOpencodeConfig()
+      content: renderOpencodeConfig(config)
     },
     {
       path: ".opencode/plugins/factory.js",
@@ -28929,7 +29554,8 @@ function renderWorkspace(config) {
     })),
     ...ponytailFiles(config),
     ...AGENTS.map((spec) => renderAgent(config, spec)),
-    ...config.repos.filter((r) => r.role === "code").map((r) => renderImplementer(config, r))
+    ...config.repos.filter((r) => r.role === "code").map((r) => renderImplementer(config, r)),
+    ...config.agents.map((agent) => renderCustomAgent(config, agent, options.root))
   ];
   return files.sort((a, b) => a.path.localeCompare(b.path));
 }
@@ -28954,10 +29580,10 @@ function findBlock(text, markers) {
   return { start, end: endMarker + markers.end.length };
 }
 function readOptional(abs) {
-  return existsSync10(abs) ? readFileSync9(abs, "utf8") : undefined;
+  return existsSync10(abs) ? readFileSync11(abs, "utf8") : undefined;
 }
 function currentOwned(root, path, mode) {
-  const text = readOptional(join13(root, path));
+  const text = readOptional(join14(root, path));
   if (text === undefined || mode === "file")
     return text;
   const block = findBlock(text, markersFor(path));
@@ -29025,12 +29651,12 @@ ${block}
   writeAtomic(abs, next);
 }
 function removeOwned(root, path, mode) {
-  const abs = join13(root, path);
+  const abs = join14(root, path);
   if (mode === "file") {
     rmSync3(abs, { force: true });
     return;
   }
-  const text = readFileSync9(abs, "utf8");
+  const text = readFileSync11(abs, "utf8");
   const range = findBlock(text, markersFor(path));
   if (range === undefined)
     return;
@@ -29047,9 +29673,9 @@ async function blobText(root, blob) {
   return res.code === 0 ? res.stdout : undefined;
 }
 async function mergeThree(root, ours, base, theirs) {
-  const dir = mkdtempSync2(join13(tmpdir2(), "ai-factory-merge-"));
+  const dir = mkdtempSync2(join14(tmpdir2(), "ai-factory-merge-"));
   try {
-    const files = { ours: join13(dir, "ours"), base: join13(dir, "base"), theirs: join13(dir, "theirs") };
+    const files = { ours: join14(dir, "ours"), base: join14(dir, "base"), theirs: join14(dir, "theirs") };
     writeFileSync5(files.ours, ours);
     writeFileSync5(files.base, base);
     writeFileSync5(files.theirs, theirs);
@@ -29096,7 +29722,7 @@ async function executeSync(root, plan, previous, options = {}) {
         if (file === undefined)
           throw new Error(`no render for ${change.path}`);
         if (change.action !== "unchanged") {
-          const abs = join13(root, file.path);
+          const abs = join14(root, file.path);
           if (file.mode === "block")
             writeBlock(abs, file.path, file.content);
           else
@@ -29114,7 +29740,7 @@ async function executeSync(root, plan, previous, options = {}) {
           break;
         }
         const result = await mergeThree(root, ours, base, file.content);
-        const abs = join13(root, file.path);
+        const abs = join14(root, file.path);
         if (file.mode === "block")
           writeBlock(abs, file.path, result.text.replace(/\n$/, ""));
         else
@@ -29146,12 +29772,12 @@ import {
   mkdirSync as mkdirSync6,
   mkdtempSync as mkdtempSync3,
   readdirSync as readdirSync5,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync12,
   rmSync as rmSync4,
   statSync as statSync4
 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join14, relative as relative3, sep } from "node:path";
+import { join as join15, relative as relative4, sep } from "node:path";
 
 // src/tasks/glob.ts
 var cache = new Map;
@@ -29441,14 +30067,14 @@ function normalizeCheckboxes(text) {
 
 // src/openspec/cli.ts
 function env(root) {
-  const xdg = join14(root, ".factory", "cache", "openspec-xdg");
+  const xdg = join15(root, ".factory", "cache", "openspec-xdg");
   mkdirSync6(xdg, { recursive: true });
   return { ...toolEnv("openspec"), XDG_CONFIG_HOME: xdg };
 }
 async function openspec(root, cwd, args) {
   return exec([toolBin("openspec"), ...args], { cwd, env: env(root), timeoutMs: 120000 });
 }
-var changePath = (dir, id) => join14(dir, "openspec", "changes", id);
+var changePath = (dir, id) => join15(dir, "openspec", "changes", id);
 async function newChange(root, dir, id) {
   if (existsSync11(changePath(dir, id)))
     return;
@@ -29470,10 +30096,10 @@ async function validateChange(root, dir, id) {
   return item.valid ? [] : item.issues.map((i) => `openspec ${i.level.toLowerCase()}: ${i.path ? `${i.path}: ` : ""}${i.message}`);
 }
 function checkProposal(dir, id) {
-  const file = join14(changePath(dir, id), "proposal.md");
+  const file = join15(changePath(dir, id), "proposal.md");
   if (!existsSync11(file))
     return ["proposal.md is missing"];
-  const text = readFileSync10(file, "utf8");
+  const text = readFileSync12(file, "utf8");
   const issues = [];
   for (const heading of ["## Why", "## What Changes"]) {
     if (!text.split(`
@@ -29487,10 +30113,10 @@ function checkProposal(dir, id) {
 }
 async function checkDesign(root, dir, id, codeRepos, contracts = []) {
   const issues = [...checkProposal(dir, id), ...await validateChange(root, dir, id)];
-  const tasksFile = join14(changePath(dir, id), "tasks.md");
+  const tasksFile = join15(changePath(dir, id), "tasks.md");
   if (!existsSync11(tasksFile))
     return { issues: [...issues, "tasks.md is missing"], tasks: [] };
-  const parsed = parseTasks(readFileSync10(tasksFile, "utf8"));
+  const parsed = parseTasks(readFileSync12(tasksFile, "utf8"));
   issues.push(...parsed.issues.map((i) => `tasks.md:${i.line}: ${i.message}`));
   if (parsed.tasks.length === 0)
     issues.push("tasks.md has no tasks");
@@ -29508,7 +30134,7 @@ async function archiveChange(root, dir, id) {
 }
 var OPENSPEC_TOOLS_TEMPLATE = "openspec-tools";
 async function renderOpenspecTools(root) {
-  const scratch = mkdtempSync3(join14(tmpdir3(), "ai-factory-openspec-"));
+  const scratch = mkdtempSync3(join15(tmpdir3(), "ai-factory-openspec-"));
   try {
     const res = await exec([
       toolBin("openspec"),
@@ -29522,21 +30148,21 @@ async function renderOpenspecTools(root) {
     ], { cwd: scratch, env: env(root), timeoutMs: 120000 });
     if (res.code !== 0)
       throw new ExecError("openspec init failed", res);
-    const base = join14(scratch, ".opencode");
+    const base = join15(scratch, ".opencode");
     if (!existsSync11(base))
       return [];
     const files = [];
     const walk = (dir) => {
       for (const name of readdirSync5(dir).sort()) {
-        const abs = join14(dir, name);
+        const abs = join15(dir, name);
         if (statSync4(abs).isDirectory())
           walk(abs);
         else
           files.push({
-            path: relative3(scratch, abs).split(sep).join("/"),
+            path: relative4(scratch, abs).split(sep).join("/"),
             template: OPENSPEC_TOOLS_TEMPLATE,
             mode: "file",
-            content: readFileSync10(abs, "utf8")
+            content: readFileSync12(abs, "utf8")
           });
       }
     };
@@ -29567,7 +30193,7 @@ function carriedTools(previous, options) {
 function planWorkspace(root, config, options = {}) {
   const previous = readLock(root)?.managed ?? {};
   const tools = options.tools ?? [];
-  const plan = planSync(root, [...renderWorkspace(config), ...tools], previous, {
+  const plan = planSync(root, [...renderWorkspace(config, { root }), ...tools], previous, {
     unmanaged: config.unmanaged,
     ...options,
     carry: Object.keys(carriedTools(previous, options)),
@@ -29608,10 +30234,10 @@ async function syncWorkspace(root, config, options = {}) {
       files: [...PONYTAIL.files]
     }
   } : {});
-  writeFileSync6(join15(root, LOCK_FILE), serializeLock(lock));
+  writeFileSync6(join16(root, LOCK_FILE), serializeLock(lock));
   const hooks = [];
   for (const repo of config.repos) {
-    hooks.push({ repo: repo.name, result: await installPrePush(join15(root, repo.path)) });
+    hooks.push({ repo: repo.name, result: await installPrePush(join16(root, repo.path)) });
   }
   return { plan, lock, hooks, merged, conflicts };
 }
@@ -29623,7 +30249,7 @@ async function dirtyInstallPaths(root, ignore = []) {
 `).filter((l) => l.trim() !== "").map((l) => l.slice(3)).filter((p) => !ignore.includes(p));
 }
 function commitInstall(root, message) {
-  return commitPaths(root, INSTALL_PATHS.filter((p) => existsSync12(join15(root, p))), message);
+  return commitPaths(root, INSTALL_PATHS.filter((p) => existsSync12(join16(root, p))), message);
 }
 
 // src/cli/commands/detect.ts
@@ -29658,7 +30284,7 @@ var detectCommand = {
         "run ai-factory from the workspace (AI repo or single repo)"
       ]);
     }
-    const hasConfig = existsSync13(join16(root, CONFIG_FILE));
+    const hasConfig = existsSync13(join17(root, CONFIG_FILE));
     const loaded = hasConfig ? loadConfig(root) : undefined;
     if (values.apply && loaded === undefined) {
       throw new PreconditionError(`no ${CONFIG_FILE} to apply to`, ["run `ai-factory init` first"]);
@@ -29734,21 +30360,21 @@ var detectCommand = {
 };
 
 // src/doctor/doctor.ts
-import { existsSync as existsSync20, lstatSync as lstatSync2, mkdtempSync as mkdtempSync4, readdirSync as readdirSync7, readFileSync as readFileSync16, rmSync as rmSync8 } from "node:fs";
+import { existsSync as existsSync20, lstatSync as lstatSync2, mkdtempSync as mkdtempSync4, readdirSync as readdirSync7, readFileSync as readFileSync18, rmSync as rmSync8 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { delimiter, extname, join as join26 } from "node:path";
+import { delimiter, extname, join as join27 } from "node:path";
 
 // src/gates/resolve.ts
-import { existsSync as existsSync16, readFileSync as readFileSync13 } from "node:fs";
-import { join as join19 } from "node:path";
+import { existsSync as existsSync16, readFileSync as readFileSync15 } from "node:fs";
+import { join as join20 } from "node:path";
 
 // src/gates/affected.ts
-import { existsSync as existsSync15, readFileSync as readFileSync12 } from "node:fs";
-import { join as join18, relative as relative4 } from "node:path";
+import { existsSync as existsSync15, readFileSync as readFileSync14 } from "node:fs";
+import { join as join19, relative as relative5 } from "node:path";
 
 // src/gates/targets.ts
-import { existsSync as existsSync14, readFileSync as readFileSync11 } from "node:fs";
-import { join as join17 } from "node:path";
+import { existsSync as existsSync14, readFileSync as readFileSync13 } from "node:fs";
+import { join as join18 } from "node:path";
 var WALK2 = { maxDepth: 8, maxFiles: 50000 };
 function worktreeFiles(worktree) {
   return listFiles(worktree, WALK2).map((f) => f.path);
@@ -29789,7 +30415,7 @@ function installDirs(profile, files) {
 }
 function packageDependencies(abs) {
   try {
-    const pkg = JSON.parse(readFileSync11(join17(abs, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync13(join18(abs, "package.json"), "utf8"));
     const names = new Set;
     for (const key of [
       "dependencies",
@@ -29810,9 +30436,9 @@ function packageDependencies(abs) {
 function requirementHolds(req, worktree, dir) {
   if (req === undefined)
     return true;
-  const dirs = dir === "." ? [worktree] : [join17(worktree, dir), worktree];
+  const dirs = dir === "." ? [worktree] : [join18(worktree, dir), worktree];
   if ("file" in req)
-    return dirs.some((d) => req.file.some((f) => existsSync14(join17(d, f))));
+    return dirs.some((d) => req.file.some((f) => existsSync14(join18(d, f))));
   if ("dependency" in req) {
     return dirs.some((d) => {
       const deps = packageDependencies(d);
@@ -29821,7 +30447,7 @@ function requirementHolds(req, worktree, dir) {
   }
   return dirs.some((d) => {
     try {
-      return readFileSync11(join17(d, req.fileContains.file), "utf8").includes(req.fileContains.text);
+      return readFileSync13(join18(d, req.fileContains.file), "utf8").includes(req.fileContains.text);
     } catch {
       return false;
     }
@@ -29852,12 +30478,12 @@ var stem = (path) => {
   return dot === -1 ? base : base.slice(0, dot);
 };
 function targetChanges(target, changed) {
-  const roots = target.charts.length > 0 ? target.charts.map((c) => join18(target.dir, c)) : [target.dir];
+  const roots = target.charts.length > 0 ? target.charts.map((c) => join19(target.dir, c)) : [target.dir];
   return changed.filter((f) => roots.some((r) => within(f, r)) && (target.charts.length > 0 || hasExt(target.profile, f)));
 }
 function crateName(cargoToml) {
   try {
-    const text = readFileSync12(cargoToml, "utf8");
+    const text = readFileSync14(cargoToml, "utf8");
     const pkg = text.split(/^\[/m).find((section) => section.startsWith("package]"));
     return pkg?.match(/^\s*name\s*=\s*"([^"]+)"/m)?.[1];
   } catch {
@@ -29872,9 +30498,9 @@ function ancestorDirs(path) {
   return [...dirs, "."];
 }
 function placeholderValues(worktree, target, changed, allFiles, base, mode, related = []) {
-  const rel = (p) => target.dir === "." ? p : relative4(target.dir, p);
+  const rel = (p) => target.dir === "." ? p : relative5(target.dir, p);
   const mine = targetChanges(target, changed);
-  const existing = mine.filter((f) => existsSync15(join18(worktree, f)));
+  const existing = mine.filter((f) => existsSync15(join19(worktree, f)));
   const tests = new Set(existing.filter((f) => isTestFile(target.profile, f)));
   const stems = new Set(existing.filter((f) => !isTestFile(target.profile, f)).map(stem));
   const dependents = new Set(related);
@@ -29887,11 +30513,11 @@ function placeholderValues(worktree, target, changed, allFiles, base, mode, rela
   const packages = [...new Set(existing.filter((f) => f.endsWith(".go")).map((f) => rel(f)))].map((f) => f.includes("/") ? `./${f.slice(0, f.lastIndexOf("/"))}` : ".").filter((p, i, all) => all.indexOf(p) === i);
   const crates = new Set;
   for (const f of existing.filter((x) => x.endsWith(".rs"))) {
-    const name = ancestorDirs(f).map((dir) => crateName(join18(worktree, dir, "Cargo.toml"))).find((n) => n !== undefined);
+    const name = ancestorDirs(f).map((dir) => crateName(join19(worktree, dir, "Cargo.toml"))).find((n) => n !== undefined);
     if (name)
       crates.add(name);
   }
-  const charts = mode === "full" ? [...target.charts] : target.charts.filter((c) => mine.some((f) => within(f, join18(target.dir, c))));
+  const charts = mode === "full" ? [...target.charts] : target.charts.filter((c) => mine.some((f) => within(f, join19(target.dir, c))));
   return {
     files: existing.map(rel),
     testFiles: [...tests].sort().map(rel),
@@ -29923,22 +30549,22 @@ var GATES_BY_MODE = {
 var SKIP = "skip";
 function readText2(path) {
   try {
-    return readFileSync13(path, "utf8");
+    return readFileSync15(path, "utf8");
   } catch {
     return;
   }
 }
 function scriptRunner(worktree) {
-  if (existsSync16(join19(worktree, "bun.lock")) || existsSync16(join19(worktree, "bun.lockb")))
+  if (existsSync16(join20(worktree, "bun.lock")) || existsSync16(join20(worktree, "bun.lockb")))
     return "bun run";
-  if (existsSync16(join19(worktree, "pnpm-lock.yaml")))
+  if (existsSync16(join20(worktree, "pnpm-lock.yaml")))
     return "pnpm run";
-  if (existsSync16(join19(worktree, "yarn.lock")))
+  if (existsSync16(join20(worktree, "yarn.lock")))
     return "yarn run";
   return "npm run --silent";
 }
 function findScript(worktree, name) {
-  const pkg = readText2(join19(worktree, "package.json"));
+  const pkg = readText2(join20(worktree, "package.json"));
   if (pkg !== undefined) {
     try {
       const scripts = JSON.parse(pkg).scripts;
@@ -29947,14 +30573,14 @@ function findScript(worktree, name) {
     } catch {}
   }
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const make = readText2(join19(worktree, "Makefile"));
+  const make = readText2(join20(worktree, "Makefile"));
   if (make !== undefined && new RegExp(`^${escaped}\\s*:(?!=)`, "m").test(make))
     return "Makefile";
-  const just = readText2(join19(worktree, "justfile")) ?? readText2(join19(worktree, "Justfile"));
+  const just = readText2(join20(worktree, "justfile")) ?? readText2(join20(worktree, "Justfile"));
   if (just !== undefined && new RegExp(`^@?${escaped}(\\s[^:]*)?:(?!=)`, "m").test(just))
     return "justfile";
   for (const file of ["Taskfile.yml", "Taskfile.yaml"]) {
-    const task = readText2(join19(worktree, file));
+    const task = readText2(join20(worktree, file));
     if (task === undefined)
       continue;
     try {
@@ -30004,7 +30630,7 @@ function profileGate(input, type, target) {
     cwd: target.dir,
     source: "profile",
     profile: target.profile.id,
-    binDirs: target.profile.binDirs.map((b) => target.dir === "." ? b : join19(target.dir, b))
+    binDirs: target.profile.binDirs.map((b) => target.dir === "." ? b : join20(target.dir, b))
   };
 }
 var isGap = (x) => ("reason" in x);
@@ -30035,7 +30661,7 @@ function resolveGates(input) {
     const scriptName = input.config.gates.scripts[type];
     const host = scriptName === undefined ? undefined : findScript(input.worktree, scriptName);
     if (host !== undefined && scriptName !== undefined) {
-      const files = type === "testAffected" ? input.changed.filter((f) => existsSync16(join19(input.worktree, f))) : [];
+      const files = type === "testAffected" ? input.changed.filter((f) => existsSync16(join20(input.worktree, f))) : [];
       if (type === "testAffected" && files.length === 0) {
         plan.skipped.push({ type, cwd: ".", reason: "skip: nothing affected" });
       } else {
@@ -30069,13 +30695,50 @@ function resolveGates(input) {
         plan.missing.push(result);
     }
   }
+  for (const extra of input.config.gates.extra) {
+    if (!extra.phases.includes(input.mode))
+      continue;
+    const wanted = extra.when.changed;
+    if (wanted.length > 0 && input.mode === "task" && !input.changed.some((file) => wanted.some((glob) => opencodeGlobRegExp(glob).test(file)))) {
+      plan.skipped.push({
+        type: extra.type,
+        cwd: extra.cwd,
+        reason: `skip: ${extra.name} does not match the changed paths`
+      });
+      continue;
+    }
+    const values = repoPlaceholders(input, targets);
+    const command = fillPlaceholders(extra.command, values);
+    if (command === undefined) {
+      plan.skipped.push({
+        type: extra.type,
+        cwd: extra.cwd,
+        reason: `skip: nothing affected for ${extra.name}`
+      });
+      continue;
+    }
+    const setup = extra.setup === undefined ? undefined : fillPlaceholders(extra.setup, values);
+    plan.gates.push({
+      type: extra.type,
+      name: extra.name,
+      command,
+      cwd: extra.cwd,
+      source: "extra",
+      binDirs: rootBins,
+      ...Object.keys(extra.env).length > 0 ? { env: extra.env } : {},
+      ...setup === undefined ? {} : { setup },
+      ...extra.outputs.length > 0 ? { outputs: extra.outputs } : {},
+      checkOnly: extra.checkOnly,
+      ...extra.timeoutMs === undefined ? {} : { timeoutMs: extra.timeoutMs }
+    });
+  }
   return plan;
 }
 function repoPlaceholders(input, targets) {
-  const perTarget = targets.map((t) => placeholderValues(input.worktree, { profile: t.profile, dir: ".", charts: t.charts.map((c) => join19(t.dir, c)) }, input.changed, input.files, input.base, input.mode));
+  const perTarget = targets.map((t) => placeholderValues(input.worktree, { profile: t.profile, dir: ".", charts: t.charts.map((c) => join20(t.dir, c)) }, input.changed, input.files, input.base, input.mode));
   const union = (key) => [...new Set(perTarget.flatMap((v) => v[key]))].sort();
   return {
-    files: input.changed.filter((f) => existsSync16(join19(input.worktree, f))),
+    files: input.changed.filter((f) => existsSync16(join20(input.worktree, f))),
     testFiles: union("testFiles"),
     packages: union("packages"),
     crates: union("crates"),
@@ -30139,8 +30802,8 @@ async function resolveBranchRef(dir, branch, options = {}) {
 }
 
 // src/graph/graph.ts
-import { existsSync as existsSync18, readFileSync as readFileSync14, rmSync as rmSync6, statSync as statSync6 } from "node:fs";
-import { join as join21 } from "node:path";
+import { existsSync as existsSync18, readFileSync as readFileSync16, rmSync as rmSync6, statSync as statSync6 } from "node:fs";
+import { join as join22 } from "node:path";
 
 // src/logs/log.ts
 import {
@@ -30152,7 +30815,7 @@ import {
   rmSync as rmSync5,
   statSync as statSync5
 } from "node:fs";
-import { join as join20 } from "node:path";
+import { join as join21 } from "node:path";
 
 // src/logs/redact.ts
 var MARK = (kind) => `[REDACTED:${kind}]`;
@@ -30210,7 +30873,7 @@ function redactValue(value, env, heuristic) {
     return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactValue(v, env, heuristic)]));
   return value;
 }
-var logDir = (root, changeId) => join20(root, ".factory", "logs", changeId);
+var logDir = (root, changeId) => join21(root, ".factory", "logs", changeId);
 function appendLog(root, changeId, entry, options = {}) {
   const dir = logDir(root, changeId);
   mkdirSync7(dir, { recursive: true });
@@ -30220,21 +30883,21 @@ function appendLog(root, changeId, entry, options = {}) {
     at: at.toISOString(),
     ...redactValue(entry, env, options.redact ?? true)
   });
-  appendFileSync(join20(dir, `${at.toISOString().slice(0, 10)}.jsonl`), `${line}
+  appendFileSync(join21(dir, `${at.toISOString().slice(0, 10)}.jsonl`), `${line}
 `);
 }
 function pruneLogs(root, retentionDays, now = Date.now()) {
-  const base = join20(root, ".factory", "logs");
+  const base = join21(root, ".factory", "logs");
   if (!existsSync17(base))
     return [];
   const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
   const removed = [];
   for (const change of readdirSync6(base)) {
-    const dir = join20(base, change);
+    const dir = join21(base, change);
     if (!statSync5(dir).isDirectory())
       continue;
     for (const file of readdirSync6(dir)) {
-      const abs = join20(dir, file);
+      const abs = join21(dir, file);
       if (statSync5(abs).mtimeMs < cutoff) {
         rmSync5(abs, { force: true });
         removed.push(abs);
@@ -30247,12 +30910,12 @@ function pruneLogs(root, retentionDays, now = Date.now()) {
 }
 
 // src/graph/graph.ts
-var graphDir = (root) => join21(root, "graphify-out");
-var graphFile = (root) => join21(graphDir(root), "graph.json");
+var graphDir = (root) => join22(root, "graphify-out");
+var graphFile = (root) => join22(graphDir(root), "graph.json");
 var metaFile = (root) => factoryDir(root, "graph-meta.json");
 function readGraph(root) {
   try {
-    return JSON.parse(readFileSync14(graphFile(root), "utf8"));
+    return JSON.parse(readFileSync16(graphFile(root), "utf8"));
   } catch {
     return;
   }
@@ -30353,12 +31016,12 @@ function dependentFiles(root, files) {
 }
 
 // src/policy/sandbox.ts
-import { existsSync as existsSync19, readFileSync as readFileSync15 } from "node:fs";
-import { isAbsolute, join as join23, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync19, readFileSync as readFileSync17 } from "node:fs";
+import { isAbsolute, join as join24, resolve as resolve3 } from "node:path";
 
 // src/policy/realpath.ts
 import { lstatSync, readlinkSync, realpathSync as realpathSync2 } from "node:fs";
-import { basename as basename2, dirname as dirname5, join as join22, resolve as resolve2 } from "node:path";
+import { basename as basename2, dirname as dirname5, join as join23, resolve as resolve2 } from "node:path";
 function realPathOf(abs, depth = 0) {
   if (depth > 40)
     return abs;
@@ -30368,11 +31031,11 @@ function realPathOf(abs, depth = 0) {
     const st = lstatSync(current, { throwIfNoEntry: false });
     if (st !== undefined) {
       try {
-        return join22(realpathSync2.native(current), ...missing.reverse());
+        return join23(realpathSync2.native(current), ...missing.reverse());
       } catch {
         if (st.isSymbolicLink()) {
           const target = resolve2(dirname5(current), readlinkSync(current));
-          return realPathOf(join22(target, ...missing.reverse()), depth + 1);
+          return realPathOf(join23(target, ...missing.reverse()), depth + 1);
         }
         return abs;
       }
@@ -30474,8 +31137,8 @@ function seatbeltProfile(policy) {
   if ((policy.writableInside ?? []).length > 0)
     lines.push(`(allow file-write* ${(policy.writableInside ?? []).map(subpath).join(" ")})`);
   if (home !== undefined) {
-    lines.push(`(deny file-write* ${HOME_WRITE_DENY.map((p) => subpath(join23(home, p))).join(" ")})`);
-    lines.push(`(deny file-read* ${HOME_READ_DENY.map((p) => subpath(join23(home, p))).join(" ")})`);
+    lines.push(`(deny file-write* ${HOME_WRITE_DENY.map((p) => subpath(join24(home, p))).join(" ")})`);
+    lines.push(`(deny file-read* ${HOME_READ_DENY.map((p) => subpath(join24(home, p))).join(" ")})`);
   }
   lines.push(`(deny file-write* ${SYSTEM_WRITE_DENY.map(subpath).join(" ")})`);
   if (policy.denySecretReads === true)
@@ -30489,22 +31152,22 @@ function sandboxArgv(profile, argv) {
   return [SANDBOX_EXEC, "-p", profile, ...argv];
 }
 function gitWritableDirs(worktree) {
-  const dotGit = join23(worktree, ".git");
+  const dotGit = join24(worktree, ".git");
   let gitDir = dotGit;
   try {
-    const text = readFileSync15(dotGit, "utf8");
+    const text = readFileSync17(dotGit, "utf8");
     const m = text.match(/^gitdir:\s*(.+)$/m);
     if (m?.[1])
       gitDir = isAbsolute(m[1].trim()) ? m[1].trim() : resolve3(worktree, m[1].trim());
   } catch {
-    return [join23(dotGit, "index"), join23(dotGit, "index.lock"), join23(dotGit, "objects")];
+    return [join24(dotGit, "index"), join24(dotGit, "index.lock"), join24(dotGit, "objects")];
   }
   let common = gitDir;
   try {
-    const rel = readFileSync15(join23(gitDir, "commondir"), "utf8").trim();
+    const rel = readFileSync17(join24(gitDir, "commondir"), "utf8").trim();
     common = isAbsolute(rel) ? rel : resolve3(gitDir, rel);
   } catch {}
-  return [gitDir, join23(common, "objects")];
+  return [gitDir, join24(common, "objects")];
 }
 function protectedInWorktree(worktree) {
   return [
@@ -30516,7 +31179,7 @@ function protectedInWorktree(worktree) {
     "factory.lock.json",
     "openspec/specs",
     ".gitmodules"
-  ].map((p) => join23(worktree, p));
+  ].map((p) => join24(worktree, p));
 }
 function checkoutPolicy(workspace, dir, extra = [], home = process.env.HOME) {
   return {
@@ -30907,11 +31570,11 @@ import { spawn as spawn2 } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { mkdirSync as mkdirSync8, writeFileSync as writeFileSync8 } from "node:fs";
 import { createServer } from "node:net";
-import { join as join25 } from "node:path";
+import { join as join26 } from "node:path";
 
 // src/policy/session-files.ts
-import { join as join24 } from "node:path";
-var sessionContextFile = (workspace, sessionId) => join24(workspace, ".factory", "sessions", `${sessionId}.json`);
+import { join as join25 } from "node:path";
+var sessionContextFile = (workspace, sessionId) => join25(workspace, ".factory", "sessions", `${sessionId}.json`);
 
 // src/runtime/credentials.ts
 var PROVIDER_ENV = {
@@ -30984,8 +31647,7 @@ var PROXY_ENV = [
   "no_proxy"
 ];
 function providersOf(config) {
-  const models = Object.values(config.models).filter((m) => typeof m === "string");
-  return [...new Set(models.map((m) => m.split("/")[0] ?? ""))].filter(Boolean);
+  return [...new Set(allModels(config).map((m) => m.split("/")[0] ?? ""))].filter(Boolean);
 }
 function serverEnv(root, config, password, base = process.env) {
   const env = {};
@@ -31003,11 +31665,11 @@ function serverEnv(root, config, password, base = process.env) {
     ...env,
     ...agentGitEnv({}),
     OPENCODE_PASSWORD: password,
-    OPENCODE_DB: join25(root, ".factory", "opencode", "opencode.db"),
+    OPENCODE_DB: join26(root, ".factory", "opencode", "opencode.db"),
     AI_FACTORY_WORKSPACE: root,
     AI_FACTORY_SCRUB: scrubList().join(","),
     AI_FACTORY_SANDBOX: sandboxEnabled(config.security.sandbox) ? "seatbelt" : "off",
-    AI_FACTORY_GRAPH: join25(root, "graphify-out", "graph.json"),
+    AI_FACTORY_GRAPH: join26(root, "graphify-out", "graph.json"),
     NO_COLOR: "1"
   };
 }
@@ -31045,6 +31707,19 @@ var minus = (a, b) => ({
   cacheWrite: a.cacheWrite - b.cacheWrite,
   cost: a.cost - b.cost
 });
+var WAIT_POLL_MS = 60000;
+function isTimeout(err) {
+  const seen = new Set;
+  let current = err;
+  while (current !== null && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    const { name, cause } = current;
+    if (name === "TimeoutError" || name === "HeadersTimeoutError" || name === "BodyTimeoutError")
+      return true;
+    current = cause;
+  }
+  return false;
+}
 
 class OpencodeRuntime {
   #opts;
@@ -31071,7 +31746,10 @@ class OpencodeRuntime {
     } catch (err) {
       if (signal?.aborted)
         throw err;
-      throw new TransientError(`opencode server unreachable${this.#alive() ? "" : " (it exited)"}: ${err instanceof Error ? err.message : String(err)}`);
+      const detail = err instanceof Error ? err.message : String(err);
+      if (isTimeout(err))
+        throw new TransientError(`opencode client timed out during ${method} ${path}${this.#alive() ? "" : " (the server exited)"}: ${detail}`);
+      throw new TransientError(`opencode server unreachable${this.#alive() ? "" : " (it exited)"}: ${detail}`);
     }
     const text = await res.text();
     let json = text;
@@ -31097,7 +31775,7 @@ class OpencodeRuntime {
     }
     const password = randomBytes(18).toString("base64url");
     const port = await freePort();
-    mkdirSync8(join25(this.#opts.root, ".factory", "opencode"), { recursive: true });
+    mkdirSync8(join26(this.#opts.root, ".factory", "opencode"), { recursive: true });
     this.#base = `http://127.0.0.1:${port}`;
     this.#auth = `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}`;
     this.#proc = spawn2(toolBin("opencode"), ["serve", "--hostname", "127.0.0.1", "--port", String(port)], {
@@ -31206,7 +31884,7 @@ class OpencodeRuntime {
       throw new Error(`opencode session create failed (${created.status}): ${JSON.stringify(created.data)}`);
     }
     const file = sessionContextFile(this.#opts.root, id);
-    mkdirSync8(join25(this.#opts.root, ".factory", "sessions"), { recursive: true });
+    mkdirSync8(join26(this.#opts.root, ".factory", "sessions"), { recursive: true });
     writeFileSync8(file, JSON.stringify({ sessionId: id, ...spec.context }, null, 2));
     return {
       id,
@@ -31225,8 +31903,15 @@ class OpencodeRuntime {
     return cut === -1 ? messages : messages.slice(0, cut);
   }
   async#awaitTurn(id, marker, stop) {
+    const pollMs = this.#opts.waitPollMs ?? WAIT_POLL_MS;
     for (;; ) {
-      await this.#api("POST", `/api/experimental/session/${id}/wait`, undefined, stop);
+      const poll = AbortSignal.any([stop, AbortSignal.timeout(pollMs)]);
+      try {
+        await this.#api("POST", `/api/experimental/session/${id}/wait`, undefined, poll);
+      } catch (err) {
+        if (stop.aborted || !poll.aborted)
+          throw err;
+      }
       const all = await this.#recent(id);
       const fresh = this.#since(all, marker);
       const markerSeen = marker === undefined || all.some((m) => m.id === marker);
@@ -31254,7 +31939,9 @@ class OpencodeRuntime {
         throw err;
       interrupted = true;
       await this.#api("POST", `/api/session/${id}/interrupt`);
-      await this.#api("POST", `/api/experimental/session/${id}/wait`);
+      try {
+        await this.#api("POST", `/api/experimental/session/${id}/wait`, undefined, AbortSignal.timeout(this.#opts.waitPollMs ?? WAIT_POLL_MS));
+      } catch {}
       messages = this.#since(await this.#recent(id), marker);
     }
     const after = await this.#session(id);
@@ -31425,8 +32112,8 @@ function gateExecutables(command) {
 }
 function onPath(name, dirs) {
   if (name.includes("/"))
-    return dirs.some((d) => existsSync20(join26(d, name)));
-  return dirs.some((d) => d !== "" && existsSync20(join26(d, name)));
+    return dirs.some((d) => existsSync20(join27(d, name)));
+  return dirs.some((d) => d !== "" && existsSync20(join27(d, name)));
 }
 function dirSize(path) {
   let total = 0;
@@ -31440,7 +32127,7 @@ function dirSize(path) {
       continue;
     }
     for (const name of entries) {
-      const child = join26(dir, name);
+      const child = join27(dir, name);
       const st = lstatSync2(child, { throwIfNoEntry: false });
       if (st === undefined || st.isSymbolicLink())
         continue;
@@ -31558,12 +32245,12 @@ async function checkRepos(c, root, config, uninitialised) {
   }
   const checkouts = [{ name: "AI repo", dir: root }];
   for (const repo of config.repos) {
-    const dir = join26(root, repo.path);
+    const dir = join27(root, repo.path);
     if (repo.path === ".") {
       ready.push(repo);
       continue;
     }
-    if (!existsSync20(join26(dir, ".git"))) {
+    if (!existsSync20(join27(dir, ".git"))) {
       if (!uninitialised.includes(repo.path))
         c.add("warn", repo.name, `${repo.path} is not a git checkout`);
       continue;
@@ -31584,12 +32271,36 @@ async function checkRepos(c, root, config, uninitialised) {
   }
   return ready;
 }
+function packageScript(dir, name) {
+  try {
+    const pkg = JSON.parse(readFileSync18(join27(dir, "package.json"), "utf8"));
+    const value = pkg.scripts?.[name];
+    return typeof value === "string" ? value : undefined;
+  } catch {
+    return;
+  }
+}
+var WRITE_FLAG = /(^|\s)(--write|--fix|--apply|-w)(\s|$)/;
+function checkWriteModeScripts(c, root, config, repos) {
+  c.in("gates");
+  for (const repo of repos.filter((r) => r.role === "code")) {
+    const dir = join27(root, repo.path);
+    for (const [type, name] of Object.entries(config.gates.scripts)) {
+      if (typeof name !== "string")
+        continue;
+      const script = packageScript(dir, name);
+      if (script !== undefined && WRITE_FLAG.test(script)) {
+        c.add("warn", `${repo.name} ${type} script`, `\`${name}\` writes files: ${script}`, `point gates.scripts.${type} at a check-only variant, or set gates.overrides.${repo.name}.${type}`);
+      }
+    }
+  }
+}
 function checkGates(c, root, config, repos) {
   c.in("gates");
   const rows = [];
   const pathDirs = (process.env.PATH ?? "").split(delimiter);
   for (const repo of repos.filter((r) => r.role === "code")) {
-    const dir = join26(root, repo.path);
+    const dir = join27(root, repo.path);
     const plan = resolveGates({
       config,
       repo,
@@ -31604,11 +32315,12 @@ function checkGates(c, root, config, repos) {
       rows.push({
         repo: repo.name,
         type: g.type,
+        ...g.name === undefined ? {} : { name: g.name },
         cwd: g.cwd,
         command: g.command,
         source: g.source
       });
-      const dirs = [...g.binDirs.map((b) => join26(dir, g.cwd, b)), join26(dir, g.cwd), ...pathDirs];
+      const dirs = [...g.binDirs.map((b) => join27(dir, g.cwd, b)), join27(dir, g.cwd), ...pathDirs];
       for (const exe of gateExecutables(g.command))
         if (!onPath(exe, dirs))
           missingTools.add(exe);
@@ -31636,10 +32348,10 @@ function looseTsconfig(dir, gates) {
   const gate = gates.find((g) => g.type === "types");
   if (gate === undefined || /--strict\b/.test(gate.command))
     return;
-  const rel = join26(gate.cwd, "tsconfig.json");
+  const rel = join27(gate.cwd, "tsconfig.json");
   let text;
   try {
-    text = readFileSync16(join26(dir, rel), "utf8");
+    text = readFileSync18(join27(dir, rel), "utf8");
   } catch {
     return;
   }
@@ -31648,14 +32360,81 @@ function looseTsconfig(dir, gates) {
     return;
   return tsconfig.compilerOptions?.strict === true ? undefined : rel;
 }
+function checkContext(c, root, config) {
+  c.in("context");
+  const paths = allInstructionPaths(config);
+  const missing = paths.filter((p) => !existsSync20(join27(root, p)));
+  if (missing.length > 0)
+    c.add("warn", "instructions", `missing: ${missing.join(", ")}`, "create the files or remove them from instructions");
+  else
+    c.add("ok", "instructions", `${paths.length} path(s) injected into sessions`);
+  const names = [
+    ...Object.values(config.skills.roles).flat(),
+    ...Object.values(config.skills.repos).flat()
+  ];
+  if (names.length > 0) {
+    const found = new Set;
+    for (const source of config.skills.sources) {
+      const dir = join27(root, source);
+      if (!existsSync20(dir))
+        continue;
+      try {
+        for (const name of readdirSync7(dir)) {
+          const skill = join27(dir, name, "SKILL.md");
+          if (existsSync20(skill))
+            found.add(name);
+        }
+      } catch {}
+    }
+    const unknown = [...new Set(names)].filter((n) => !found.has(n));
+    if (unknown.length > 0)
+      c.add("warn", "skills", `not found in ${config.skills.sources.join(", ")}: ${unknown.join(", ")}`, "add the skill under .opencode/skills/ or remove it from skills.roles");
+    else
+      c.add("ok", "skills", `${new Set(names).size} skill(s) configured`);
+  }
+  const legacy = join27(root, ".factory", "legacy");
+  if (existsSync20(legacy)) {
+    const stamps = readdirSync7(legacy).sort();
+    c.add("ok", "legacy setup", `${stamps.length} archived set(s) under .factory/legacy/`);
+  }
+}
+function checkRelease(c, root, config) {
+  c.in("release");
+  if (!config.release.detect) {
+    c.add("ok", "release", "detection disabled");
+    return;
+  }
+  const found = [];
+  for (const file of [
+    ".release-please-config.json",
+    ".goreleaser.yaml",
+    ".goreleaser.yml",
+    ".changeset/config.json",
+    ".github/workflows",
+    ".gitlab-ci.yml"
+  ]) {
+    if (existsSync20(join27(root, file)))
+      found.push(file);
+  }
+  for (const repo of config.repos.filter((r) => r.path !== ".")) {
+    for (const file of ["release-please-config.json", ".goreleaser.yaml", ".gitlab-ci.yml"]) {
+      if (existsSync20(join27(root, repo.path, file)))
+        found.push(`${repo.path}/${file}`);
+    }
+  }
+  if (found.length === 0)
+    c.add("ok", "release", "no release tooling detected");
+  else
+    c.add("ok", "release", `detected ${found.join(", ")}; commits stay local and the factory does not edit release workflows`);
+}
 function checkCaches(c, root) {
   c.in("caches");
-  const factory = join26(root, ".factory");
+  const factory = join27(root, ".factory");
   for (const [name, path] of [
-    ["dependency caches", join26(factory, "cache")],
-    ["worktrees", join26(factory, "worktrees")],
-    ["logs", join26(factory, "logs")],
-    ["backups", join26(factory, "backups")]
+    ["dependency caches", join27(factory, "cache")],
+    ["worktrees", join27(factory, "worktrees")],
+    ["logs", join27(factory, "logs")],
+    ["backups", join27(factory, "backups")]
   ]) {
     if (!existsSync20(path))
       continue;
@@ -31664,11 +32443,11 @@ function checkCaches(c, root) {
 }
 async function checkModels(c, root, config) {
   c.in("models");
-  const configured = Object.entries(config.models).filter((e) => typeof e[1] === "string");
-  const tmp = mkdtempSync4(join26(tmpdir4(), "ai-factory-doctor-"));
+  const configured = modelEntries(config);
+  const tmp = mkdtempSync4(join27(tmpdir4(), "ai-factory-doctor-"));
   const res = await exec([toolBin("opencode"), "models", "--standalone"], {
     cwd: root,
-    env: { ...serverEnv(root, config, "doctor"), OPENCODE_DB: join26(tmp, "opencode.db") },
+    env: { ...serverEnv(root, config, "doctor"), OPENCODE_DB: join27(tmp, "opencode.db") },
     replaceEnv: true,
     timeoutMs: 60000
   }).finally(() => rmSync8(tmp, { recursive: true, force: true }));
@@ -31684,7 +32463,7 @@ async function checkModels(c, root, config) {
     if (available.has(id))
       c.add("ok", role, model);
     else
-      c.add("fail", role, `${model} is not available to opencode`, `set the provider's credentials (env or \`opencode auth login\`) or change models.${role}`);
+      c.add("fail", role, `${model} is not available to opencode`, `set the provider's credentials (env or \`opencode auth login\`) or change the model in factory.config.jsonc`);
   }
 }
 var CODE_EXTENSIONS = new Set(Object.values(PROFILES).flatMap((p) => p.extensions));
@@ -31799,7 +32578,10 @@ async function runDoctor(root) {
   checkEnvironment(c, process.env);
   checkManaged(c, root, config);
   const repos = await checkRepos(c, root, config, uninitialised);
+  checkWriteModeScripts(c, root, config, repos);
   const gates = checkGates(c, root, config, repos);
+  checkContext(c, root, config);
+  checkRelease(c, root, config);
   checkCaches(c, root);
   await checkModels(c, root, config);
   await checkGraph(c, root, config, lock);
@@ -31822,11 +32604,12 @@ function print(io, report) {
   }
   if (report.gates.length > 0) {
     io.out("gate table (full mode; per task, scoped commands and affected tests are used)");
-    const width = Math.max(...report.gates.map((g) => `${g.repo} ${g.type}`.length));
+    const label = (g) => `${g.repo} ${g.name ?? g.type}`;
+    const width = Math.max(...report.gates.map((g) => label(g).length));
     for (const g of report.gates) {
       const where = g.cwd === "." ? "" : ` [${g.cwd}]`;
       const what = g.command ? `${g.command}  (${g.source})` : g.problem ?? "";
-      io.out(`  ${`${g.repo} ${g.type}`.padEnd(width)}${where}  ${what}`);
+      io.out(`  ${label(g).padEnd(width)}${where}  ${what}`);
     }
   }
   const fails = report.checks.filter((c) => c.status === "fail").length;
@@ -31878,14 +32661,14 @@ Exit code ${ExitCode.Precondition} when a check fails; warnings exit 0.`,
 
 // src/cli/commands/gate.ts
 import { existsSync as existsSync25, readdirSync as readdirSync9 } from "node:fs";
-import { join as join33 } from "node:path";
+import { join as join34 } from "node:path";
 
 // src/gates/run.ts
-import { delimiter as delimiter2, join as join30 } from "node:path";
+import { delimiter as delimiter2, join as join31 } from "node:path";
 
 // src/addons/shortcuts.ts
-import { readFileSync as readFileSync17 } from "node:fs";
-import { join as join27 } from "node:path";
+import { readFileSync as readFileSync19 } from "node:fs";
+import { join as join28 } from "node:path";
 var SHORTCUT = /(?:\/\/|#|\/\*|\*|--|<!--|;)\s*(?:shortcut|ponytail):\s*(.+?)\s*(?:\*\/|-->)?\s*$/i;
 function shortcutIn(line) {
   return line.match(SHORTCUT)?.[1];
@@ -31922,7 +32705,7 @@ async function newShortcuts(dir, base) {
 `).filter(Boolean)) {
     let text;
     try {
-      text = readFileSync17(join27(dir, file), "utf8");
+      text = readFileSync19(join28(dir, file), "utf8");
     } catch {
       continue;
     }
@@ -31990,8 +32773,8 @@ function compactOutput(raw, maxLines) {
 
 // src/gates/guard.ts
 import { createHash as createHash3 } from "node:crypto";
-import { existsSync as existsSync21, mkdirSync as mkdirSync9, readFileSync as readFileSync18, rmSync as rmSync9, writeFileSync as writeFileSync9 } from "node:fs";
-import { dirname as dirname6, join as join28 } from "node:path";
+import { existsSync as existsSync21, mkdirSync as mkdirSync9, readFileSync as readFileSync20, rmSync as rmSync9, writeFileSync as writeFileSync9 } from "node:fs";
+import { dirname as dirname6, join as join29 } from "node:path";
 var MISSING = "missing";
 async function dirtyPaths2(worktree) {
   const res = await git(["status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all"], {
@@ -32004,13 +32787,13 @@ async function dirtyPaths2(worktree) {
 function hashFile(abs) {
   if (!existsSync21(abs))
     return { hash: MISSING };
-  const content = readFileSync18(abs);
+  const content = readFileSync20(abs);
   return { hash: createHash3("sha256").update(content).digest("hex"), content };
 }
 async function snapshot(worktree) {
   const entries = new Map;
   for (const path of await dirtyPaths2(worktree))
-    entries.set(path, hashFile(join28(worktree, path)));
+    entries.set(path, hashFile(join29(worktree, path)));
   return { worktree, head: await gitOk(["rev-parse", "HEAD"], { cwd: worktree }), entries };
 }
 async function changedSince(before) {
@@ -32033,7 +32816,7 @@ async function restore(before, paths) {
     await gitOk(["reset", "-q", "--mixed", before.head], { cwd: before.worktree });
   }
   for (const path of paths.filter((p) => p !== "HEAD")) {
-    const abs = join28(before.worktree, path);
+    const abs = join29(before.worktree, path);
     const entry = before.entries.get(path);
     if (entry === undefined) {
       const tracked = await gitOk(["ls-files", "--", path], { cwd: before.worktree });
@@ -32052,19 +32835,19 @@ async function restore(before, paths) {
 
 // src/gates/install.ts
 import { existsSync as existsSync22, mkdirSync as mkdirSync10 } from "node:fs";
-import { join as join29 } from "node:path";
+import { join as join30 } from "node:path";
 function cacheEnv(root, repoName) {
-  const cache = join29(root, ".factory", "cache");
+  const cache = join30(root, ".factory", "cache");
   const env = {
-    npm_config_cache: join29(cache, "npm"),
-    npm_config_store_dir: join29(cache, "pnpm-store"),
-    BUN_INSTALL_CACHE_DIR: join29(cache, "bun"),
-    YARN_CACHE_FOLDER: join29(cache, "yarn"),
-    UV_CACHE_DIR: join29(cache, "uv"),
-    GOMODCACHE: join29(cache, "go", "mod"),
-    GOCACHE: join29(cache, "go", "build"),
-    GOLANGCI_LINT_CACHE: join29(cache, "golangci-lint"),
-    CARGO_TARGET_DIR: join29(cache, "cargo-target", repoName)
+    npm_config_cache: join30(cache, "npm"),
+    npm_config_store_dir: join30(cache, "pnpm-store"),
+    BUN_INSTALL_CACHE_DIR: join30(cache, "bun"),
+    YARN_CACHE_FOLDER: join30(cache, "yarn"),
+    UV_CACHE_DIR: join30(cache, "uv"),
+    GOMODCACHE: join30(cache, "go", "mod"),
+    GOCACHE: join30(cache, "go", "build"),
+    GOLANGCI_LINT_CACHE: join30(cache, "golangci-lint"),
+    CARGO_TARGET_DIR: join30(cache, "cargo-target", repoName)
   };
   for (const dir of Object.values(env))
     mkdirSync10(dir, { recursive: true });
@@ -32083,7 +32866,7 @@ async function installDeps(root, worktree, repo, timeoutMs = 15 * 60000) {
   const done = new Set;
   for (const profile of profilesFor(repoLanguages(repo))) {
     for (const dir of installDirs(profile, files)) {
-      const step = profile.install.find((s) => existsSync22(join29(worktree, dir, s.lockfile)));
+      const step = profile.install.find((s) => existsSync22(join30(worktree, dir, s.lockfile)));
       const key = `${dir}\x00${step?.command ?? profile.id}`;
       if (done.has(key))
         continue;
@@ -32098,7 +32881,7 @@ async function installDeps(root, worktree, repo, timeoutMs = 15 * 60000) {
         continue;
       }
       const res = await exec(["sh", "-c", step.command], {
-        cwd: join29(worktree, dir),
+        cwd: join30(worktree, dir),
         env,
         replaceEnv: true,
         timeoutMs
@@ -32120,22 +32903,30 @@ var FAILING = new Set(["fail", "missing", "not-check-only", "timeout"]);
 var TEST_GATES = new Set(["test", "testAffected"]);
 async function runOne(input, gate) {
   const before = await snapshot(input.worktree);
-  const bins = gate.binDirs.map((b) => join30(input.worktree, b));
+  const bins = gate.binDirs.map((b) => join31(input.worktree, b));
   const env = {
     ...agentProcessEnv(),
     ...cacheEnv(input.root, input.repo.name),
     ...QUIET_ENV,
+    ...gate.env ?? {},
     PATH: [...bins, process.env.PATH ?? ""].join(delimiter2)
   };
-  const argv = ["sh", "-c", gate.command];
-  const res = await exec(sandboxEnabled(input.config.security.sandbox) ? sandboxArgv(seatbeltProfile(checkoutPolicy(input.root, input.worktree, [join30(input.root, ".factory", "cache")])), argv) : argv, {
-    cwd: join30(input.worktree, gate.cwd),
+  const argv = [
+    "sh",
+    "-c",
+    gate.setup === undefined ? gate.command : `set -e
+${gate.setup}
+${gate.command}`
+  ];
+  const res = await exec(sandboxEnabled(input.config.security.sandbox) ? sandboxArgv(seatbeltProfile(checkoutPolicy(input.root, input.worktree, [join31(input.root, ".factory", "cache")])), argv) : argv, {
+    cwd: join31(input.worktree, gate.cwd),
     env,
     replaceEnv: true,
-    timeoutMs: input.timeoutMs ?? 15 * 60000
+    timeoutMs: gate.timeoutMs ?? input.timeoutMs ?? 15 * 60000
   });
   const base = {
     type: gate.type,
+    ...gate.name === undefined ? {} : { name: gate.name },
     cwd: gate.cwd,
     command: gate.command,
     source: gate.source,
@@ -32143,8 +32934,46 @@ async function runOne(input, gate) {
     durationMs: res.durationMs
   };
   const max = input.config.tokens.gateOutputMaxLines;
+  const raw = `${res.stdout}
+${res.stderr}`;
+  const output = redactProcess(compactOutput(raw, max));
   const modified = await changedSince(before);
-  if (modified.length > 0) {
+  const outputs = gate.outputs ?? [];
+  if (outputs.length > 0) {
+    const drifted = modified.filter((path) => outputs.some((glob) => opencodeGlobRegExp(glob).test(path)));
+    if (modified.length > 0)
+      await restore(before, modified);
+    if (res.timedOut)
+      return { ...base, status: "timeout", output: `gate timed out: \`${gate.command}\`` };
+    if (res.code !== 0)
+      return { ...base, status: "fail", output: output || `gate failed: \`${gate.command}\`` };
+    if (modified.includes("HEAD")) {
+      return {
+        ...base,
+        status: "fail",
+        output: `generated gate moved HEAD: \`${gate.command}\` must not commit (restored)`
+      };
+    }
+    const extraWrites = modified.filter((path) => !drifted.includes(path));
+    if (extraWrites.length > 0) {
+      return {
+        ...base,
+        status: "fail",
+        modified: extraWrites,
+        output: `generated gate wrote outside its outputs: ${extraWrites.join(", ")} (restored)`
+      };
+    }
+    if (drifted.length > 0) {
+      return {
+        ...base,
+        status: "fail",
+        modified: drifted,
+        output: `generated artifacts are stale: ${drifted.join(", ")} (regenerate and commit them)`
+      };
+    }
+    return { ...base, status: "pass", output: "" };
+  }
+  if (modified.length > 0 && gate.checkOnly !== false) {
     await restore(before, modified);
     return {
       ...base,
@@ -32155,12 +32984,10 @@ async function runOne(input, gate) {
   }
   if (res.timedOut)
     return { ...base, status: "timeout", output: `gate timed out: \`${gate.command}\`` };
-  const raw = `${res.stdout}
-${res.stderr}`;
   return {
     ...base,
     status: res.code === 0 ? "pass" : "fail",
-    output: res.code === 0 ? "" : redactProcess(compactOutput(raw, max))
+    output: res.code === 0 ? "" : output
   };
 }
 function relatedFiles(root, repoPath, changed) {
@@ -32243,13 +33070,13 @@ async function runGates(input) {
 
 // src/git/worktrees.ts
 import { existsSync as existsSync23, mkdirSync as mkdirSync11 } from "node:fs";
-import { dirname as dirname7, join as join31 } from "node:path";
+import { dirname as dirname7, join as join32 } from "node:path";
 var taskBranch = (id, task) => `${changeBranch(id)}--${task}`;
-var worktreePath = (root, id, repo, task) => join31(root, ".factory", "worktrees", id, repo, task);
+var worktreePath = (root, id, repo, task) => join32(root, ".factory", "worktrees", id, repo, task);
 async function addTaskWorktree(root, repoDir, repoName, id, task) {
   const path = worktreePath(root, id, repoName, task);
   const branch = taskBranch(id, task);
-  if (existsSync23(join31(path, ".git")))
+  if (existsSync23(join32(path, ".git")))
     return { path, branch, created: false };
   mkdirSync11(dirname7(path), { recursive: true });
   await gitOk(["worktree", "prune"], { cwd: repoDir });
@@ -32268,20 +33095,27 @@ async function removeTaskWorktree(repoDir, wt) {
 }
 
 // src/update/snapshot.ts
-import { cpSync, existsSync as existsSync24, mkdirSync as mkdirSync12, readdirSync as readdirSync8, readFileSync as readFileSync19, rmSync as rmSync10 } from "node:fs";
-import { join as join32 } from "node:path";
-var gateFile = (root, id) => join32(root, ".factory", "runs", id, "snapshot", "gates.json");
+import { cpSync, existsSync as existsSync24, mkdirSync as mkdirSync12, readdirSync as readdirSync8, readFileSync as readFileSync21, rmSync as rmSync10 } from "node:fs";
+import { join as join33 } from "node:path";
+var gateFile = (root, id) => join33(root, ".factory", "runs", id, "snapshot", "gates.json");
 function snapshotDefinitions(root, id, config, factoryVersion, replace = false) {
-  const agents = join32(root, ".opencode", "agents");
-  const target = join32(root, ".factory", "worktrees", id, ".opencode", "agents");
+  const snapshotRoot = join33(root, ".factory", "worktrees", id, ".opencode");
+  const agents = join33(root, ".opencode", "agents");
+  const target = join33(snapshotRoot, "agents");
+  const skills = join33(root, ".opencode", "skills");
+  const skillTarget = join33(snapshotRoot, "skills");
   if (replace) {
-    rmSync10(target, { recursive: true, force: true });
+    rmSync10(snapshotRoot, { recursive: true, force: true });
     rmSync10(gateFile(root, id), { force: true });
   }
   if (existsSync24(agents) && !existsSync24(target)) {
     mkdirSync12(target, { recursive: true });
     cpSync(agents, target, { recursive: true });
   }
+  if (existsSync24(skills) && !existsSync24(skillTarget)) {
+    mkdirSync12(skillTarget, { recursive: true });
+    cpSync(skills, skillTarget, { recursive: true });
+  }
   if (!existsSync24(gateFile(root, id))) {
     const tables = Object.fromEntries(Object.keys(PROFILES).map((l) => [l, PROFILES[l].gates]));
     writeJsonAtomic(gateFile(root, id), {
@@ -32293,15 +33127,15 @@ function snapshotDefinitions(root, id, config, factoryVersion, replace = false)
 }
 function loadGateSnapshot(root, id) {
   const file = gateFile(root, id);
-  return existsSync24(file) ? JSON.parse(readFileSync19(file, "utf8")) : undefined;
+  return existsSync24(file) ? JSON.parse(readFileSync21(file, "utf8")) : undefined;
 }
 function dropAgentSnapshot(root, id) {
-  const dir = join32(root, ".factory", "worktrees", id);
-  rmSync10(join32(dir, ".opencode"), { recursive: true, force: true });
+  const dir = join33(root, ".factory", "worktrees", id);
+  rmSync10(join33(dir, ".opencode"), { recursive: true, force: true });
   if (!existsSync24(dir))
     return;
   for (const repo of readdirSync8(dir)) {
-    const repoDir = join32(dir, repo);
+    const repoDir = join33(dir, repo);
     if (readdirSync8(repoDir).length === 0)
       rmSync10(repoDir, { recursive: true });
   }
@@ -32372,7 +33206,7 @@ async function baseOf2(dir, ref) {
   return res.stdout.trim();
 }
 function findTaskWorktree(root, id, task, repoName) {
-  const changeDir = join33(root, ".factory", "worktrees", id);
+  const changeDir = join34(root, ".factory", "worktrees", id);
   const repos = repoName ? [repoName] : existsSync25(changeDir) ? readdirSync9(changeDir) : [];
   const hits = repos.map((r) => ({ repo: r, dir: worktreePath(root, id, r, task) })).filter((h) => existsSync25(h.dir));
   const hit = hits[0];
@@ -32387,7 +33221,7 @@ function printReport(io, report) {
     const where = r.cwd === "." ? "" : ` [${r.cwd}]`;
     const what = r.command ? ` ${r.command}` : "";
     const time = r.durationMs > 0 ? ` ${(r.durationMs / 1000).toFixed(1)}s` : "";
-    io.out(`  ${MARK3[r.status]} ${r.type}${where}${what}${time}${r.status === "skipped" ? ` (${r.output})` : ""}`);
+    io.out(`  ${MARK3[r.status]} ${r.name ?? r.type}${where}${what}${time}${r.status === "skipped" ? ` (${r.output})` : ""}`);
     if (r.status !== "pass" && r.status !== "skipped" && r.output) {
       for (const line of r.output.split(`
 `))
@@ -32436,7 +33270,7 @@ var gateCommand = {
     } else {
       const repos = values.repo !== undefined ? [pick(values.repo)] : codeRepos;
       for (const repo of repos) {
-        const dir = join33(root, repo.path);
+        const dir = join34(root, repo.path);
         const branch = (await git(["branch", "--show-current"], { cwd: dir })).stdout.trim();
         if (branch !== `change/${id}`) {
           if (values.repo !== undefined) {
@@ -32471,7 +33305,7 @@ var gateCommand = {
 
 // src/cli/commands/graph.ts
 import { existsSync as existsSync26 } from "node:fs";
-import { join as join34 } from "node:path";
+import { join as join35 } from "node:path";
 var graphCommand = {
   name: "graph",
   summary: "Build or incrementally update the workspace graph",
@@ -32488,7 +33322,7 @@ The pipeline also updates it after every task merge, so this is rarely needed by
     const root = await findWorkspaceRoot(io.cwd);
     if (root === undefined)
       throw new PreconditionError("not inside a git repository");
-    if (!existsSync26(join34(root, LOCK_FILE)))
+    if (!existsSync26(join35(root, LOCK_FILE)))
       throw new PreconditionError("ai-factory is not installed here", ["run `ai-factory init`"]);
     const tool = await checkTool("graphify", root);
     if (!tool.ok)
@@ -32508,8 +33342,8 @@ The pipeline also updates it after every task merge, so this is rarely needed by
 };
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync27, writeFileSync as writeFileSync10 } from "node:fs";
-import { join as join35 } from "node:path";
+import { existsSync as existsSync28, writeFileSync as writeFileSync10 } from "node:fs";
+import { join as join37 } from "node:path";
 
 // src/config/render.ts
 var DEFAULT_MODELS = {
@@ -32521,6 +33355,72 @@ var DEFAULT_MODELS = {
   explorer: "anthropic/claude-haiku-5-5"
 };
 var json = (value) => JSON.stringify(value);
+function suggestedExtraGates(detection) {
+  const out = [];
+  for (const repo of detection.repos) {
+    if (repo.languages.includes("tauri")) {
+      out.push({
+        name: "ios-compile",
+        type: "types",
+        phases: ["task", "full"],
+        when: { changed: ["src-tauri/**"] },
+        command: "cargo check --manifest-path src-tauri/Cargo.toml --target aarch64-apple-ios"
+      });
+    }
+  }
+  for (const suite of detection.e2e) {
+    out.push({
+      name: `e2e-${suite.repo}`,
+      type: "test",
+      phases: ["full"],
+      command: suite.command
+    });
+  }
+  const wholeRepo = new Set(["docs", "kustomize", "chart", "verify"]);
+  for (const repo of detection.tasks) {
+    for (const name of repo.names) {
+      if (!wholeRepo.has(name))
+        continue;
+      out.push({
+        name: `${name}-${repo.repo}`,
+        type: "test",
+        phases: ["full"],
+        command: `task ${name}`
+      });
+    }
+  }
+  for (const contract of detection.contracts) {
+    if (contract.command === undefined)
+      continue;
+    if (contract.kind === "ipc") {
+      out.push({
+        name: "generated-bindings",
+        type: "test",
+        phases: ["task", "full"],
+        when: { changed: ["src-tauri/**", "src/**"] },
+        command: contract.command,
+        outputs: contract.outputs ?? [contract.path]
+      });
+    } else if (contract.kind === "crd") {
+      out.push({
+        name: "generated-crd",
+        type: "test",
+        phases: ["full"],
+        command: contract.command,
+        outputs: contract.outputs ?? [contract.path]
+      });
+    } else if (contract.kind === "generated") {
+      out.push({
+        name: "generated-artifacts",
+        type: "test",
+        phases: ["full"],
+        command: contract.command,
+        outputs: contract.outputs ?? [contract.path]
+      });
+    }
+  }
+  return out;
+}
 function renderInitialConfig(detection) {
   const repos = detection.repos.map((r) => `    ${json(toRepoConfig(r))}`).join(`,
 `);
@@ -32541,16 +33441,29 @@ ${repos}
   ],
 
   // opencode model ids ("provider/model") per role. contractReviewer defaults to reviewer.
+  // "roles", "repos" and "agents" can override these; the flat entries stay the fallback.
   "models": {
 ${models}
   },
 
+  // Project bars injected into every session. Add docs/security.md, docs/go.md, etc.
+  "instructions": ${json(detection.instructions)},
+  // Skills the agents should load first, from .opencode/skills or a custom source.
+  "skills": { "sources": [".opencode/skills"], "roles": {}, "repos": {} },
+  // MCP tool action patterns per role (e.g. "reviewer": ["mantine_*"]).
+  "mcp": { "roles": {} },
+  // Optional specialist agents and task routing by touched paths.
+  "agents": [],
+  "routing": [],
+
   "gates": {
     "maxRetries": 3,
     // Gate type -> script/target name looked up in package.json, Makefile, justfile, Taskfile.
     "scripts": { "format": "format:check", "lint": "lint", "types": "typecheck", "test": "test", "testAffected": "test:affected" },
     // Repo name -> gate type -> literal command; wins over scripts and profile defaults.
-    "overrides": {}
+    "overrides": {},
+    // Detected stack gates: iOS compile and generated-artifact drift. Edit or remove freely.
+    "extra": ${json(suggestedExtraGates(detection))}
   },
 
   // Proposed by detection: confirm providers and consumers.
@@ -32573,6 +33486,12 @@ ${contracts}
   "graph": { "exclude": ${json(DEFAULT_GRAPH_EXCLUDE)} },
   // Agent shells and gates run in an OS sandbox where available ("auto"; macOS sandbox-exec).
   "security": { "sandbox": "auto" },
+  // Task commits: "conventional" or "gitmoji"; scopes prefixes the repo name.
+  "commits": { "style": "conventional", "scopes": false },
+  // Clarification before design and the no-spec quick task.
+  "workflow": { "refine": true, "quick": { "enabled": true, "branchPrefix": "task/" } },
+  // Detect release-please, goreleaser, changesets and forge CI (read-only).
+  "release": { "detect": true },
 
   // Managed files the factory must never overwrite (workspace-relative paths).
   "unmanaged": []
@@ -32580,9 +33499,51 @@ ${contracts}
 `;
 }
 
+// src/workspace/legacy.ts
+import { existsSync as existsSync27, mkdirSync as mkdirSync13, readdirSync as readdirSync10, renameSync as renameSync6, rmdirSync as rmdirSync2 } from "node:fs";
+import { dirname as dirname8, join as join36 } from "node:path";
+var OPENSPEC_PREFIX = /^(opsx-|openspec-)/;
+function move(root, rel, stamp, archived) {
+  const from = join36(root, rel);
+  if (!existsSync27(from))
+    return;
+  const to = join36(root, ".factory", "legacy", stamp, rel);
+  mkdirSync13(dirname8(to), { recursive: true });
+  renameSync6(from, to);
+  archived.push(rel);
+}
+function moveEntries(root, dir, keep, stamp, archived) {
+  const abs = join36(root, dir);
+  if (!existsSync27(abs))
+    return;
+  for (const name of readdirSync10(abs)) {
+    if (keep(name))
+      continue;
+    move(root, `${dir}/${name}`, stamp, archived);
+  }
+  try {
+    if (readdirSync10(abs).length === 0)
+      rmdirSync2(abs);
+  } catch {}
+}
+function archiveLegacySetups(root, repoPaths) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const archived = [];
+  const dirs = [".opencode", ...repoPaths.filter((p) => p !== ".").map((p) => `${p}/.opencode`)];
+  for (const base of dirs) {
+    for (const name of ["agent", "agents"]) {
+      moveEntries(root, `${base}/${name}`, () => false, stamp, archived);
+    }
+    moveEntries(root, `${base}/commands`, (n) => OPENSPEC_PREFIX.test(n), stamp, archived);
+    moveEntries(root, `${base}/command`, () => false, stamp, archived);
+    moveEntries(root, `${base}/skills`, (n) => OPENSPEC_PREFIX.test(n), stamp, archived);
+  }
+  return { stamp, archived };
+}
+
 // src/cli/commands/init.ts
 var OPENSPEC_CONFIG = "openspec/config.yaml";
-var HELP4 = `Usage: ai-factory init [--force] [--allow-downgrade] [--no-commit] [--no-graph] [--json]
+var HELP4 = `Usage: ai-factory init [--plan] [--force] [--allow-downgrade] [--no-commit] [--no-graph] [--json]
 
 Installs the factory into the workspace: detects repos, languages and contracts, checks
 the tools, runs \`openspec init\` for opencode, renders agents, standards and config,
@@ -32591,6 +33552,7 @@ and commits the result in the AI repo. Safe to run again: an unchanged workspace
 no diff and no commit.
 
 Options:
+  --plan        Show what would be created, archived or replaced; write nothing
   --force       Overwrite existing files that ai-factory did not create
   --allow-downgrade  Let this (older) version rewrite a workspace a newer one installed
   --no-commit   Leave the changes uncommitted
@@ -32617,6 +33579,7 @@ var initCommand = {
       "allow-downgrade": { type: "boolean", default: false },
       "no-commit": { type: "boolean", default: false },
       "no-graph": { type: "boolean", default: false },
+      plan: { type: "boolean", default: false },
       json: { type: "boolean", default: false }
     });
     const root = await findWorkspaceRoot(io.cwd);
@@ -32635,7 +33598,7 @@ var initCommand = {
     if (missing.length > 0) {
       throw new PreconditionError("required tools are missing or unsupported", missing.map((t) => t.ok ? "" : `${t.tool}: ${t.problem} → ${t.fix}`));
     }
-    if (!values["no-commit"]) {
+    if (!values.plan && !values["no-commit"]) {
       const dirty = await dirtyInstallPaths(root, [CONFIG_FILE]);
       if (dirty.length > 0) {
         throw new PreconditionError("uncommitted changes in files that init commits", [
@@ -32644,14 +33607,33 @@ var initCommand = {
         ]);
       }
     }
-    const configPath = join35(root, CONFIG_FILE);
-    const newConfig = !existsSync27(configPath);
+    const configPath = join37(root, CONFIG_FILE);
+    const newConfig = !existsSync28(configPath);
     const detection = newConfig ? await detectWorkspace(root) : undefined;
-    const keepOpenspec = newConfig && !values.force && existsSync27(join35(root, OPENSPEC_CONFIG)) && readLock(root) === undefined;
+    const legacy = !values.plan && readLock(root) === undefined && detection !== undefined ? archiveLegacySetups(root, detection.repos.map((r) => r.path)) : undefined;
+    const keepOpenspec = newConfig && !values.force && existsSync28(join37(root, OPENSPEC_CONFIG)) && readLock(root) === undefined;
     const rendered = detection !== undefined ? renderInitialConfig(detection) : undefined;
     const configText = rendered !== undefined && keepOpenspec ? setJsonc(rendered, ["unmanaged"], [OPENSPEC_CONFIG]) : rendered;
     const config = configText !== undefined ? parseConfigText(configText, CONFIG_FILE) : loadConfig(root).config;
     const openspecFiles = await renderOpenspecTools(root);
+    if (values.plan) {
+      const planned = planSync(root, [...renderWorkspace(config, { root }), ...openspecFiles], readLock(root)?.managed ?? {}, { unmanaged: config.unmanaged, force: values.force });
+      if (values.json) {
+        io.out(JSON.stringify({
+          root,
+          newConfig,
+          notes: detection?.notes ?? [],
+          plan: planned.map(({ path, action }) => ({ path, action }))
+        }, null, 2));
+      } else {
+        io.out(`ai-factory ${FACTORY_VERSION} plan for ${root}`);
+        if (newConfig)
+          io.out(`would write ${CONFIG_FILE}`);
+        for (const change of planned)
+          io.out(`${REPORTED[change.action] ?? change.action}: ${change.path}`);
+      }
+      return ExitCode.Ok;
+    }
     planWorkspace(root, config, { force: values.force, tools: openspecFiles });
     if (configText !== undefined)
       writeFileSync10(configPath, configText);
@@ -32660,7 +33642,7 @@ var initCommand = {
       tools: openspecFiles
     });
     const commit = values["no-commit"] ? undefined : await commitInstall(root, `chore(factory): init v${FACTORY_VERSION}`);
-    const graph = values["no-graph"] ? undefined : await updateGraph(root, { full: !existsSync27(graphFile(root)) });
+    const graph = values["no-graph"] ? undefined : await updateGraph(root, { full: !existsSync28(graphFile(root)) });
     const changed = result.plan.filter((c) => REPORTED[c.action] !== undefined);
     if (values.json) {
       io.out(JSON.stringify({
@@ -32679,6 +33661,9 @@ var initCommand = {
     io.out(`tools: ${tools.map((t) => `${t.tool} ${t.ok ? t.version : "?"}`).join(", ")}`);
     for (const note of detection?.notes ?? [])
       io.out(`note: ${note}`);
+    if (legacy !== undefined && legacy.archived.length > 0) {
+      io.out(`legacy setup archived under .factory/legacy/${legacy.stamp}/ (${legacy.archived.length} path${legacy.archived.length === 1 ? "" : "s"})`);
+    }
     if (keepOpenspec)
       io.out(`kept your ${OPENSPEC_CONFIG} (listed under "unmanaged"); add the factory's workspace context to it by hand if you want the architect to see it`);
     if (newConfig)
@@ -32704,17 +33689,17 @@ var initCommand = {
 };
 
 // src/cli/commands/pipeline-commands.ts
-import { existsSync as existsSync33 } from "node:fs";
-import { join as join46 } from "node:path";
+import { existsSync as existsSync34, readFileSync as readFileSync27 } from "node:fs";
+import { join as join49, resolve as resolve5 } from "node:path";
 
 // src/pipeline/approve.ts
-import { mkdirSync as mkdirSync13, writeFileSync as writeFileSync11 } from "node:fs";
-import { dirname as dirname8 } from "node:path";
+import { mkdirSync as mkdirSync14, writeFileSync as writeFileSync11 } from "node:fs";
+import { dirname as dirname9 } from "node:path";
 
 // src/approval/approval.ts
 import { createHash as createHash4 } from "node:crypto";
-import { existsSync as existsSync28, readdirSync as readdirSync10, readFileSync as readFileSync20, statSync as statSync7 } from "node:fs";
-import { join as join36 } from "node:path";
+import { existsSync as existsSync29, readdirSync as readdirSync11, readFileSync as readFileSync22, statSync as statSync7 } from "node:fs";
+import { join as join38 } from "node:path";
 function parseApproval(value) {
   if (typeof value !== "object" || value === null)
     return;
@@ -32722,28 +33707,28 @@ function parseApproval(value) {
   const ok = typeof v.changeId === "string" && typeof v.approver === "string" && typeof v.specCommit === "string" && /^[0-9a-f]{40,64}$/.test(v.specCommit) && typeof v.hash === "string" && /^[0-9a-f]{64}$/.test(v.hash) && typeof v.approvedAt === "string";
   return ok ? value : undefined;
 }
-var changeDir = (root, id) => join36(root, "openspec", "changes", id);
-var approvalFile = (root, id) => join36(root, ".factory", "approvals", `${id}.json`);
+var changeDir = (root, id) => join38(root, "openspec", "changes", id);
+var approvalFile = (root, id) => join38(root, ".factory", "approvals", `${id}.json`);
 function filesUnder(dir, prefix = "") {
-  if (!existsSync28(dir))
+  if (!existsSync29(dir))
     return [];
-  return readdirSync10(dir).sort().flatMap((name) => {
+  return readdirSync11(dir).sort().flatMap((name) => {
     const rel = prefix === "" ? name : `${prefix}/${name}`;
-    const abs = join36(dir, name);
+    const abs = join38(dir, name);
     return statSync7(abs).isDirectory() ? filesUnder(abs, rel) : [rel];
   });
 }
 function approvedFiles(root, id) {
   const dir = changeDir(root, id);
-  const top = ["proposal.md", "design.md", "tasks.md"].filter((f) => existsSync28(join36(dir, f)));
-  const specs = filesUnder(join36(dir, "specs"), "specs").filter((f) => f.endsWith(".md"));
+  const top = ["proposal.md", "design.md", "tasks.md"].filter((f) => existsSync29(join38(dir, f)));
+  const specs = filesUnder(join38(dir, "specs"), "specs").filter((f) => f.endsWith(".md"));
   return [...top, ...specs].sort();
 }
 function specHash(root, id) {
   const hash = createHash4("sha256");
   const dir = changeDir(root, id);
   for (const rel of approvedFiles(root, id)) {
-    let content = readFileSync20(join36(dir, rel), "utf8").replace(/\r\n/g, `
+    let content = readFileSync22(join38(dir, rel), "utf8").replace(/\r\n/g, `
 `);
     if (rel === "tasks.md")
       content = normalizeCheckboxes(content);
@@ -32753,10 +33738,10 @@ function specHash(root, id) {
 }
 function readApproval(root, id) {
   const file = approvalFile(root, id);
-  if (!existsSync28(file))
+  if (!existsSync29(file))
     return;
   try {
-    return parseApproval(JSON.parse(readFileSync20(file, "utf8")));
+    return parseApproval(JSON.parse(readFileSync22(file, "utf8")));
   } catch {
     return;
   }
@@ -32774,12 +33759,12 @@ function checkApprovalHash(root, id) {
 }
 
 // src/pipeline/design.ts
-import { existsSync as existsSync30 } from "node:fs";
-import { join as join39 } from "node:path";
+import { existsSync as existsSync31 } from "node:fs";
+import { join as join41 } from "node:path";
 
 // src/git/branching.ts
-import { existsSync as existsSync29 } from "node:fs";
-import { join as join37 } from "node:path";
+import { existsSync as existsSync30 } from "node:fs";
+import { join as join39 } from "node:path";
 async function switchToChangeBranch(dir, branch, start) {
   if (await currentBranch(dir) === branch)
     return { created: false };
@@ -32816,8 +33801,8 @@ async function trackedBranch(root, path) {
   return;
 }
 async function branchSubmodule(root, repo, id) {
-  const dir = join37(root, repo.path);
-  if (!existsSync29(join37(dir, ".git"))) {
+  const dir = join39(root, repo.path);
+  if (!existsSync30(join39(dir, ".git"))) {
     throw new PreconditionError(`submodule ${repo.path} is not initialised`, [
       `run \`git submodule update --init ${repo.path}\``
     ]);
@@ -32889,7 +33874,7 @@ function decisionValues(handoff) {
 }
 
 // src/pipeline/context.ts
-import { join as join38 } from "node:path";
+import { join as join40 } from "node:path";
 
 // src/runtime/rate-limit.ts
 function sleep(ms, signal) {
@@ -32987,7 +33972,7 @@ class Pipeline {
     return repo;
   }
   repoDir(repo) {
-    return join38(this.root, repo.path);
+    return join40(this.root, repo.path);
   }
   out(line) {
     this.deps.out(line);
@@ -33026,14 +34011,31 @@ class Pipeline {
     }
   }
   async#call(call, signal) {
-    const model = modelFor(this.config, call.modelRole);
-    const provider = model.split("/")[0] ?? model;
-    const raw = await this.deps.runtime.open({
-      agent: call.agent,
-      model,
-      title: call.title,
-      context: { ...call.context, changeId: call.changeId, role: call.role }
+    const first = modelFor(this.config, call.modelRole, {
+      ...call.context.repo === undefined ? {} : { repo: call.context.repo },
+      agent: call.agent
     });
+    let model = first;
+    let raw;
+    let lastError;
+    for (const candidate of [first, ...this.config.models.fallback]) {
+      try {
+        raw = await this.deps.runtime.open({
+          agent: call.agent,
+          model: candidate,
+          title: call.title,
+          context: { ...call.context, changeId: call.changeId, role: call.role }
+        });
+        model = candidate;
+        break;
+      } catch (err) {
+        lastError = err;
+      }
+    }
+    if (raw === undefined) {
+      throw lastError instanceof Error ? lastError : new Error(`could not open a session for ${call.agent}`);
+    }
+    const provider = model.split("/")[0] ?? model;
     const session = limited(raw, this.limiter, provider);
     let turn = await promptForHandoff(session, call.prompt, signal);
     let usage = turn.usage;
@@ -33113,6 +34115,8 @@ ${text}`).join(`
 
 `);
   const contracts = input.contracts.map((c) => `- ${c.kind} ${c.provider}:${c.path} → ${c.consumers.join(", ") || "no consumers"}`);
+  const instructions = input.instructions === undefined || input.instructions.length === 0 ? "- none configured" : input.instructions.map((p) => `- \`${p}\``).join(`
+`);
   return `Write the OpenSpec change \`${input.id}\` in \`openspec/changes/${input.id}/\` (the folder exists; fill proposal.md, specs/<capability>/spec.md, design.md and tasks.md).
 
 Request:
@@ -33128,6 +34132,9 @@ Contracts:
 ${contracts.length > 0 ? contracts.join(`
 `) : "- none configured"}
 
+Project instructions (read these before writing the spec):
+${instructions}
+
 Explorer findings:
 ${explored || "(none)"}
 
@@ -33169,18 +34176,28 @@ ${conflicts.map((f) => `- ${f}`).join(`
 Resolve every conflict so both changes are kept and correct. Remove all conflict markers. Do not run git commands that change history; the factory continues the rebase. End with a handoff (\`task: "${task.id}"\`).`;
 }
 function reviewPrompt(input) {
+  const instructions = input.instructions === undefined || input.instructions.length === 0 ? "" : `
+Project instructions (read these before judging the diff; paths are relative to this checkout):
+${input.instructions.map((p) => `- \`${p}\``).join(`
+`)}
+`;
   return `Review repo \`${input.repo.name}\` for this change: \`git diff ${input.base}..${input.head}\` (run it in this directory), plus the code around it.
-Standards in force: ${input.profiles.join(", ") || "none"} (see .opencode/standards/ in the workspace).
-
+Standards in force: ${input.profiles.join(", ") || "none"} (the full standards are in the workspace's .opencode/standards/).
+${instructions}
 Spec of the change:
 ${input.spec}
 
 Use \`task: "review:${input.repo.name}"\`.`;
 }
 function testerPrompt(input) {
+  const instructions = input.instructions === undefined || input.instructions.length === 0 ? "" : `
+Project instructions (follow these test conventions; paths are workspace-relative, so open \`$AI_FACTORY_WORKSPACE/<path>\` from a worktree):
+${input.instructions.map((p) => `- \`${p}\``).join(`
+`)}
+`;
   return `Task ${input.task.id}: make sure every scenario below that concerns repo \`${input.task.repo}\` has a test.
 You may only edit test files (${input.testGlobs.join(", ")}).
-
+${instructions}
 Spec of the change:
 ${input.spec}
 
@@ -33203,6 +34220,25 @@ function findingPack(f) {
 - Impact if skipped: ${f.impact}
 ${f.file ? `- Location: ${f.file}${f.line ? `:${f.line}` : ""}` : ""}`;
 }
+function quickPrompt(input) {
+  return `Quick task in repo \`${input.repo.name}\` (no OpenSpec change):
+"""
+${input.task}
+"""
+Make the smallest complete change that satisfies the task. You may edit any file in this
+repository except the factory-managed files and secrets. Tests for the change belong with it.
+The factory runs the repository's gates after you finish; report the result in your handoff.
+Use \`task: "quick"\`.`;
+}
+function quickReviewPrompt(input) {
+  return `Review the uncommitted quick-task change in repo \`${input.repo.name}\`:
+"""
+${input.task}
+"""
+Run \`git diff\` in this repository and read the code around the changes. Report only real
+bugs, security problems, missing tests for risky logic, and contract/convention violations.
+Use \`task: "quick-review"\` and the normal findings handoff.`;
+}
 function contractReviewPrompt(input) {
   return `One cross-repo review of the contracts this change touches. The deterministic contract gate already ran:
 ${input.contracts.map((c) => c.summary).join(`
@@ -33217,14 +34253,14 @@ Report only real mismatches between providers and consumers as findings, with \`
 
 // src/pipeline/design.ts
 function specDir(p, draft) {
-  return draft === undefined ? p.root : join39(p.root, draft);
+  return draft === undefined ? p.root : join41(p.root, draft);
 }
 function slug(text) {
   const words = text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter(Boolean).slice(0, 5);
   return words.join("-") || "change";
 }
 function uniqueId(p, wanted) {
-  const taken = (id) => loadRun(p.root, id) !== undefined || existsSync30(join39(p.root, "openspec", "changes", id)) || existsSync30(join39(p.root, ".factory", "drafts", id));
+  const taken = (id) => loadRun(p.root, id) !== undefined || existsSync31(join41(p.root, "openspec", "changes", id)) || existsSync31(join41(p.root, ".factory", "drafts", id));
   let id = wanted;
   for (let n = 2;taken(id); n++)
     id = `${wanted}-${n}`;
@@ -33239,8 +34275,8 @@ async function branchForDesign(p, id) {
   }
   const base = loadRun(p.root, occupiedBy)?.branches["."]?.base ?? await revParse(p.root, "HEAD");
   const draft = `.factory/drafts/${id}`;
-  if (!existsSync30(join39(p.root, draft))) {
-    const args = await refExists(p.root, `refs/heads/${changeBranch(id)}`) ? ["worktree", "add", "-q", join39(p.root, draft), changeBranch(id)] : ["worktree", "add", "-q", "-b", changeBranch(id), join39(p.root, draft), base];
+  if (!existsSync31(join41(p.root, draft))) {
+    const args = await refExists(p.root, `refs/heads/${changeBranch(id)}`) ? ["worktree", "add", "-q", join41(p.root, draft), changeBranch(id)] : ["worktree", "add", "-q", "-b", changeBranch(id), join41(p.root, draft), base];
     await gitOk(args, { cwd: p.root });
   }
   return { base, draft };
@@ -33348,7 +34384,8 @@ async function design(p, id) {
       request: run.request,
       explorations,
       repos: p.codeRepos(),
-      contracts: p.config.contracts
+      contracts: p.config.contracts,
+      instructions: allInstructionPaths(p.config)
     }),
     retry: async (_handoff, attempt) => {
       if (attempt > p.config.gates.maxRetries)
@@ -33401,7 +34438,7 @@ async function approve(p, id) {
   await p.update(id, (d) => {
     assertApprovable(id, d);
     const file = approvalFile(p.root, id);
-    mkdirSync13(dirname8(file), { recursive: true });
+    mkdirSync14(dirname9(file), { recursive: true });
     writeFileSync11(file, `${JSON.stringify(approval, null, 2)}
 `);
     d.phase = "queued";
@@ -33459,15 +34496,15 @@ async function verifyApproval(p, id, dir) {
 }
 
 // src/pipeline/contracts.ts
-import { mkdirSync as mkdirSync15, writeFileSync as writeFileSync13 } from "node:fs";
-import { join as join43 } from "node:path";
+import { mkdirSync as mkdirSync16, writeFileSync as writeFileSync13 } from "node:fs";
+import { join as join45 } from "node:path";
 
 // src/contracts/gate.ts
 var import_ajv = __toESM(require_ajv(), 1);
 var import__2020 = __toESM(require__2020(), 1);
 var import_ajv_formats = __toESM(require_dist(), 1);
-import { readFileSync as readFileSync21 } from "node:fs";
-import { join as join40 } from "node:path";
+import { readFileSync as readFileSync23 } from "node:fs";
+import { join as join42 } from "node:path";
 
 // src/contracts/schema-diff.ts
 var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -34003,7 +35040,7 @@ var SOURCE = /\.(ts|tsx|js|jsx|mjs|cjs|go|py|rs|java|kt|swift|rb|php|cs|vue|svel
 function consumerSources(dir) {
   return listFiles(dir, { maxDepth: 8, maxFiles: 5000 }).filter((f) => SOURCE.test(f.path) && f.size <= 256 * 1024).map((f) => {
     try {
-      return readFileSync21(join40(dir, f.path), "utf8");
+      return readFileSync23(join42(dir, f.path), "utf8");
     } catch {
       return "";
     }
@@ -34027,21 +35064,50 @@ async function runValidate(command, dir, contractAbs, maxLines) {
 ${compactOutput(`${res.stdout}
 ${res.stderr}`, maxLines)}`;
 }
-function repoOf(config, name) {
+function repoOf2(config, name) {
   const repo = config.repos.find((r) => r.name === name);
   if (repo === undefined)
     throw new Error(`unknown repo ${name}`);
   return repo;
 }
 async function checkContract(input, contract) {
-  const provider = repoOf(input.config, contract.provider);
-  const providerDir = join40(input.root, provider.path);
+  const provider = repoOf2(input.config, contract.provider);
+  const providerDir = join42(input.root, provider.path);
   const head = await headRef(providerDir, input.id);
   const base = input.bases[provider.name] ?? head;
   const breaking = [];
   const consumerIssues = [];
   const notes = [];
-  if (contract.kind === "proto") {
+  if (contract.kind === "generated" || contract.kind === "crd" || contract.kind === "ipc" || contract.kind === "custom") {
+    if (contract.command === undefined) {
+      consumerIssues.push(`${contract.kind} contract has no command`);
+    } else if (contract.kind === "custom") {
+      const issue = await runValidate(contract.command, providerDir, join42(providerDir, contract.path), input.gateOutputMaxLines);
+      if (issue)
+        consumerIssues.push(`${provider.name}: ${issue}`);
+    } else {
+      const before = await snapshot(providerDir);
+      const res = await exec(["sh", "-c", contract.command], {
+        cwd: providerDir,
+        env: { CI: "1", NO_COLOR: "1" },
+        timeoutMs: 15 * 60000
+      });
+      const modified = await changedSince(before);
+      if (modified.length > 0)
+        await restore(before, modified);
+      if (res.code !== 0) {
+        consumerIssues.push(`\`${contract.command}\` failed:
+${compactOutput(`${res.stdout}
+${res.stderr}`, input.gateOutputMaxLines)}`);
+      } else {
+        const outputs = contract.outputs ?? [contract.path];
+        const drifted = modified.filter((file) => outputs.some((glob) => file === glob || file.startsWith(`${glob.replace(/\/$/, "")}/`) || opencodeGlobRegExp(glob).test(file)));
+        if (drifted.length > 0) {
+          consumerIssues.push(`generated artifacts are stale: ${drifted.join(", ")}; regenerate and commit them`);
+        }
+      }
+    }
+  } else if (contract.kind === "proto") {
     const oldFiles = await filesAt(providerDir, base, contract.path, ".proto");
     const newFiles = await filesAt(providerDir, head, contract.path, ".proto");
     if (newFiles.length === 0)
@@ -34064,7 +35130,7 @@ async function checkContract(input, contract) {
       else {
         breaking.push(...diffOpenApi(oldDoc, newDoc));
         for (const consumer of contract.consumers) {
-          const dir = join40(input.root, repoOf(input.config, consumer).path);
+          const dir = join42(input.root, repoOf2(input.config, consumer).path);
           for (const path of referencedRemovedPaths(oldDoc, newDoc, consumerSources(dir))) {
             consumerIssues.push(`${consumer} still references ${path}, which the new contract no longer has`);
           }
@@ -34096,8 +35162,8 @@ async function checkContract(input, contract) {
     }
   }
   for (const [consumer, command] of Object.entries(contract.validate ?? {})) {
-    const dir = join40(input.root, repoOf(input.config, consumer).path);
-    const issue = await runValidate(command, dir, join40(providerDir, contract.path), input.gateOutputMaxLines);
+    const dir = join42(input.root, repoOf2(input.config, consumer).path);
+    const issue = await runValidate(command, dir, join42(providerDir, contract.path), input.gateOutputMaxLines);
     if (issue)
       consumerIssues.push(`${consumer}: ${issue}`);
   }
@@ -34128,23 +35194,23 @@ function touchedContracts(config, repos) {
 
 // src/pipeline/implement.ts
 import {
-  existsSync as existsSync31,
-  mkdirSync as mkdirSync14,
-  readdirSync as readdirSync11,
-  readFileSync as readFileSync23,
+  existsSync as existsSync32,
+  mkdirSync as mkdirSync15,
+  readdirSync as readdirSync12,
+  readFileSync as readFileSync25,
   rmSync as rmSync11,
   statSync as statSync8,
   writeFileSync as writeFileSync12
 } from "node:fs";
-import { join as join42 } from "node:path";
+import { join as join44 } from "node:path";
 
 // src/gates/definitions.ts
-import { readFileSync as readFileSync22 } from "node:fs";
-import { join as join41 } from "node:path";
+import { readFileSync as readFileSync24 } from "node:fs";
+import { join as join43 } from "node:path";
 var HOSTS = ["package.json", "Makefile", "justfile", "Justfile", "Taskfile.yml", "Taskfile.yaml"];
 function current(dir, file) {
   try {
-    return readFileSync22(join41(dir, file), "utf8");
+    return readFileSync24(join43(dir, file), "utf8");
   } catch {
     return;
   }
@@ -34323,7 +35389,7 @@ class GraphUpdater {
 }
 
 // src/policy/scope.ts
-import { isAbsolute as isAbsolute2, normalize, relative as relative5, resolve as resolve4 } from "node:path";
+import { isAbsolute as isAbsolute2, normalize, relative as relative6, resolve as resolve4 } from "node:path";
 
 // src/policy/paths.ts
 var PROTECTED = [
@@ -34378,7 +35444,7 @@ var architectDirs = (changeId) => [
 var IMPLEMENTING_ROLES = new Set(["implementer", "tester"]);
 function checkEdit(ctx, path, approval) {
   const abs = normalize(isAbsolute2(path) ? path : resolve4(ctx.directory, path));
-  const rel = relative5(ctx.directory, abs);
+  const rel = relative6(ctx.directory, abs);
   if (rel === "" || rel.startsWith("..") || isAbsolute2(rel)) {
     return {
       allowed: false,
@@ -34753,6 +35819,25 @@ class Scheduler {
   }
 }
 
+// src/tasks/routing.ts
+function agentForTask(config, repo, touches) {
+  for (const rule of config.routing) {
+    const agent = config.agents.find((a) => a.id === rule.agent);
+    if (agent === undefined || agent.phase !== "implementer")
+      continue;
+    const hit = rule.paths.some((path) => touches.some((touch) => {
+      try {
+        return opencodeGlobRegExp(path).test(touch) || opencodeGlobRegExp(touch).test(path);
+      } catch {
+        return false;
+      }
+    }));
+    if (hit)
+      return { agent: agent.id, role: "implementer", custom: true };
+  }
+  return { agent: `implementer-${repo}`, role: "implementer", custom: false };
+}
+
 // src/util/cap.ts
 var CHARS_PER_TOKEN = 4;
 var estimateTokens = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);
@@ -34775,7 +35860,7 @@ function gateDefinitions(p, id) {
     return { config: p.config };
   return { config: { ...p.config, gates: snapshot.gates }, gateTables: snapshot.tables };
 }
-var packPath = (root, id, task) => join42(root, ".factory", "context", id, `${task}.md`);
+var packPath = (root, id, task) => join44(root, ".factory", "context", id, `${task}.md`);
 async function activate(p, id) {
   const claim = await claimActive(p.root, id);
   if (claim.status === "busy") {
@@ -34792,7 +35877,7 @@ async function activate(p, id) {
   const run = p.run(id);
   const branch = changeBranch(id);
   if (run.draft !== undefined) {
-    await gitOk(["worktree", "remove", join42(p.root, run.draft)], { cwd: p.root });
+    await gitOk(["worktree", "remove", join44(p.root, run.draft)], { cwd: p.root });
     await p.update(id, (d) => {
       delete d.draft;
     });
@@ -34824,18 +35909,18 @@ async function activate(p, id) {
   return { status: "active" };
 }
 function specText(p, id) {
-  const dir = join42(p.root, "openspec", "changes", id, "specs");
-  if (!existsSync31(dir))
+  const dir = join44(p.root, "openspec", "changes", id, "specs");
+  if (!existsSync32(dir))
     return "";
   const out = [];
   const walk = (d, rel) => {
-    for (const name of readdirSync11(d).sort()) {
-      const abs = join42(d, name);
+    for (const name of readdirSync12(d).sort()) {
+      const abs = join44(d, name);
       if (statSync8(abs).isDirectory())
         walk(abs, `${rel}${name}/`);
       else if (name.endsWith(".md"))
         out.push(`### specs/${rel}${name}
-${readFileSync23(abs, "utf8").trim()}`);
+${readFileSync25(abs, "utf8").trim()}`);
     }
   };
   walk(dir, "");
@@ -34861,10 +35946,10 @@ function cappedSpec(p, id) {
 async function ensureContextPacks(p, id) {
   const cap = p.config.tokens.contextPackMaxTokens;
   const tasks = p.run(id).tasks.filter((t) => t.kind === "task" && t.status === "pending");
-  const missing = tasks.filter((t) => !existsSync31(packPath(p.root, id, t.id)));
+  const missing = tasks.filter((t) => !existsSync32(packPath(p.root, id, t.id)));
   if (missing.length > 0) {
     p.out(`▶ context packs (${missing.length})`);
-    mkdirSync14(join42(p.root, ".factory", "context", id), { recursive: true });
+    mkdirSync15(join44(p.root, ".factory", "context", id), { recursive: true });
     const res = await p.call({
       changeId: id,
       agent: "architect",
@@ -34883,7 +35968,7 @@ async function ensureContextPacks(p, id) {
   }
   for (const t of tasks) {
     const file = packPath(p.root, id, t.id);
-    const text = existsSync31(file) ? capPack(readFileSync23(file, "utf8"), cap) : fallbackPack(p, id, t, cap);
+    const text = existsSync32(file) ? capPack(readFileSync25(file, "utf8"), cap) : fallbackPack(p, id, t, cap);
     writeFileSync12(file, text);
   }
 }
@@ -35017,7 +36102,7 @@ class PipelineTaskRunner {
         await gitOk(["checkout", "-q", "HEAD", "--", v.path], { cwd: dir });
       else {
         await git(["rm", "-q", "--cached", "--ignore-unmatch", "--", v.path], { cwd: dir });
-        rmSync11(join42(dir, v.path), { force: true, recursive: true });
+        rmSync11(join44(dir, v.path), { force: true, recursive: true });
       }
     }
     return violations.map((v) => `${v.path}: ${v.reason}`);
@@ -35043,14 +36128,15 @@ class PipelineTaskRunner {
           t.installed = true;
       });
     }
-    const pack = existsSync31(packPath(this.p.root, this.id, task.id)) ? readFileSync23(packPath(this.p.root, this.id, task.id), "utf8") : "";
+    const pack = existsSync32(packPath(this.p.root, this.id, task.id)) ? readFileSync25(packPath(this.p.root, this.id, task.id), "utf8") : "";
     const gates = gateCommands(this.p, task, dir);
     const isTest = task.kind === "test";
     const prompt = isTest ? testerPrompt({
       task,
       spec: cappedSpec(this.p, this.id),
       testGlobs: this.#context(task, dir).testGlobs ?? [],
-      gates
+      gates,
+      instructions: instructionPaths(this.p.config, task.repo)
     }) : taskPrompt({
       task,
       pack,
@@ -35058,9 +36144,10 @@ class PipelineTaskRunner {
       ...ctx.feedback === undefined ? {} : { feedback: ctx.feedback }
     });
     const headBefore = (await gitOk(["rev-parse", "HEAD"], { cwd: dir })).trim();
+    const routed = agentForTask(this.p.config, task.repo, task.touches);
     const res = await this.p.call({
       changeId: this.id,
-      agent: isTest ? "tester" : `implementer-${task.repo}`,
+      agent: isTest ? "tester" : routed.agent,
       role: isTest ? "tester" : "implementer",
       modelRole: isTest ? "tester" : "implementer",
       context: this.#context(task, dir),
@@ -35111,7 +36198,7 @@ ${redefined.join(`
     }
     const report = await this.#gates(task, dir);
     if (!report.passed) {
-      const output = report.results.filter((r) => r.status !== "pass" && r.status !== "skipped").map((r) => `[${r.type}] ${r.command ?? ""}
+      const output = report.results.filter((r) => r.status !== "pass" && r.status !== "skipped").map((r) => `[${r.name ?? r.type}] ${r.command ?? ""}
 ${r.output}`).join(`
 
 `);
@@ -35122,7 +36209,10 @@ ${output}` : output
       };
     }
     const type = task.kind === "test" ? "test" : task.kind === "task" ? undefined : "fix";
-    const commit = await commitTask(dir, this.id, task.id, task.title, type);
+    const commit = await commitTask(dir, this.id, task.id, task.title, type, {
+      style: this.p.config.commits.style,
+      ...this.p.config.commits.scopes ? { scope: task.repo } : {}
+    });
     return { status: "passed", ...commit ? { commit } : {} };
   }
   async merge(task) {
@@ -35137,7 +36227,7 @@ ${output}` : output
     }
     const branch = taskBranch(this.id, task.id);
     const path = worktreePath(this.p.root, this.id, repo.name, task.id);
-    if (!existsSync31(path)) {
+    if (!existsSync32(path)) {
       const merged = !await refExists(repoDir, `refs/heads/${branch}`) || (await git(["merge-base", "--is-ancestor", branch, changeBranch(this.id)], {
         cwd: repoDir
       })).code === 0;
@@ -35162,16 +36252,17 @@ ${output}` : output
     if (outcome.status === "conflict")
       return { status: "conflict", conflicts: outcome.conflicts };
     const report = this.#lastRegate.get(task.id);
-    const output = report?.results.filter((r) => r.status !== "pass" && r.status !== "skipped").map((r) => `[${r.type}] ${r.output}`).join(`
+    const output = report?.results.filter((r) => r.status !== "pass" && r.status !== "skipped").map((r) => `[${r.name ?? r.type}] ${r.output}`).join(`
 
 `) ?? "gates failed after the rebase";
     return { status: "gates-failed", output };
   }
   async resolveConflict(task, conflicts) {
     const path = worktreePath(this.p.root, this.id, task.repo, task.id);
+    const routed = agentForTask(this.p.config, task.repo, task.touches);
     const res = await this.p.call({
       changeId: this.id,
-      agent: `implementer-${task.repo}`,
+      agent: routed.agent,
       role: "implementer",
       modelRole: "implementer",
       context: { ...this.#context(task, path), touches: ["**"] },
@@ -35183,8 +36274,8 @@ ${output}` : output
     if (res.handoff?.status !== "done")
       return false;
     for (const file of conflicts) {
-      const abs = join42(path, file);
-      if (existsSync31(abs) && /^(<{7}|={7}|>{7})( |$)/m.test(readFileSync23(abs, "utf8")))
+      const abs = join44(path, file);
+      if (existsSync32(abs) && /^(<{7}|={7}|>{7})( |$)/m.test(readFileSync25(abs, "utf8")))
         return false;
     }
     return true;
@@ -35193,7 +36284,7 @@ ${output}` : output
     const repo = this.p.repo(task.repo);
     const repoDir = this.p.repoDir(repo);
     const path = worktreePath(this.p.root, this.id, repo.name, task.id);
-    if (existsSync31(path)) {
+    if (existsSync32(path)) {
       await abortRebase(path);
       await gitOk(["worktree", "remove", "--force", path], { cwd: repoDir });
     }
@@ -35257,7 +36348,7 @@ function addFixTask(p, draft, id, task) {
   });
   recordTask(state, "added", "contract-fix");
   draft.tasks.push(state);
-  mkdirSync15(join43(p.root, ".factory", "context", id), { recursive: true });
+  mkdirSync16(join45(p.root, ".factory", "context", id), { recursive: true });
   writeFileSync13(packPath(p.root, id, task.id), task.pack);
 }
 async function contractPhase(p, id) {
@@ -35369,11 +36460,11 @@ ${summarize(r)}
 }
 
 // src/pipeline/finish.ts
-import { existsSync as existsSync32, mkdirSync as mkdirSync16, readdirSync as readdirSync12, readFileSync as readFileSync24, writeFileSync as writeFileSync14 } from "node:fs";
-import { join as join45 } from "node:path";
+import { existsSync as existsSync33, mkdirSync as mkdirSync17, readdirSync as readdirSync13, readFileSync as readFileSync26, writeFileSync as writeFileSync14 } from "node:fs";
+import { join as join47 } from "node:path";
 
 // src/git/pointers.ts
-import { join as join44 } from "node:path";
+import { join as join46 } from "node:path";
 var PROVISIONAL_SUBJECT = (id) => `chore(submodules): bump for ${id} [provisional]`;
 async function bumpPointers(root, id, repos) {
   const paths = repos.map((r) => r.path);
@@ -35472,7 +36563,7 @@ async function repoint(root, config, id) {
   for (const pointer of bump.pointers) {
     const repo = config.repos.find((r) => r.path === pointer.path);
     const name = repo?.name ?? pointer.path;
-    const dir = join44(root, pointer.path);
+    const dir = join46(root, pointer.path);
     const base = { repo: name, path: pointer.path, from: pointer.to };
     const current = (await git(["rev-parse", `HEAD:${pointer.path}`], { cwd: root })).stdout.trim();
     if (current !== pointer.to) {
@@ -35558,7 +36649,8 @@ async function review(p, id) {
         base,
         head: changeBranch(id),
         spec,
-        profiles: profilesFor(repoLanguages(repo)).map((pr) => pr.title)
+        profiles: profilesFor(repoLanguages(repo)).map((pr) => pr.title),
+        instructions: sessionInstructionPaths(p.config, name, repo.path)
       })
     });
     if (res.handoff === undefined) {
@@ -35583,7 +36675,7 @@ async function review(p, id) {
           kind: "review-fix"
         });
         added++;
-        mkdirSync16(join45(p.root, ".factory", "context", id), { recursive: true });
+        mkdirSync17(join47(p.root, ".factory", "context", id), { recursive: true });
         writeFileSync14(packPath(p.root, id, taskId), findingPack(f));
       }
       addTask(d, {
@@ -35626,7 +36718,7 @@ async function fullSuite(p, id) {
         command: r.command
       }))
     });
-    const output = report.results.filter((r) => r.status !== "pass" && r.status !== "skipped").map((r) => `[${r.type}] ${r.command ?? ""}
+    const output = report.results.filter((r) => r.status !== "pass" && r.status !== "skipped").map((r) => `[${r.name ?? r.type}] ${r.command ?? ""}
 ${r.output}`).join(`
 
 `);
@@ -35675,7 +36767,7 @@ function harvest(run) {
   }
   return { risks, questions, findings };
 }
-var reportFile = (root, id, kind) => join45(root, ".factory", "reports", kind === "final" ? `${id}.md` : `${id}-paused.md`);
+var reportFile = (root, id, kind) => join47(root, ".factory", "reports", kind === "final" ? `${id}.md` : `${id}-paused.md`);
 function writePauseReport(p, id, summary) {
   const run = p.run(id);
   const failed = run.tasks.filter((t) => t.status === "failed");
@@ -35706,18 +36798,18 @@ function writePauseReport(p, id, summary) {
     ...usageReport(summarizeUsage(p.root, id))
   ];
   const file = reportFile(p.root, id, "paused");
-  mkdirSync16(join45(p.root, ".factory", "reports"), { recursive: true });
+  mkdirSync17(join47(p.root, ".factory", "reports"), { recursive: true });
   writeFileSync14(file, lines.join(`
 `));
   return file;
 }
 function archivedName(root, id) {
-  if (existsSync32(join45(root, "openspec", "changes", id)))
+  if (existsSync33(join47(root, "openspec", "changes", id)))
     return;
-  const archive = join45(root, "openspec", "changes", "archive");
-  if (!existsSync32(archive))
+  const archive = join47(root, "openspec", "changes", "archive");
+  if (!existsSync33(archive))
     return;
-  return readdirSync12(archive).filter((n) => n === id || n.endsWith(`-${id}`)).sort().at(-1);
+  return readdirSync13(archive).filter((n) => n === id || n.endsWith(`-${id}`)).sort().at(-1);
 }
 async function close(p, id) {
   const run = p.run(id);
@@ -35725,9 +36817,9 @@ async function close(p, id) {
   if (open.length > 0)
     throw new PreconditionError(`cannot close ${id}: tasks not merged: ${open.map((t) => t.id).join(", ")}`);
   p.out("▶ close");
-  const tasksFile = join45(p.root, "openspec", "changes", id, "tasks.md");
-  if (existsSync32(tasksFile)) {
-    let text = readFileSync24(tasksFile, "utf8");
+  const tasksFile = join47(p.root, "openspec", "changes", id, "tasks.md");
+  if (existsSync33(tasksFile)) {
+    let text = readFileSync26(tasksFile, "utf8");
     for (const t of run.tasks.filter((x) => x.kind === "task"))
       text = setTaskChecked(text, t.id, true);
     writeFileSync14(tasksFile, text);
@@ -35818,7 +36910,7 @@ Archived as \`openspec/changes/archive/${archivedAs}\`.`,
     ...usageReport(summarizeUsage(p.root, id))
   ];
   const file = reportFile(p.root, id, "final");
-  mkdirSync16(join45(p.root, ".factory", "reports"), { recursive: true });
+  mkdirSync17(join47(p.root, ".factory", "reports"), { recursive: true });
   writeFileSync14(file, lines.join(`
 `));
   await p.update(id, (d) => {
@@ -36009,12 +37101,72 @@ async function step(p, id) {
   }
 }
 
+// src/pipeline/refine.ts
+import { mkdirSync as mkdirSync18, writeFileSync as writeFileSync15 } from "node:fs";
+import { join as join48 } from "node:path";
+var QUESTIONS = [
+  ["scope", "Which repos, modules or capabilities does this touch?", ""],
+  ["out-of-scope", "What is explicitly out of scope?", "nothing stated"],
+  [
+    "verification",
+    "How should this be verified (tests, gates, manual checks)?",
+    "the repository's normal gates"
+  ],
+  ["constraints", "Any contracts, compatibility or platform constraints?", "none stated"],
+  ["extra", "Anything else the spec must know?", "none"]
+];
+function requestSlug(text) {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").split("-").slice(0, 8).join("-");
+  return slug === "" ? "request" : slug;
+}
+async function refineRequest(io, request) {
+  if (io.ask === undefined) {
+    throw new PreconditionError("cannot ask questions in this environment", [
+      "run `ai-factory refine` from an interactive terminal, or pass a complete request to `run`"
+    ]);
+  }
+  const answers = [];
+  for (const [key, question, initial] of QUESTIONS) {
+    const answer = await io.ask(question, initial);
+    if (answer === undefined) {
+      throw new PreconditionError("refinement was cancelled");
+    }
+    if (answer.trim() !== "" && answer !== initial)
+      answers.push([key, answer.trim()]);
+  }
+  const text = `# Refined request
+
+## Original
+
+${request.trim()}
+
+## Clarifications
+
+${answers.map(([key, answer]) => `- **${key}**: ${answer}`).join(`
+`)}
+
+## Instructions for the architect
+
+Treat the clarifications as part of the request. If they conflict with the original, the
+clarification wins. Keep anything not named here out of scope, and put open questions into
+\`openspec/changes/<id>/questions.md\` rather than guessing.
+`;
+  const root = await findWorkspaceRoot(io.cwd);
+  if (root === undefined)
+    throw new PreconditionError("not inside a git repository");
+  const dir = join48(root, ".factory", "requests");
+  mkdirSync18(dir, { recursive: true });
+  const path = join48(dir, `${requestSlug(request)}.md`);
+  writeFileSync15(path, text);
+  return { path, text };
+}
+
 // src/cli/commands/pipeline-commands.ts
 async function setup(io) {
   const root = await findWorkspaceRoot(io.cwd);
   if (root === undefined)
     throw new PreconditionError("not inside a git repository");
-  if (!existsSync33(join46(root, LOCK_FILE)))
+  if (!existsSync34(join49(root, LOCK_FILE)))
     throw new PreconditionError("ai-factory is not installed here", ["run `ai-factory init`"]);
   const { config } = loadConfig(root);
   pruneLogs(root, config.logs.retentionDays);
@@ -36062,18 +37214,35 @@ function changeIdArg(command, positionals) {
 var runCommand = {
   name: "run",
   summary: "Start a change from a request and run it up to spec approval",
-  help: `Usage: ai-factory run "<request>"
+  help: `Usage: ai-factory run "<request>" [--request <file>] [--interactive]
 
 Intake (change id and summary), a change branch in the AI repo, explorers per likely repo,
 then the architect writes the OpenSpec change. Stops at spec approval: review
 openspec/changes/<id>/ and run \`ai-factory approve <id>\`. If another change is active, the
-new one is drafted in .factory/drafts/<id> and queued after approval.`,
+new one is drafted in .factory/drafts/<id> and queued after approval.
+
+  --request <file>  Read the request from a file (e.g. one written by \`ai-factory refine\`)
+  --interactive     Ask scope/verification questions before intake`,
   async run(args, io) {
-    const { positionals } = parseCommandArgs("run", args, {}, true);
-    const request = positionals.join(" ").trim();
+    const { values, positionals } = parseCommandArgs("run", args, {
+      request: { type: "string" },
+      interactive: { type: "boolean", default: false }
+    }, true);
+    let request = positionals.join(" ").trim();
+    if (values.request !== undefined) {
+      request = readFileSync27(resolve5(io.cwd, values.request), "utf8").trim();
+    }
     if (request === "")
       throw new UsageError('run: expected a request, e.g. ai-factory run "add a health endpoint"');
     return withPipeline(io, "intake", async (p) => {
+      if (values.interactive) {
+        if (!p.config.workflow.refine) {
+          throw new PreconditionError("workflow.refine is disabled");
+        }
+        const refined = await refineRequest(io, request);
+        request = refined.text;
+        io.out(`refined request: ${refined.path}`);
+      }
       const id = await intake(p, request);
       const result = await design(p, id);
       if (!result.ok) {
@@ -36131,8 +37300,282 @@ kept worktrees, finished ones stay; a queued change starts when the workspace is
   }
 };
 
+// src/pipeline/quick.ts
+import { rmSync as rmSync12 } from "node:fs";
+import { join as join50 } from "node:path";
+async function revert(dir, paths) {
+  for (const path of paths) {
+    const inHead = (await git(["cat-file", "-e", `HEAD:${path}`], { cwd: dir })).code === 0;
+    if (inHead)
+      await gitOk(["checkout", "-q", "HEAD", "--", path], { cwd: dir });
+    else {
+      await git(["rm", "-q", "--cached", "--ignore-unmatch", "--", path], { cwd: dir });
+      rmSync12(join50(dir, path), { force: true, recursive: true });
+    }
+  }
+}
+function gateOutput(report) {
+  return report.results.filter((r) => r.status !== "pass" && r.status !== "skipped").map((r) => `[${r.name ?? r.type}] ${r.command ?? ""}
+${r.output}`).join(`
+
+`);
+}
+async function quickTask(p, input) {
+  if (!p.config.workflow.quick.enabled) {
+    throw new PreconditionError("workflow.quick.enabled is false");
+  }
+  const code = p.codeRepos();
+  const repo = input.repo === undefined ? code.length === 1 ? code[0] : undefined : code.find((r) => r.name === input.repo);
+  if (repo === undefined) {
+    throw new PreconditionError(input.repo === undefined ? "quick: this workspace has several code repos; pass --repo <name>" : `quick: unknown repo "${input.repo}"`, code.map((r) => `  ${r.name} (${r.path})`));
+  }
+  const dir = p.repoDir(repo);
+  await ensureClean(dir, repo.name);
+  const slug = requestSlug(input.task);
+  const branch = `${p.config.workflow.quick.branchPrefix}${slug}`;
+  if (await currentBranch(dir) === branch) {
+    throw new PreconditionError(`already on ${branch}`);
+  }
+  if ((await git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: dir })).code === 0) {
+    throw new PreconditionError(`branch ${branch} already exists`);
+  }
+  const base = (await gitOk(["rev-parse", "HEAD"], { cwd: dir })).trim();
+  await gitOk(["switch", "-q", "-c", branch], { cwd: dir });
+  const installed = await installDeps(p.root, dir, repo);
+  const installFailure = installed.find((s) => s.status === "failed");
+  if (installFailure !== undefined) {
+    return {
+      repo: repo.name,
+      branch,
+      ok: false,
+      detail: `install failed: ${installFailure.detail ?? installFailure.dir}`
+    };
+  }
+  const explicit = input.agent === undefined ? undefined : p.config.agents.find((a) => a.id === input.agent);
+  if (input.agent !== undefined && explicit === undefined) {
+    throw new PreconditionError(`quick: unknown agent "${input.agent}"`);
+  }
+  if (explicit !== undefined && explicit.phase !== "implementer") {
+    throw new PreconditionError(`quick: agent "${explicit.id}" is not an implementer`);
+  }
+  const routed = explicit === undefined ? { agent: `implementer-${repo.name}`, role: "implementer", custom: false } : { agent: explicit.id, role: "implementer", custom: true };
+  const context = {
+    directory: dir,
+    workspace: p.root,
+    repo: repo.name,
+    task: "quick",
+    touches: ["**"]
+  };
+  let feedback;
+  let passed = false;
+  let output = "";
+  for (let attempt = 1;attempt <= 3 && !passed; attempt++) {
+    const res = await p.call({
+      changeId: `quick-${slug}`,
+      agent: routed.agent,
+      role: "implementer",
+      modelRole: "implementer",
+      context,
+      title: `quick ${slug} attempt ${attempt}`,
+      step: "quick",
+      kind: "attempt",
+      attempt,
+      prompt: feedback === undefined ? quickPrompt({ task: input.task, repo }) : `${quickPrompt({ task: input.task, repo })}
+
+Previous attempt failed:
+${feedback}`
+    });
+    if (res.handoff === undefined || res.handoff.status !== "done") {
+      return {
+        repo: repo.name,
+        branch,
+        ok: false,
+        detail: res.handoff?.openQuestions.join("; ") ?? res.problem ?? "agent did not finish"
+      };
+    }
+    const changed = await changedFiles(dir, base);
+    const violations = auditChanges({
+      sessionId: "quick-audit",
+      changeId: `quick-${slug}`,
+      role: "implementer",
+      ...context
+    }, changed, true);
+    if (violations.length > 0) {
+      await revert(dir, violations.map((v) => v.path));
+      return {
+        repo: repo.name,
+        branch,
+        ok: false,
+        detail: `edits outside the quick scope were reverted:
+${violations.map((v) => `${v.path}: ${v.reason}`).join(`
+`)}`
+      };
+    }
+    const report = await runGates({
+      root: p.root,
+      config: p.config,
+      repo,
+      worktree: dir,
+      mode: "task",
+      base
+    });
+    if (report.passed) {
+      passed = true;
+      break;
+    }
+    output = gateOutput(report);
+    feedback = output;
+  }
+  if (!passed) {
+    return { repo: repo.name, branch, ok: false, detail: `gates failed:
+${output}` };
+  }
+  if (input.review) {
+    let findings = [];
+    for (let round = 1;round <= 3; round++) {
+      const review = await p.call({
+        changeId: `quick-${slug}`,
+        agent: "reviewer",
+        role: "reviewer",
+        modelRole: "reviewer",
+        context: { directory: dir, workspace: p.root, repo: repo.name },
+        title: `quick ${slug} review ${round}`,
+        step: "quick-review",
+        kind: "step",
+        prompt: quickReviewPrompt({ task: input.task, repo })
+      });
+      if (review.handoff === undefined) {
+        return {
+          repo: repo.name,
+          branch,
+          ok: false,
+          detail: review.problem ?? "review produced no handoff"
+        };
+      }
+      findings = (review.handoff.findings ?? []).filter((f) => f.severity !== "nice").map((f) => `- [${f.severity}] ${f.file ?? ""}${f.line ? `:${f.line}` : ""} ${f.problem}
+  fix: ${f.fix}`);
+      if (findings.length === 0)
+        break;
+      const fix = await p.call({
+        changeId: `quick-${slug}`,
+        agent: routed.agent,
+        role: "implementer",
+        modelRole: "implementer",
+        context,
+        title: `quick ${slug} fix ${round}`,
+        step: "quick",
+        kind: "attempt",
+        attempt: 4 + round,
+        prompt: `Fix these review findings for the quick task:
+${findings.join(`
+`)}
+
+${quickPrompt({ task: input.task, repo })}`
+      });
+      if (fix.handoff?.status !== "done") {
+        return { repo: repo.name, branch, ok: false, detail: "review fix did not finish" };
+      }
+      const report = await runGates({
+        root: p.root,
+        config: p.config,
+        repo,
+        worktree: dir,
+        mode: "task",
+        base
+      });
+      if (!report.passed) {
+        return {
+          repo: repo.name,
+          branch,
+          ok: false,
+          detail: `gates failed after review fix:
+${gateOutput(report)}`
+        };
+      }
+      if (round === 3) {
+        return {
+          repo: repo.name,
+          branch,
+          ok: false,
+          detail: `review findings remain:
+${findings.join(`
+`)}`
+        };
+      }
+    }
+  }
+  const subject = conventionalSubject(input.task, undefined, {
+    style: p.config.commits.style,
+    ...p.config.commits.scopes ? { scope: repo.name } : {}
+  });
+  const commit = await commitAll(dir, subject, { "Change-Id": `quick-${slug}` });
+  return {
+    repo: repo.name,
+    branch,
+    ...commit === undefined ? {} : { commit },
+    ok: true,
+    detail: commit === undefined ? "nothing to commit" : `committed ${commit.slice(0, 12)}`
+  };
+}
+
+// src/cli/commands/quick.ts
+var HELP5 = `Usage: ai-factory quick "<task>" [--repo <name>] [--agent <id>] [--no-review]
+
+The no-OpenSpec path: create a task/<slug> branch, implement, run the repository gates, run
+one review pass, then make one local commit. No spec, no approval hash, and no push.
+--agent selects a configured custom implementer. The branch stays checked out so you can
+inspect or amend it.`;
+var quickCommand = {
+  name: "quick",
+  summary: "Implement a small task on a branch without an OpenSpec change",
+  help: HELP5,
+  async run(args, io) {
+    const { values, positionals } = parseCommandArgs("quick", args, {
+      repo: { type: "string" },
+      agent: { type: "string" },
+      "no-review": { type: "boolean", default: false }
+    }, true);
+    const task = positionals.join(" ").trim();
+    if (task === "")
+      throw new UsageError('quick: expected a task, e.g. "fix the login typo"');
+    return withPipeline(io, "quick", async (p) => {
+      const result = await quickTask(p, {
+        task,
+        ...values.repo === undefined ? {} : { repo: values.repo },
+        ...values.agent === undefined ? {} : { agent: values.agent },
+        review: !values["no-review"]
+      });
+      io.out(`${result.ok ? "✓" : "✗"} ${result.repo} ${result.branch}: ${result.detail}`);
+      return result.ok ? ExitCode.Ok : ExitCode.GateFailed;
+    });
+  }
+};
+
+// src/cli/commands/refine.ts
+var HELP6 = `Usage: ai-factory refine "<request>"
+
+Ask a few scope, verification and constraint questions, then write a refined request to
+.factory/requests/<slug>.md. Nothing is designed or implemented. Feed it to the pipeline
+with \`ai-factory run --request .factory/requests/<slug>.md\`, or use \`run --interactive\`
+to refine in the same command.`;
+var refineCommand = {
+  name: "refine",
+  summary: "Clarify a vague request before it becomes a spec",
+  help: HELP6,
+  async run(args, io) {
+    const { positionals } = parseCommandArgs("refine", args, {}, true);
+    const request = positionals.join(" ").trim();
+    if (request === "")
+      throw new UsageError('refine: expected a request, e.g. "add search"');
+    const { path } = await refineRequest(io, request);
+    io.out(`refined request: ${path}`);
+    io.out(`next: ai-factory run --request ${path}`);
+    return ExitCode.Ok;
+  }
+};
+
 // src/cli/commands/repoint.ts
-var HELP5 = `Usage: ai-factory repoint <change-id> [--json]
+var HELP7 = `Usage: ai-factory repoint <change-id> [--json]
 
 After the submodule MRs of a change are merged upstream: fetches each submodule, finds the
 merged commit (fast-forward, merge commit, Change-Id trailer, or the squash commit with the
@@ -36143,7 +37586,7 @@ Exits ${ExitCode.Precondition} when any pointer is still provisional.`;
 var repointCommand = {
   name: "repoint",
   summary: "Replace provisional submodule pointers after the MRs merged",
-  help: HELP5,
+  help: HELP7,
   async run(args, io) {
     const { values, positionals } = parseCommandArgs("repoint", args, { json: { type: "boolean", default: false } }, true);
     const id = positionals[0];
@@ -36172,8 +37615,8 @@ var repointCommand = {
 };
 
 // src/cli/commands/state-commands.ts
-import { existsSync as existsSync34, readdirSync as readdirSync13 } from "node:fs";
-import { join as join47 } from "node:path";
+import { existsSync as existsSync35, readdirSync as readdirSync14 } from "node:fs";
+import { join as join51 } from "node:path";
 async function workspace(io) {
   const root = await findWorkspaceRoot(io.cwd);
   if (root === undefined)
@@ -36222,9 +37665,9 @@ function taskDetail(run, task) {
 }
 function worktreesOf(root, id) {
   const dir = factoryDir(root, "worktrees", id);
-  if (!existsSync34(dir))
+  if (!existsSync35(dir))
     return [];
-  return readdirSync13(dir).filter((repo) => repo !== ".opencode").flatMap((repo) => readdirSync13(join47(dir, repo)).map((task) => `.factory/worktrees/${id}/${repo}/${task}`));
+  return readdirSync14(dir).filter((repo) => repo !== ".opencode").flatMap((repo) => readdirSync14(join51(dir, repo)).map((task) => `.factory/worktrees/${id}/${repo}/${task}`));
 }
 function printRun(io, root, run, active, queuePos) {
   const role = active?.changeId === run.id ? `active, ${driverAlive(active) ? `driven by pid ${active.pid}` : "no process driving it (resume to continue)"}` : queuePos >= 0 ? `queued #${queuePos + 1}` : "not active";
@@ -36382,20 +37825,20 @@ that were cancelled because of it. Continue the change with \`ai-factory resume
 };
 
 // src/cli/commands/update.ts
-import { rmSync as rmSync13, writeFileSync as writeFileSync16 } from "node:fs";
-import { join as join49 } from "node:path";
+import { rmSync as rmSync14, writeFileSync as writeFileSync17 } from "node:fs";
+import { join as join53 } from "node:path";
 
 // src/update/update.ts
 import {
   cpSync as cpSync2,
-  existsSync as existsSync35,
-  mkdirSync as mkdirSync17,
-  readdirSync as readdirSync14,
-  readFileSync as readFileSync25,
-  rmSync as rmSync12,
-  writeFileSync as writeFileSync15
+  existsSync as existsSync36,
+  mkdirSync as mkdirSync19,
+  readdirSync as readdirSync15,
+  readFileSync as readFileSync28,
+  rmSync as rmSync13,
+  writeFileSync as writeFileSync16
 } from "node:fs";
-import { dirname as dirname9, join as join48 } from "node:path";
+import { dirname as dirname10, join as join52 } from "node:path";
 
 // src/migrations/001-graph-exclude-defaults.ts
 var V1_GRAPH_EXCLUDE = [
@@ -36421,8 +37864,19 @@ var graphExcludeDefaults = {
   }
 };
 
+// src/migrations/002-config-v3.ts
+var configV3 = {
+  from: 2,
+  to: 3,
+  name: "config-v3",
+  migrate(text) {
+    parseJsonc(text);
+    return setJsonc(text, ["schemaVersion"], 3);
+  }
+};
+
 // src/migrations/index.ts
-var MIGRATIONS = [graphExcludeDefaults];
+var MIGRATIONS = [graphExcludeDefaults, configV3];
 function schemaVersionOf(text) {
   const { value } = parseJsonc(text);
   const v = value?.schemaVersion;
@@ -36484,7 +37938,7 @@ function changesInProgress(root) {
   return [...ids].sort();
 }
 async function planUpdate(root, lock, options) {
-  const original = readFileSync25(join48(root, CONFIG_FILE), "utf8");
+  const original = readFileSync28(join52(root, CONFIG_FILE), "utf8");
   const migration = migrateConfigText(original);
   const config = parseConfigText(migration.text, CONFIG_FILE);
   const plan = planWorkspace(root, config, {
@@ -36544,20 +37998,20 @@ function formatPlan(plan) {
 var backupsDir = (root) => factoryDir(root, "backups");
 function backup(root, plan) {
   const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const dir = join48(backupsDir(root), stamp);
+  const dir = join52(backupsDir(root), stamp);
   const files = [];
   const created = [];
   for (const rel of plan.touched) {
-    const abs = join48(root, rel);
-    if (!existsSync35(abs)) {
+    const abs = join52(root, rel);
+    if (!existsSync36(abs)) {
       created.push(rel);
       continue;
     }
-    mkdirSync17(dirname9(join48(dir, "files", rel)), { recursive: true });
-    cpSync2(abs, join48(dir, "files", rel), { recursive: true });
+    mkdirSync19(dirname10(join52(dir, "files", rel)), { recursive: true });
+    cpSync2(abs, join52(dir, "files", rel), { recursive: true });
     files.push(rel);
   }
-  writeJsonAtomic(join48(dir, "manifest.json"), {
+  writeJsonAtomic(join52(dir, "manifest.json"), {
     at: new Date().toISOString(),
     fromVersion: plan.fromVersion,
     toVersion: plan.toVersion,
@@ -36568,28 +38022,28 @@ function backup(root, plan) {
 }
 function latestBackup(root) {
   const base = backupsDir(root);
-  if (!existsSync35(base))
+  if (!existsSync36(base))
     return;
-  for (const name of readdirSync14(base).sort().reverse()) {
-    const file = join48(base, name, "manifest.json");
-    if (!existsSync35(file))
+  for (const name of readdirSync15(base).sort().reverse()) {
+    const file = join52(base, name, "manifest.json");
+    if (!existsSync36(file))
       continue;
-    const manifest = JSON.parse(readFileSync25(file, "utf8"));
+    const manifest = JSON.parse(readFileSync28(file, "utf8"));
     if (!manifest.restored)
-      return { dir: join48(base, name), manifest };
+      return { dir: join52(base, name), manifest };
   }
   return;
 }
 async function restoreBackup(root, dir, manifest) {
   for (const rel of manifest.created)
-    rmSync12(join48(root, rel), { recursive: true, force: true });
+    rmSync13(join52(root, rel), { recursive: true, force: true });
   for (const rel of manifest.files) {
-    const target = join48(root, rel);
-    rmSync12(target, { recursive: true, force: true });
-    mkdirSync17(dirname9(target), { recursive: true });
-    cpSync2(join48(dir, "files", rel), target, { recursive: true });
+    const target = join52(root, rel);
+    rmSync13(target, { recursive: true, force: true });
+    mkdirSync19(dirname10(target), { recursive: true });
+    cpSync2(join52(dir, "files", rel), target, { recursive: true });
   }
-  writeFileSync15(join48(dir, "manifest.json"), `${JSON.stringify({ ...manifest, restored: true }, null, 2)}
+  writeFileSync16(join52(dir, "manifest.json"), `${JSON.stringify({ ...manifest, restored: true }, null, 2)}
 `);
   return [...manifest.files, ...manifest.created];
 }
@@ -36683,7 +38137,7 @@ Upgrades this workspace to the installed factory version, as one local commit
       if (!t.ok)
         io.out(`warning: ${t.tool}: ${t.problem} → ${t.fix}`);
     const backupDir = backup(root, plan);
-    writeFileSync16(join49(root, CONFIG_FILE), plan.configText);
+    writeFileSync17(join53(root, CONFIG_FILE), plan.configText);
     const result = await syncWorkspace(root, plan.config, {
       merge: true,
       ...values.restore ? { restore: true } : {},
@@ -36698,7 +38152,7 @@ Upgrades this workspace to the installed factory version, as one local commit
     }
     const commit = await commitInstall(root, `chore(factory): update to v${FACTORY_VERSION}`);
     if (commit === undefined)
-      rmSync13(backupDir, { recursive: true, force: true });
+      rmSync14(backupDir, { recursive: true, force: true });
     if (plan.graphRebuild) {
       const graph = await updateGraph(root, { full: true });
       io.out(graph.ok ? "graph: rebuilt" : `graph: rebuild failed (${graph.error ?? ""}); run \`ai-factory graph --full\``);
@@ -36752,7 +38206,9 @@ var COMMANDS = [
   rollbackCommand,
   doctorCommand,
   detectCommand,
+  refineCommand,
   runCommand,
+  quickCommand,
   approveCommand,
   resumeCommand,
   statusCommand,
@@ -36799,6 +38255,16 @@ async function askYesNo(question) {
     rl.close();
   }
 }
+async function askText(question, initial) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = initial === undefined || initial === "" ? "" : ` (${initial})`;
+    const answer = (await rl.question(`${question}${suffix}: `)).trim();
+    return answer === "" ? initial : answer;
+  } finally {
+    rl.close();
+  }
+}
 async function runCli(argv, io) {
   let cwd = io.cwd;
   let i = 0;
@@ -36810,7 +38276,7 @@ async function runCli(argv, io) {
         io.err("error: -C needs a directory");
         return ExitCode.Usage;
       }
-      cwd = resolve5(cwd, dir);
+      cwd = resolve6(cwd, dir);
     } else if (arg === "-V" || arg === "--version") {
       io.out(FACTORY_VERSION);
       return ExitCode.Ok;
@@ -36852,6 +38318,6 @@ var code = await runCli(process.argv.slice(2), {
 `),
   err: (text) => process.stderr.write(`${text}
 `),
-  ...process.stdin.isTTY ? { confirm: askYesNo } : {}
+  ...process.stdin.isTTY ? { confirm: askYesNo, ask: askText } : {}
 });
 process.exit(code);