@comento/pota-harness 0.0.0-stage → 1.0.0

package/scripts/pota-update-state.mjs

@@ -0,0 +1,219 @@
+import { spawn as spawnProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { lstat, rm, rmdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { potaHome, installManifestPath, installRoot } from "./pota-paths.mjs";
+
+// Auto-upgrade state shared by the SessionStart hook and the detached runner. The hook only reads small files here,
+// claims a pending notice, and spawns the runner; it never touches the network, a lock, or the installation.
+export const UPDATE_PACKAGE_NAME = "@comento/pota-harness";
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const NOTICE_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+export const NOTICE_KINDS = ["updated", "failed", "manual"];
+// Exit codes of `pota-lifecycle.mjs upgrade --auto` besides 0 (done) and 1 (anything else). They are a contract
+// between versions: the runner is the installed version and the lifecycle it starts is the new one.
+// `manual`: the files are committed and only the Claude Code step (cache refresh, registration, a missing claude CLI)
+// is left to the user.
+export const AUTO_UPGRADE_EXIT = Object.freeze({ manual: 3 });
+const UPDATE_SCHEMA_VERSION = 1;
+const SMALL_FILE_LIMIT = 64 * 1024;
+const MANIFEST_FILE_LIMIT = 1024 * 1024;
+const OFF_VALUES = new Set(["0", "false", "off", "no"]);
+const INSTALLED_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+export function updatePaths(env = process.env) {
+  const home = potaHome(env);
+  const root = join(home, "update");
+  return {
+    home,
+    root,
+    config: join(home, "config.json"),
+    state: join(root, "state.json"),
+    notice: join(root, "notice.json"),
+    log: join(root, "last-run.log"),
+    lock: join(root, "update.lock"),
+    stage: join(root, "stage"),
+    manifest: installManifestPath(env),
+    runtimeParent: join(installRoot(env), "runtime"),
+  };
+}
+
+// A regular file at most `limit` bytes, parsed as JSON. Symlinks, directories, oversized and malformed files are
+// "invalid"; only a missing file is "missing".
+export function readJsonFile(path, limit = SMALL_FILE_LIMIT) {
+  let info;
+  try { info = lstatSync(path); } catch (error) { return { status: error?.code === "ENOENT" ? "missing" : "invalid" }; }
+  if (!info.isFile() || info.size > limit) return { status: "invalid" };
+  try { return { status: "ok", value: JSON.parse(readFileSync(path, "utf8")) }; } catch { return { status: "invalid" }; }
+}
+
+export function writeJsonAtomic(path, value) {
+  writeFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function writeFileAtomic(path, text) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, text, { flag: "wx" });
+    renameSync(temporary, path);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+// On by default. POTA_AUTO_UPGRADE=0|false|off|no or config.json `autoUpgrade: false` turns it off, and so does a
+// config.json that cannot be read or has the wrong shape: an unclear setting never starts an install.
+export function autoUpgradeSetting(env = process.env, paths = updatePaths(env)) {
+  const raw = env.POTA_AUTO_UPGRADE;
+  if (typeof raw === "string" && OFF_VALUES.has(raw.trim().toLowerCase())) return { enabled: false, source: "env" };
+  const config = readJsonFile(paths.config);
+  if (config.status === "missing") return { enabled: true, source: "default" };
+  if (config.status !== "ok" || !isPlainObject(config.value)) return { enabled: false, source: "invalid-config" };
+  const value = config.value.autoUpgrade;
+  if (value === undefined) return { enabled: true, source: "default" };
+  if (typeof value !== "boolean") return { enabled: false, source: "invalid-config" };
+  return { enabled: value, source: "config" };
+}
+
+export function readInstallManifest(paths) {
+  const read = readJsonFile(paths.manifest, MANIFEST_FILE_LIMIT);
+  const manifest = read.status === "ok" ? read.value : null;
+  if (manifest?.schemaVersion !== 2 || manifest.plugin !== "pota" || typeof manifest.version !== "string"
+      || !INSTALLED_VERSION.test(manifest.version) || !["checkout", "package"].includes(manifest.origin)) return null;
+  return { version: manifest.version, installedAt: manifest.installedAt, origin: manifest.origin };
+}
+
+export function readUpdateState(paths) {
+  const read = readJsonFile(paths.state);
+  return read.status === "ok" && isPlainObject(read.value) && read.value.schemaVersion === UPDATE_SCHEMA_VERSION ? read.value : null;
+}
+
+export function readPendingNotice(paths) {
+  const read = readJsonFile(paths.notice);
+  return read.status === "ok" && validNotice(read.value) ? read.value : null;
+}
+
+export function emptyUpdateState() {
+  return {
+    schemaVersion: UPDATE_SCHEMA_VERSION, lastCheckedAt: null, latestSeen: null, consecutiveFailures: 0,
+    nextAttemptAt: null, failedVersion: null, lastResult: null,
+  };
+}
+
+export function noticeRecord(kind, from, to, at) {
+  return { schemaVersion: UPDATE_SCHEMA_VERSION, kind, from, to, at };
+}
+
+// The hook runs from an installed runtime only when its own .pota-runtime.json points at <install>/runtime/<version>.
+// A source checkout has no locator there, so it reads and writes nothing else.
+export function runningInstall(pluginRoot, paths) {
+  if (typeof pluginRoot !== "string") return null;
+  const locator = readJsonFile(join(pluginRoot, ".pota-runtime.json"));
+  if (locator.status !== "ok" || locator.value?.plugin !== "pota" || typeof locator.value.pluginRoot !== "string") return null;
+  const version = childName(paths.runtimeParent, locator.value.pluginRoot);
+  if (!version || !INSTALLED_VERSION.test(version)) return null;
+  return { runtimeRoot: join(paths.runtimeParent, version), version };
+}
+
+// Due once a day after the later of the last check and the install; a recorded backoff can only push it further out.
+export function checkDue({ state, manifest, now }) {
+  const time = now.getTime();
+  const next = Date.parse(state?.nextAttemptAt ?? "");
+  if (Number.isFinite(next) && time < next) return false;
+  const since = Math.max(...[state?.lastCheckedAt, manifest?.installedAt].map((value) => Date.parse(value ?? "")).filter(Number.isFinite));
+  return !Number.isFinite(since) || time - since >= CHECK_INTERVAL_MS;
+}
+
+// SessionStart: claim at most one pending notice, then start the runner when a check is due. Returns the claimed
+// notice or null. Callers swallow errors so the capsule and exit code never depend on this step.
+export function sessionStartUpdate({ env = process.env, now = new Date(), spawn = spawnProcess, pluginRoot } = {}) {
+  const paths = updatePaths(env);
+  const running = runningInstall(pluginRoot, paths);
+  if (!running) return null;
+  let notice = null;
+  try { notice = claimNotice(paths, { runningVersion: running.version, now }); } catch { notice = null; }
+  try { startRunnerWhenDue({ env, now, spawn, paths, running }); } catch { /* the next session tries again */ }
+  return notice;
+}
+
+function startRunnerWhenDue({ env, now, spawn, paths, running }) {
+  if (!autoUpgradeSetting(env, paths).enabled) return;
+  const manifest = readInstallManifest(paths);
+  // Only the canonical runtime of the installed version starts a runner; a retained runtime or a checkout install never does.
+  if (!manifest || manifest.origin !== "package" || manifest.version !== running.version) return;
+  if (!checkDue({ state: readUpdateState(paths), manifest, now })) return;
+  // stdio "ignore" keeps the hook's stdout pipe closed so the host does not wait for the runner; the error listener
+  // keeps a failed spawn from becoming an uncaught exception in the hook.
+  const child = spawn(process.execPath, [join(running.runtimeRoot, "scripts", "pota-auto-upgrade.mjs"), "run"], {
+    cwd: paths.home, env, detached: true, stdio: "ignore", windowsHide: true,
+  });
+  child?.on?.("error", () => {});
+  child?.unref?.();
+}
+
+// `updated` is shown only by a session that runs the new version; `failed` and `manual` by any installed version.
+// The first session to rename the file shows it; notices older than 14 days are dropped silently.
+export function claimNotice(paths, { runningVersion, now = new Date() }) {
+  const read = readJsonFile(paths.notice);
+  if (read.status === "missing") return null;
+  if (read.status !== "ok" || !validNotice(read.value) || now.getTime() - Date.parse(read.value.at) > NOTICE_MAX_AGE_MS) {
+    rmSync(paths.notice, { force: true });
+    return null;
+  }
+  if (!noticeShownBy(read.value, runningVersion)) return null;
+  const claimed = `${paths.notice}.${randomUUID()}.claimed`;
+  try { renameSync(paths.notice, claimed); } catch { return null; }
+  try {
+    const value = readJsonFile(claimed).value;
+    if (validNotice(value) && noticeShownBy(value, runningVersion)) return value;
+    // A runner replaced the notice between the read and the rename; put the newer one back for its own session.
+    try { lstatSync(paths.notice); } catch { renameSync(claimed, paths.notice); }
+    return null;
+  } finally {
+    rmSync(claimed, { force: true });
+  }
+}
+
+function noticeShownBy(notice, runningVersion) {
+  return notice.kind !== "updated" || notice.to === runningVersion;
+}
+
+function validNotice(value) {
+  return isPlainObject(value) && value.schemaVersion === UPDATE_SCHEMA_VERSION && NOTICE_KINDS.includes(value.kind)
+    && typeof value.to === "string" && typeof value.from === "string" && Number.isFinite(Date.parse(value.at ?? ""));
+}
+
+// Called by uninstall after the lifecycle lock is released: the known update files and the runner's stage go, and the
+// directory is removed when empty. config.json and projects/ stay. A running runner (its lock present) keeps its stage.
+export async function removeUpdateState(env = process.env) {
+  const paths = updatePaths(env);
+  try {
+    if (!(await lstat(paths.root)).isDirectory()) return;
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  for (const path of [paths.state, paths.notice, paths.log]) await rm(path, { force: true });
+  let locked = true;
+  try { await lstat(paths.lock); } catch (error) { if (error?.code === "ENOENT") locked = false; else throw error; }
+  if (!locked) await rm(paths.stage, { recursive: true, force: true });
+  try { await rmdir(paths.root); } catch (error) { if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error?.code)) throw error; }
+}
+
+function childName(parent, child) {
+  const direct = singleSegment(relative(resolve(parent), resolve(child)));
+  if (direct) return direct;
+  try { return singleSegment(relative(realpathSync(parent), realpathSync(child))); } catch { return null; }
+}
+
+function singleSegment(relation) {
+  if (!relation || relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation) || relation.includes(sep)) return null;
+  return relation;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/scripts/pota.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { runState } from "./pota-state.mjs";
+import { INDEX_USAGE, checkIndex, parseIndexArgs, updateIndex } from "./pota-index.mjs";
+import { parseRootArgs, resolvePluginRoot } from "./pota-paths.mjs";
+
+const pluginRoot = resolvePluginRoot(import.meta.url);
+const scriptDir = join(pluginRoot, "scripts");
+const version = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf8")).version;
+
+export async function main(command = "help", args = [], { runner = spawnSync } = {}) {
+  if (command === "help" || command === "--help") {
+    console.log(message("usage"));
+    return;
+  }
+  if (command === "version" || command === "--version") {
+    console.log(`pota ${version}`);
+    return;
+  }
+  if (["install", "upgrade", "doctor", "uninstall"].includes(command)) {
+    const result = runner(process.execPath, [join(scriptDir, "pota-lifecycle.mjs"), command, ...args], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (["goal", "task"].includes(command)) {
+    const goalArgs = command === "goal" ? args : ["task", ...args];
+    const result = runner(process.execPath, [join(scriptDir, "pota-goal.mjs"), ...goalArgs], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (command === "memory" || command === "plan") {
+    const options = parseIndexArgs(command, args);
+    if (options.action === "guidance") {
+      console.log(message(command));
+      return;
+    }
+    if (options.action === "help") {
+      console.log(INDEX_USAGE[command]);
+      return;
+    }
+    if (options.action === "version") {
+      console.log(`pota ${version}`);
+      return;
+    }
+    const report = options.action === "check"
+      ? await checkIndex(options.root, command, { strict: options.strict })
+      : await updateIndex(options.root, command, { dryRun: options.dryRun, archive: options.archive, ko: localeFamily() === "ko" });
+    console.log(JSON.stringify(report, null, 2));
+    process.exitCode = report.ok ? 0 : 1;
+    return;
+  }
+  const { args: rest, repoRoot } = parseRootArgs(args);
+  if (command === "init") {
+    // Reject every remaining argument before init writes anything.
+    if (rest.length === 1 && rest[0] === "--help") {
+      console.log("Usage: pota init [--root PATH]");
+      return;
+    }
+    if (rest.length === 1 && rest[0] === "--version") {
+      console.log(`pota ${version}`);
+      return;
+    }
+    const unexpected = rest.find((argument) => argument !== "--help" && argument !== "--version");
+    if (unexpected !== undefined) throw new Error(`unknown option: ${unexpected}`);
+    if (rest.includes("--help") && rest.includes("--version")) throw new Error("--help and --version cannot be used together");
+    if (rest.length > 0) throw new Error(`${rest[0]} may only be provided once`);
+    console.log(await runState("manual", { root: repoRoot }));
+    return;
+  }
+  if (command === "toolcheck") {
+    const result = runner(process.execPath, [join(scriptDir, "pota-toolcheck.mjs"), ...args], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (command === "auto-upgrade") {
+    const result = runner(process.execPath, [join(scriptDir, "pota-auto-upgrade.mjs"), ...args], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (command === "cleanup") {
+    const result = runner(process.execPath, [join(scriptDir, "pota-cleanup.mjs"), ...args], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (["work", "review"].includes(command)) {
+    console.log(message(command));
+    return;
+  }
+  throw new Error(`unknown command: ${command}`);
+}
+
+export function message(key, locale = localeValue()) {
+  const family = localeFamily(locale);
+  return messages[family]?.[key] ?? messages.en[key];
+}
+
+export function localeFamily(locale = localeValue()) {
+  const normalized = locale.toLowerCase();
+  for (const family of ["ko", "ja", "zh", "es", "fr", "de", "pt"]) {
+    if (normalized.startsWith(family)) return family;
+  }
+  return "en";
+}
+
+function localeValue() {
+  return [process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG]
+    .find((value) => typeof value === "string" && value.length > 0) ?? Intl.DateTimeFormat().resolvedOptions().locale;
+}
+
+function isCliEntry() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}
+
+const planExecutionPolicy = "The user-called/main agent is the orchestrator; implementation edits go to worker subagents whenever subagent tools are available. When the subagent tool provides a progress-reporting channel, subagents report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, the orchestrator relays observable events such as assignment, waiting, and final completion. When a delegated subagent finishes, it must provide its final report before leaving; after the orchestrator captures the final report and evidence, the orchestrator must close or release the completed subagent, then review the final report and evidence before marking the work complete. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.";
+const workExecutionPolicy = "The user-called/main agent orchestrates, while worker subagents perform implementation edits whenever subagent tools are available. When the subagent tool provides a progress-reporting channel, subagents report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, the orchestrator relays observable events such as assignment, waiting, and final completion. When a delegated subagent finishes, it must provide its final report before leaving; after the orchestrator captures the final report and evidence, the orchestrator must close or release the completed subagent, then review the final report and evidence before marking the work complete. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.";
+const tokenEfficientWorkPolicy = "Use a test contract for requirements, invariants, boundaries, and failure modes before the minimum implementation. The tool exit code is authoritative. Run goal verify -- <argv> and expand only failures. Inspect package lifecycle scripts: content-producing or unknown scripts must never use --ignore-scripts; only absent or proven content-neutral scripts may use it while prior full-check evidence remains fresh.";
+const stagedTriagePolicy = "Use request, planning, and code checkpoints. Before the first edit, evidence may change either route; synchronize the plan artifact, repository goal task roadmap through goal replan, and native UI plan. After editing starts, a new Heavy Path signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.";
+const stagedTriagePolicyKo = "요청, 계획, 코드 체크포인트를 사용합니다. 첫 편집 전에는 증거에 따라 어느 경로로든 바꿀 수 있으며 plan artifact, 저장소 goal task roadmap, native UI plan을 동기화합니다. 편집 뒤 새 Heavy Path 신호가 나오면 Light Path를 Heavy Path로 승격하고 추가 편집을 중단하며 관련 증거를 stale로 표시한 뒤 세 roadmap과 코드 체크포인트를 다시 맞춥니다.";
+const reasoningEffortPolicy = "Choose a model per task (fast/balanced/stronger/strongest) and pass it like effort; route reasoning effort by task: Light planning/implementation/verification=medium; Heavy planning/review/implementation=high; final verification/review=xhigh. Every new task/worker dispatch MUST pass the requested effort through the host option (Claude Code: Agent `effort`, never fork) and the chosen model the same way (Agent `model`); Effective is the passed value, `not-applied: <reason>` when not passed, `inherited` only when the host has no option. Never change global/user config.";
+const artifactLocalePolicy = "Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.";
+const memoryIndexPolicy = "Each MEMORY.md line under Domain Knowledge locates one docs/memory/<name>.md note with its one-line Summary; maintain it with pota memory index and verify it with pota memory check.";
+const planIndexPolicy = "Each PLAN.md line locates one docs/plan/<name>.md plan under Active Plans or Completed Plans (newest first); maintain it with pota plan index (--archive moves older entries to docs/plan/ARCHIVE.md) and verify it with pota plan check.";
+const artifactLocalePolicyKo = "사용자가 다른 언어를 요청하지 않는 한, 사용자에게 보이는 응답과 생성 또는 갱신하는 문서, 계획, 메모리 산출물은 OS locale 언어로 작성합니다.";
+
+const messages = {
+  en: {
+    memory: `Use the pota-memory skill. Keep MEMORY.md as a short index and write details to docs/memory/<domain>.md. ${artifactLocalePolicy} ${memoryIndexPolicy}`,
+    plan: `Use the pota-plan skill before non-trivial implementation. Read project-root MEMORY.md first when present; if absent, continue without repository memory. Understand the whole work first, then classify it into executable tasks and sub-tasks. Keep PLAN.md as an index, write detailed plans to docs/plan/<topic>.md, and record Light/Heavy Path triage before any mutation. ${stagedTriagePolicy} ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `Use pota-work only after a plan exists. Read root MEMORY.md when present and continue without it when absent. ${tokenEfficientWorkPolicy} Execute one task through its recorded Light/Heavy Path. ${stagedTriagePolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy} Resume active work after side questions unless asked to pause, stop, or switch.`,
+    review: `Use the pota-review skill. Compare evidence against PLAN.md and MEMORY.md. ${artifactLocalePolicy}`,
+    usage: "Usage: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+  ko: {
+    memory: `pota-memory 스킬을 사용하세요. MEMORY.md는 짧은 색인으로, 상세 내용은 docs/memory/<domain>.md에 기록합니다. ${artifactLocalePolicyKo} ${memoryIndexPolicy}`,
+    plan: `중요 구현 전에는 pota-plan 스킬을 사용하세요. 프로젝트 루트 MEMORY.md가 있으면 먼저 읽고, 없으면 저장소 메모리 없이 계속 진행합니다. 먼저 전체 작업을 파악한 뒤 실행 가능한 task와 필요한 sub-task로 분류합니다. PLAN.md는 색인으로, 상세 계획은 docs/plan/<topic>.md에 기록하며 파일 변경 전 Light/Heavy Path 트리아지를 남깁니다. ${stagedTriagePolicyKo} ${reasoningEffortPolicy} ${artifactLocalePolicyKo} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `계획이 있으면 pota-work를 사용하세요. 루트 MEMORY.md가 있으면 읽고 없으면 무시하고 진행합니다. ${tokenEfficientWorkPolicy} 기록된 Light/Heavy Path로 한 task를 수행합니다. ${stagedTriagePolicyKo} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicyKo} 곁가지 질문 뒤에는 일시중지·중단·전환 요청이 없으면 active work를 재개합니다.`,
+    review: `pota-review 스킬을 사용하세요. PLAN.md와 MEMORY.md 기준으로 증거를 비교합니다. ${artifactLocalePolicyKo}`,
+    usage: "사용법: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+  ja: {
+    memory: `pota-memory スキルを使用してください。MEMORY.md は短い索引にし、詳細は docs/memory/<domain>.md に記録します。${artifactLocalePolicy} ${memoryIndexPolicy}`,
+    plan: `pota-plan スキルを使用してください。PLAN.md は索引にし、詳細計画は docs/plan/<topic>.md に記録します。${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `pota-work スキルを使用してください。1つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    review: `pota-review スキルを使用してください。PLAN.md と MEMORY.md に照らして証拠を比較します。${artifactLocalePolicy}`,
+    usage: "使い方: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+  zh: {
+    memory: `使用 pota-memory skill。将 MEMORY.md 保持为简短索引，并将详细内容写入 docs/memory/<domain>.md。${artifactLocalePolicy} ${memoryIndexPolicy}`,
+    plan: `使用 pota-plan skill。将 PLAN.md 保持为索引，并将详细计划写入 docs/plan/<topic>.md。${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `使用 pota-work skill。执行一个模块切片，并收集模块证据。${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    review: `使用 pota-review skill。根据 PLAN.md 和 MEMORY.md 对比证据。${artifactLocalePolicy}`,
+    usage: "用法: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+  es: {
+    memory: `Usa la skill pota-memory. Mantén MEMORY.md como un índice breve y escribe los detalles en docs/memory/<domain>.md. ${artifactLocalePolicy} ${memoryIndexPolicy}`,
+    plan: `Usa la skill pota-plan. Mantén PLAN.md como índice y escribe los planes detallados en docs/plan/<topic>.md. ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `Usa la skill pota-work. Ejecuta un solo segmento de módulo y captura evidencia de módulo y de superficie. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    review: `Usa la skill pota-review. Compara la evidencia con PLAN.md y MEMORY.md. ${artifactLocalePolicy}`,
+    usage: "Uso: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+  fr: {
+    memory: `Utilisez la skill pota-memory. Gardez MEMORY.md comme index court et écrivez les détails dans docs/memory/<domain>.md. ${artifactLocalePolicy} ${memoryIndexPolicy}`,
+    plan: `Utilisez la skill pota-plan. Gardez MEMORY.md comme index et écrivez les plans détaillés dans docs/plan/<topic>.md. ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `Utilisez la skill pota-work. Exécutez une tranche de module et capturez les preuves de module et de surface. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    review: `Utilisez la skill pota-review. Comparez les preuves avec PLAN.md et MEMORY.md. ${artifactLocalePolicy}`,
+    usage: "Utilisation: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+  de: {
+    memory: `Verwenden Sie die Skill pota-memory. Halten Sie MEMORY.md als kurzen Index und schreiben Sie Details nach docs/memory/<domain>.md. ${artifactLocalePolicy} ${memoryIndexPolicy}`,
+    plan: `Verwenden Sie die Skill pota-plan. Halten Sie MEMORY.md als Index und schreiben Sie Detailpläne nach docs/plan/<topic>.md. ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `Verwenden Sie die Skill pota-work. Führen Sie einen Modulabschnitt aus und erfassen Sie Modul- und Oberflächenbelege. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    review: `Verwenden Sie die Skill pota-review. Vergleichen Sie Belege mit PLAN.md und MEMORY.md. ${artifactLocalePolicy}`,
+    usage: "Verwendung: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+  pt: {
+    memory: `Use a skill pota-memory. Mantenha MEMORY.md como um índice curto e escreva detalhes em docs/memory/<domain>.md. ${artifactLocalePolicy} ${memoryIndexPolicy}`,
+    plan: `Use a skill pota-plan. Mantenha MEMORY.md como índice e escreva planos detalhados em docs/plan/<topic>.md. ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy} ${planIndexPolicy}`,
+    work: `Use a skill pota-work. Execute uma fatia de módulo e capture evidências de módulo e de superfície. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    review: `Use a skill pota-review. Compare evidências com PLAN.md e MEMORY.md. ${artifactLocalePolicy}`,
+    usage: "Uso: pota install|upgrade|doctor|uninstall|auto-upgrade|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
+  },
+};
+
+if (isCliEntry()) {
+  const [command = "help", ...args] = process.argv.slice(2);
+  try {
+    await main(command, args);
+  } catch (error) {
+    console.error(`Pota error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 2;
+  }
+}

package/skills/pota-memory/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: pota-memory
+description: Create and maintain repository MEMORY.md and docs/memory domain notes for token-efficient Codex, Claude Code, and Antigravity agent work.
+---
+
+# Pota Memory
+
+Use this when domain knowledge, repository policy, or pre-plan context compression is needed.
+
+## Purpose
+
+The root `MEMORY.md` is an index, not detailed knowledge. Record details in `docs/memory/<domain>.md`.
+
+Every delegated agent reads project-root `MEMORY.md` when present and continues when absent before doing its assigned discovery, evidence, or update task.
+
+When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Every child subagent reads project-root `MEMORY.md` when present and continues when absent, keeps the assigned scope, and preserves others' edits.
+
+## Runtime Location
+
+Resolve Pota's read-only runtime from `references/pota-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Pota's `scripts/`, `templates/`, commands, agents, and model guidance. In a source checkout where the locator does not exist, resolve the plugin root from this `SKILL.md` location (`../..`). Never look for Pota runtime files in the target repository or derive the plugin root from the current working directory. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover from the published/global package with `pota doctor` followed by `pota upgrade`; do not use another mirror as a repair source.
+
+Keep the target repository root separate. Pass it explicitly with `--root <repoRoot>` when invoking the installed runtime. Repository artifacts include `MEMORY.md`, `PLAN.md`, `docs/memory/`, and `docs/plan/`; runtime goal state lives only under the user-home Pota directory.
+
+## Procedure
+
+1. Run `node "<pluginRoot>/scripts/pota.mjs" init --root "<repoRoot>"` through the resolved Pota runtime. If the runtime is unavailable, ensure `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` directly and report that `pota doctor` or `pota upgrade` is required.
+2. Explore the repository before asking the user.
+3. Delegate when it materially improves speed or quality instead of asking the user.
+   - `explorer`: read-only domain discovery, boundaries, invariants, policies, contradictions, and stale facts when available.
+   - `worker`: exact file paths, commands, schemas, references, and bounded evidence capture.
+   - Recursive subagent delegation is allowed only for bounded sub-tasks when the current surface supports it.
+4. Write detailed facts to `docs/memory/<domain>.md` from `pota://templates/domain-memory.md`. Put a `Summary:` line under the H1: one line of at most 120 characters stating what the note answers and when to read it. The index and the session-start hook show that line, so agents can pick notes without opening them.
+5. Keep only one-line entries in `MEMORY.md` under `## Domain Knowledge` (`- [<name>](docs/memory/<name>.md): <summary>`); a note link in another section is a mention that `index` never rewrites. Run `node "<pluginRoot>/scripts/pota.mjs" memory index --root "<repoRoot>"` to add unlisted notes and replace the summary after the link when `Summary:` changed (`--dry-run` previews; it removes only exact Pota placeholder lines in that section, never deletes entries or dead links, and writes nothing when the insertion point is inside an unclosed code fence), then `memory check --root "<repoRoot>"`: exit 1 lists unindexed notes, dead links, duplicates, stale summaries, and control characters to fix; warnings fail only with `--strict`.
+6. When a lesson or correction recurs and is machine-checkable, encode it as a test, lint rule, script, or hook instead of more prose; memory keeps judgment rules and a pointer to the enforcing check.
+7. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+
+## Delegation Prompt Format
+
+```text
+TASK: Explore persistent domain knowledge for <domain>.
+EXPECTED OUTCOME: Return facts, source paths, and proof commands concisely.
+REQUIRED TOOLS: Read-only file search, LSP/symbol tools, command checks.
+MUST DO: Read the project-root `MEMORY.md` before doing assigned work. Preserve proper nouns exactly. Cite local paths. Separate facts from inference. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
+MUST NOT DO: Edit files. Ask the user. Guess missing names.
+CONTEXT: Current task, repository root, existing MEMORY.md entries.
+```
+
+## Completion Criteria
+
+- `MEMORY.md` links to detailed notes, one line each, and `memory check` exits 0.
+- Each note starts with a `Summary:` line and has clear scope and sources, and is shorter than reading the original files wholesale.
+- Long explanations are not duplicated in the root index.

package/skills/pota-plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: pota-plan
+description: Use before non-trivial implementation, refactoring, migrations, debugging, repository automation, or any request that asks to plan, design, implement carefully, triage complexity, or coordinate agents. Creates decision-complete PLAN.md and docs/plan plans through repository evidence and bounded delegation instead of user questions.
+---
+
+# Pota Plan
+
+Use before non-trivial implementation, refactoring, migrations, debugging, or repository automation, or when the user asks for planning, design, "설계부터", "신중하게", "꼼꼼히", or coordinated agents. Plans reduce execution tokens: store the topic in `PLAN.md` and details in `docs/plan/<topic>.md`, never only in chat.
+
+## Re-entry and Required References
+
+At the start and after compaction, restart, or handoff, restore context in this order: optional root `MEMORY.md` → `pota-plan` → the active plan → current-task references → model guidance recorded by the plan. Missing `MEMORY.md` is not an inconsistency: continue without repository memory and never invoke another memory service. If persisted state names a plan or task and that required reference is missing, unreadable, or inconsistent, do not explore, edit, delegate, or complete work; report or record a blocker first. No read-receipt fields: state consistency and bound tool evidence are the authority.
+
+## Runtime Location
+
+Resolve the read-only runtime from `references/pota-runtime.json` next to this `SKILL.md` (its `pluginRoot`; in a source checkout without it, this file's `../..`). Never search the target repository for Pota files or derive `pluginRoot` from the cwd. If the runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover with published/global `pota doctor` followed by `pota upgrade`; never repair from another mirror.
+
+Plans use logical IDs such as `pota://templates/work-plan.md`, resolved through `pluginRoot`. The session-start hook prints a ready prefix `Pota CLI: node "<abs>/scripts/pota.mjs" goal <command>`: copy it literally into every command and never store it in a shell variable (shell variables do not persist between tool calls). `--root` may be omitted when the cwd is inside the repository (it resolves via `HARNESS_REPO_ROOT`, else the nearest `.git` ancestor).
+
+## Reference Files
+
+Read a reference only when the selected path or situation requires it (Quick and Light Path never need `heavy-path.md`):
+
+- `pota://skills/pota-plan/planning-rules.md`: plan rules, route record, tool readiness, dry-run policy; read when finalizing a plan.
+- `pota://skills/pota-plan/delegation.md`: subagent lifecycle, prompt format, reasoning-effort routing; read before dispatching.
+- `pota://skills/pota-plan/heavy-path.md`: Heavy Path flow, route changes, review gates; read only on a Heavy signal or route change.
+
+## Path Selection
+
+Decide from repository evidence without asking; this outranks plugin or agent workflow guidance.
+
+- **Routine known-target Git/GitHub operation** (status, fetch, checkout, branch, merge, push, PR management): plan/goal-free unless it requires code edits, conflict resolution, destructive recovery, release/deploy, or design.
+- **Consultation, explanation, or plan-only**: no goal.
+- **Quick Path**: all must hold: requirements are unambiguous; the expected change touches about 3 files or fewer inside existing layers; no Heavy Path signal; no external-state mutation; verification is one or two commands. No `docs/plan` artifact and no repository goal: implement, run one focused check plus the project's normal check, and report. If any criterion fails during work, escalate to Light Path (create plan + goal) before further edits.
+- **Light Path** (default): stays inside existing layers, adds no domain model, service class, or abstraction, and has no Heavy signal.
+- **Heavy Path**: any clear signal: new directory, module, or architecture layer; new domain model, service class, or abstraction; security, authentication, authorization, or sessions; external API, message queue, or payment; DB schema or migration; concurrency, transaction boundaries, or cache invalidation; multi-domain refactor; the user asks for extra care ("신중하게", "검토 받고", "설계부터", "꼼꼼히").
+
+Record three triage checkpoints: request (provisional), planning (after exploration), and code (in `pota-work`, just before the first edit; pending blocks mutation). Before the first edit the route may change either way; after editing starts, only Light → Heavy promotion is allowed. Every route change synchronizes the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before mutation.
+
+## Procedure (Light and Heavy Path)
+
+1. Run `node "<pluginRoot>/scripts/pota.mjs" init --root "<repoRoot>"`. If unavailable, create `MEMORY.md`, `PLAN.md`, `docs/memory`, `docs/plan` and report that `pota doctor`/`pota upgrade` is needed.
+2. Read `MEMORY.md` and `PLAN.md` when present; pick related notes and past plans (`planning-rules.md`). A non-trivial implementation request authorizes the plan and goal even if the user never says "goal".
+3. Write the initial plan `docs/plan/<topic>.md` from `pota://templates/work-plan.md` plus its `PLAN.md` entry from the request and `MEMORY.md`: outcome, anticipated surfaces, stable roadmap, and `triage-plan` as first active task (investigation scope, toolcheck, Heavy criteria, update condition); mark it `initial: decision-complete for triage; not implementation-ready`.
+4. Before exploration, toolcheck, delegation, or a non-blocking question, call Codex `update_plan` first and then `create_goal` when available (main agent only, subagents skip; record unavailability; never claim sync that did not occur), then start the repository goal:
+
+```sh
+node "<pluginRoot>/scripts/pota.mjs" goal start --root "<repoRoot>" --goal "<objective>" --plan "docs/plan/<topic>.md" --tasks '[{"id":"triage-plan","title":"Run planned triage and finalize the plan","requiredEvidence":["planArtifact","triageDecision"]},{"id":"implement","title":"Implement the finalized plan"},{"id":"verify","title":"Verify and review the result"}]' --criteria "<completion criterion>" --session "<current session_id>"
+```
+
+   Pass `--session` only with an ID the surface exposes; never invent one. Fold new work into an unfinished goal with `goal replan` (resume a paused or blocked goal first), never cancel it; start a separate goal only when the user explicitly switches work. When a hook reports another session owns the goal you continue, run `goal claim --session <id>` with the ID shown.
+5. Run `triage-plan`: read the picked notes and plans and installed model guidance, run `toolcheck --root "<repoRoot>"`, and explore with focused search and LSP/symbol tools. Install tools only with explicit user approval.
+6. Split the whole work into tasks each verifiable with two checks, each with `dependsOn` and `writeScope` in the `--tasks` JSON and named handoff files for cross-task data (`delegation.md`); design the test contract (requirements, invariants, boundaries, failure modes, expected failure) and dry-run/check modes.
+7. Update the plan with route, checked Heavy signals, tool readiness, delegation, verification commands, stable IDs, and fail-closed required evidence (`planning-rules.md`). Mark it `decision-complete for implementation` and call `update_plan` again.
+8. Only then record bound `planArtifact` and `triageDecision` evidence, complete `triage-plan`, and continue with `pota-work`.
+9. Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, and records evidence. Implementation edits go to `worker` whenever subagent tools are available, on Light and Heavy Path; `explorer` does read-only discovery; without subagent tools the main agent takes over and records it.
+10. Advance a UI step only after the matching repository task transition succeeds.
+11. Ask the user only when evidence and local checks cannot decide. Use the OS locale for user-visible output and artifacts unless asked otherwise.
+
+Model and reasoning effort: This skill explicitly instructs the effort level for delegated work. Pick each task's model tier (fast `haiku`, balanced `sonnet`, stronger `opus`, strongest `fable`) and request Light `medium`, Heavy `high`, final verification/review `xhigh`. Every new task/worker dispatch MUST pass the task's model and effort via the host option (Claude Code: Agent `model`/`effort`; never `fork`). Recording without passing is a defect. Record Requested/Effective model and effort per task; mark Heavy tasks `route: "heavy"` (details: `delegation.md`).
+
+## Completion Criteria
+
+- `PLAN.md` references the plan topic.
+- `docs/plan/<topic>.md` includes goal, memory inputs, model guidance, tool readiness, complexity triage, selected path, agent assignments, module tasks, and two checks per task.
+- The next implementation task can run without making planning decisions.

package/skills/pota-plan/delegation.md

@@ -0,0 +1,65 @@
+# Pota Plan: Delegation and Reasoning Effort
+
+Reference for `pota-plan`. Read before dispatching `explorer` or `worker` agents or recording reasoning effort. Quick Path work done directly by the main agent does not need this file.
+
+## Subagent Lifecycle
+
+- Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, and records evidence.
+- Use `explorer` for independent read-only codebase discovery, impact analysis, pattern searches, and read-only verification that can run in parallel when the current tool list supports it.
+- Use `worker` for actual implementation edits with clear file ownership whenever subagent tools are available, on both Light Path and Heavy Path.
+- When the subagent tool provides a progress-reporting channel, require subagents to report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion.
+- Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete.
+- When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents, subject to the current surface's depth and concurrency limits.
+- If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence; do not stop solely because subagent tools are unavailable.
+- Keep urgent non-implementation blocking work local when the next step depends immediately on the result.
+- Tell every delegated agent and child subagent to read project-root `MEMORY.md` when present and continue when absent, keep scope, and tell workers they are not alone in the codebase and must not revert others' edits.
+- Put the selected `docs/memory/<domain>.md` note paths (picked from `MEMORY.md` entries) in the prompt `CONTEXT:` line. A delegated agent may not receive the session-start memory list, so do not rely on it reaching subagents.
+- Host task-list tools (`update_plan`, `create_goal`, `wrap_up`) are called by the main agent only; a worker or subagent skips them (hosts reject them from subagents) and reports in its final report.
+- Every plan must require these status, final-report, close-and-review, and recursive-delegation rules.
+
+## Task Graph
+
+- Every task in `goal start --tasks` / `goal replan --tasks` JSON declares `dependsOn` (task ids) and `writeScope` (literal repo-relative paths; no globs, `..`, or absolute paths). Example: `{"id":"api","title":"API","dependsOn":["triage-plan"],"writeScope":["src/api"]}`.
+- Omitted `dependsOn` means the previous task in list order (first task: none); explicit `[]` means no dependency, so sequential plans keep working. In `goal replan` the default chains across completed and new tasks, and `dependsOn` may reference completed tasks. Duplicate ids, unknown ids, self references, and cycles are rejected.
+- Omitted `writeScope` is null: that task can only be active alone. Give independent tasks disjoint scopes so they can run in parallel; scope is declarative, not filesystem-enforced.
+- Pota has no messaging channel: name the handoff files that carry data between tasks in the plan (`Handoff files:`) and include them in the producer's `writeScope`.
+
+## Delegation Prompt Format
+
+```text
+TASK: Produce <role> input needed for the <topic> plan.
+EXPECTED OUTCOME: Return concrete decisions, file paths, dependencies, risks, and evidence requirements.
+REQUIRED TOOLS: Read-only repository exploration, tool readiness checks, LSP/symbol tools, local command checks.
+MODEL: <tier/value> (passed via host option)
+REASONING EFFORT: <value> (passed via host option)
+MUST DO: Read the project-root `MEMORY.md` before doing assigned work. Preserve proper nouns exactly. Prefer repository evidence. Report missing tools and obtain explicit user approval before any installation. Identify assumptions. Follow the subagent lifecycle rules (status reporting when a channel exists, final report before leaving, recursive delegation only for bounded sub-tasks, passing each child's reasoning effort through the host option; report the exact model ID from your own system prompt in the final report, `unreported` if absent, never guess; skip host task-list tools `update_plan`, `create_goal`, `wrap_up`). Tell workers they are not alone in the codebase and must not revert others' edits. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
+MUST NOT DO: Edit production code. Ask the user. Expand scope. Delegate vague or unbounded work.
+CONTEXT: User request, MEMORY.md, selected `docs/memory/<domain>.md` note paths, applied model guidance, repository root, Pota CLI prefix line from the session-start hook.
+```
+
+## Model and Reasoning Effort Routing
+
+This skill explicitly instructs the effort level for delegated work. It also instructs each task's model.
+
+- The plan decides each task's model from its nature and records `Requested model` and `Effective model`; models are not always inherited. Tiers: fast = read-only exploration, search, inventory, summarization (Claude Code `haiku`); balanced = Light Path implementation and routine verification (`sonnet`); stronger = planning, complexity triage, Heavy Path implementation, review, and final verification/review (`opus`); strongest = Heavy Path design only (`fable`).
+- Model Effective is the passed value plus the exact model ID the worker reports from its own system prompt, e.g. `fable (claude-fable-5-1)`; when the report has no ID, record `<value> (unreported)` and never guess, via `goal assign --effective-model <id|unreported>`. Not passed is `not-applied: <reason>`; `inherited` only when the host has no model option. Codex passes the tier's slug (table below) through the host-native model option, else `inherited`.
+- If a lower-tier worker fails a gate, re-dispatch that task one tier up (fast, balanced, stronger, strongest) before recording a blocker.
+- A subagent's model and effort are fixed at dispatch. Any re-dispatch that changes either (one tier up, Light → Heavy promotion, route-change recalculation) MUST be a new dispatch (Claude Code: a new Agent call); never continue the existing subagent with `SendMessage`, which keeps its original model and effort.
+- Routing is per dispatch only; never change model or global/user config files. `Model routing: inherited` in `MEMORY.md` or the plan disables per-task selection.
+- Light Path planning, implementation, and verification request `medium`.
+- Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
+- Every new task/worker dispatch MUST pass the task's requested effort through the host option. Recording without passing is a defect. Pass the chosen model the same way (Claude Code: Agent `model`). Child (recursive) dispatches follow the same rule.
+- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`. Requested is Pota's desired profile; Effective is decided by the dispatch call:
+  - Effort passed and not rejected: Effective is the requested value.
+  - Effort not passed: `not-applied: <reason>`; the reason is required.
+  - `inherited` only when the host exposes no effort option. Describe host capability only from the exposed interface or dispatch response, and distinguish Pota non-integration from host non-support.
+
+| Host | Model / effort option | Effective |
+| --- | --- | --- |
+| Claude Code | Agent tool `model` parameter (`haiku\|sonnet\|opus\|fable`). `effort` parameter (`low\|medium\|high\|xhigh\|max`), matching Pota values one to one. `subagent_type: "fork"` ignores `model` and `effort`, so never dispatch routed work as a fork. | requested value |
+| Codex | Host-native model option (fast `gpt-6-luna`, balanced `gpt-6.1-terra`, stronger `gpt-6-sol`, strongest `gpt-6-astra`) and task/subagent reasoning-effort option or equivalent. | requested value |
+| Antigravity | `invoke_subagent` `Model` takes only a tier enum: fast `flash_lite`, balanced `flash`, stronger `pro`, strongest `pro` (no tier above `pro`); `inherit` is not used for routed work. No effort option. | model: passed value; effort: `inherited` |
+| Host without an option | None. | `inherited` |
+
+- After each dispatch, record state with `goal assign --task <id> --agent <id> --effort <value> --effort-source <host-option|inherited|not-applied>`; for a `kind: "design"` task also `--model <value> --model-source host-option --host <claude-code|codex|antigravity>`. A design model that is not the host's strongest tier (`--host claude-code` `fable`, `codex` `gpt-6-astra`, `antigravity` `pro`; any of the three when `--host` is omitted) fails completion unless `--allow-no-design-model <reason>`. Mark Heavy tasks with `route: "heavy"` (tasks JSON field or `goal assign --route heavy`). A Heavy task with no effort, `not-applied`, or `inherited` fails `goal task --status completed` unless `--allow-inherited-effort <reason>` records why.
+- On every route change, synchronize the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before mutation. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.