@comento/pota-harness 0.0.0-stage → 1.0.0

package/README.es.md

@@ -0,0 +1,166 @@
+# Pota Harness
+
+Pota Harness es un plugin de harness multi-agente eficiente en tokens para Codex, Claude Code y Antigravity.
+
+[English](README.md)
+
+La idea central es conservar comportamientos útiles de agent harness: hooks, estado persistente, planificación explícita, delegación enfocada y guardas al detenerse. Pota no hace que los bucles repetidos de verificación TDD sean el comportamiento predeterminado. En su lugar, divide el trabajo en pequeños module tasks y prueba cada task con dos verification gates.
+
+1. Module acceptance verification: prueba el contrato del módulo modificado.
+2. Surface integration verification: prueba el comportamiento a través de una superficie real, como CLI, HTTP, navegador o artefactos de archivo.
+
+Antes de que un task modifique estado externo, Pota registra y ejecuta el dry-run o check mode más cercano disponible. La verificación está acotada: cada task tiene dos verification passes por defecto; después, el agente registra un blocker o divide el task en lugar de continuar un bucle abierto.
+
+Pota también trata la preparación de herramientas como parte del trabajo. LSP, typecheck, lint, dry-run y verification tools se revisan contra el stack del repositorio. Solo se instala con aprobación explícita y un installer compatible y fijado; de lo contrario se registra un blocker.
+
+## Complexity Triage
+
+Cada implementation task pasa primero por complexity triage, antes de aplicar agent, plugin o delegated workflow guidance. El triage se decide a partir de la exploración del repositorio, el alcance esperado del cambio y señales de riesgo, sin preguntar al usuario por hechos que se puedan descubrir.
+
+- Light Path: cambios estrechos dentro de existing architecture layers. Es el valor predeterminado. Implementa directamente o usa un `worker` acotado, y conserva el verification gate.
+- Heavy Path: new directory/module/layer, new domain model/service/abstraction, security/session/auth, external API/message queue/payment, DB schema/migration, concurrency/transaction/cache changes, cross-domain refactor o una explicit extra-care request.
+
+El path seleccionado y su justificación se registran en `docs/plan/<topic>.md` cuando existe un plan artifact. Incluso en Light Path, se mantienen los dos verification gates.
+
+## Tool Readiness
+
+`pota toolcheck` inspecciona el repositorio actual para stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go y Rust, y luego revisa los LSP y verification tools correspondientes.
+
+```sh
+pota toolcheck --root .
+pota toolcheck --install --yes --root .
+```
+
+- `toolcheck` reporta detected stacks y missing tools.
+- `toolcheck --install` exige aprobación explícita y `--yes`; un installer no compatible devuelve el resultado canónico `installer-unavailable` y no se ejecuta.
+- Los planes de Pota registran detected stack, required tools, install commands y blockers.
+- Que falte un LSP server no es razón válida para saltarse precise codebase exploration hasta intentar installation o un fallback symbol-aware equivalente.
+
+## Dry-Run And Loop Policy
+
+- Migrations y database changes usan `--pretend`, dry-run, schema diff, rollback feasibility checks o el equivalente repository-native más cercano antes de comandos write/apply.
+- Package, release, infrastructure, deployment, code generation y formatting work usan check, plan, diff, validate o dry-run modes antes de mutar estado cuando están disponibles.
+- Si no existe dry-run, el plan registra ese hecho y elige el comando reversible más pequeño o el artefacto de prueba disponible.
+- Si falla un verification gate, Pota diagnostica una vez, reduce o divide el task y vuelve a ejecutar ambos gates.
+- Después de dos verification passes fallidos para el mismo task, Pota registra el blocker en `docs/plan/<topic>.md` en lugar de continuar un bucle repetido.
+
+## Model Guidance
+
+Pota solo aplica ajustes específicos de modelo a modelos Claude-family y Codex-family.
+
+- Claude-family: útil para long context, policy interpretation y plan/evidence review.
+- Codex-family: útil para small implementation tasks, explicit file edits, command-based verification y bounded `worker` tasks.
+
+La guía detallada vive en el plugin instalado y se referencia como `pota://docs/model-guidance/README.md`, `pota://docs/model-guidance/claude.md` y `pota://docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+El harness crea y mantiene estos archivos en la raíz del repositorio objetivo.
+
+- `MEMORY.md`: índice corto de conocimiento persistente del dominio: una línea por nota bajo `## Domain Knowledge` (`- [<name>](docs/memory/<name>.md): <summary>`) más la `## Policy` del repositorio.
+- `docs/memory/*.md`: conocimiento detallado por dominio. Cada nota empieza con una línea `Summary:` (120 caracteres como máximo) que muestran el índice y el hook.
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/state.json`: estado active goal/task/evidence en user-home, aislado por proyecto y worktree, para recuperación y scoped stop gates. El working tree no posee runtime state.
+- `PLAN.md`: índice corto de planes de trabajo: una línea de 200 caracteres o menos por plan bajo `## Active Plans` y `## Completed Plans`. Las reglas de planificación viven en el skill `pota-plan`, no en `PLAN.md`.
+- `docs/plan/*.md`: planes de ejecución detallados.
+- `docs/plan/ARCHIVE.md`: entradas completadas antiguas que `pota plan index --archive` movió desde `PLAN.md`, de la más nueva a la más antigua, más el cuerpo de una sección legacy `## Planning Rules` bajo `## Legacy Planning Rules`. Las líneas de lista antes de su primer encabezado `## ` siguen contando como indexadas.
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/history.jsonl`: un registro resumen por goal completado o cancelado (los 200 más recientes por worktree) para `goal stats --history`.
+
+Mantén `## Completed Plans` de la más nueva a la más antigua. `pota plan index --archive` conserva las primeras 20 entradas y mueve el resto a `docs/plan/ARCHIVE.md` sin borrar nada, así que una lista ordenada de la más antigua a la más nueva archivaría los planes más recientes; revisa antes con `--dry-run`. Los `MEMORY.md`/`PLAN.md` existentes funcionan sin migración: `init` nunca los reescribe y `check` solo avisa del formato antiguo con warnings.
+
+En `SessionStart`, el hook indica al agente qué notas de memoria existen (nombre y `Summary:`, o una sola línea con nombres cuando la lista es larga) y, sin goal activo, añade una línea sobre el índice de planes: número de planes, planes activos, los últimos planes completados y `docs/plan/ARCHIVE.md` si existe. Con un goal active, paused, blocked o de otra sesión solo se añade la lista de memoria, y la cápsula de otra sesión nunca muestra nombres de planes. Un `UserPromptSubmit` sin goal añade una frase con el número de notas. El hook solo lee los archivos índice y los listados de directorio, nunca el cuerpo de las notas, y no escribe nada; un repositorio sin notas ni planes recibe la misma salida que antes.
+
+Antes de `goal finish`, `pota-work` registra una decisión de memory promotion por goal en la Evidence del plan: `Memory promotion: docs/memory/<domain>.md` cuando el goal produjo conocimiento reutilizable del repositorio, o `Memory promotion: none: <reason>` en caso contrario. La decisión es obligatoria; escribir una nota es opcional. Si un goal se completa y su archivo de plan no tiene una línea `Memory promotion:` rellenada, `goal finish` y `goal complete` imprimen un recordatorio de una línea en stderr sin cambiar el exit code ni stdout.
+
+Los archivos raíz se mantienen cortos y los detalles pasan a `docs/`, para que los agentes lean solo el contexto que necesitan.
+
+Para ahorrar tokens, define primero un test contract con requisitos, invariantes, límites y modos de fallo. Usa el tool exit code de `goal verify -- <argv>` como autoridad, resume el éxito y amplía el contexto solo al fallar. Inspecciona el package lifecycle y ejecuta normalmente `npm pack --dry-run`. Los scripts content-producing o desconocidos nunca deben usar `--ignore-scripts`; úsalo solo si no hay scripts o son content-neutral demostrados y la evidencia del full check sigue vigente.
+
+## Commands
+
+El paquete publicado puede ejecutarse con `bunx` o con comandos `pota` instalados globalmente.
+
+```sh
+bunx @comento/pota-harness@latest install
+bunx @comento/pota-harness@latest upgrade
+bunx @comento/pota-harness@latest doctor
+bunx @comento/pota-harness@latest uninstall
+bunx @comento/pota-harness@latest toolcheck
+```
+
+Después de una instalación global, también están disponibles comandos cortos.
+
+```sh
+bun add -g @comento/pota-harness
+pota install
+pota upgrade
+pota doctor
+pota uninstall
+pota toolcheck
+pota auto-upgrade status
+```
+
+- `pota install [--hosts all|codex,claude,antigravity]`: instala de forma transaccional custom marketplace source, versioned runtime, secciones config propias de Pota y mirrors actuales. El canonical runtime vive en `~/.pota/install/` y el resto se instala solo para los hosts elegidos. Sin `--hosts`, la primera instalación en una terminal pregunta los hosts; las ejecuciones no interactivas y CI instalan todos.
+- `pota upgrade [--hosts all|codex,claude,antigravity]`: reemplaza solo entradas sin modificar del ownership manifest tras staged validation y usa rollback al fallar. Mantiene los hosts registrados salvo que `--hosts` los cambie y actualiza un Claude Code plugin cache que aún tenga otra versión. Si la versión instalada es más nueva que esta CLI, `install` y `upgrade` se niegan sin cambiar nada; `--allow-downgrade` instala de todos modos la versión de esta CLI.
+- `pota doctor`: valida ownership digests, features efectivos de Codex, el estado real del plugin y runtime locators sin reparar. Imprime primero `Hosts: <ids>` y solo revisa los hosts elegidos (incluido `Claude plugin cache version`).
+- `pota uninstall`: primero compara cada entrada no config del ownership manifest con su installed digest y rechaza todo el uninstall, sin cambiar nada, si algún managed artifact fue modificado o eliminado. Si no, elimina o restaura las entradas gestionadas y los retained runtimes, limpia los managed scaffolds vacíos, preserva los objetivos unmanaged y sus directorios padre, y aplica rollback a los fallos anteriores al commit. También elimina `~/.pota/update/`, y conserva `~/.pota/config.json` y `~/.pota/projects/`. Una instalación con layout legacy se elimina en su sitio sin migrarla.
+- `pota auto-upgrade status|on|off|run`: `status` imprime en JSON la configuración, la versión instalada, la última comprobación y el aviso pendiente; `on`/`off` escriben `autoUpgrade` en `~/.pota/config.json` e imprimen el mismo informe; `run` consulta npm ahora, sin esperar el intervalo de 24 horas ni el backoff. Exit 0 es éxito, 1 un error de ejecución o una ejecución fallida y 2 un error de uso.
+- `pota toolcheck`: detecta repository stacks y revisa required tools; solo ejecuta un installer compatible aprobado, o devuelve `installer-unavailable`.
+- `pota cleanup --root <repo>`: por defecto informa en modo read-only el residuo legacy `.pota` local al proyecto. `--yes` migra/reconcilia active state válido al almacén user-home, elimina solo residuos conocidos de state/lock/tool, conserva archivos desconocidos y poda el directorio solo si queda vacío.
+- `pota memory check|index [--root <repo>]`: `check` compara `MEMORY.md` con `docs/memory/*.md` e imprime un informe JSON; sale con 1 ante notas sin indexar, dead links, duplicados, resúmenes desactualizados, caracteres de control en resúmenes o rutas inseguras, y los warnings solo fallan con `--strict`. Las entradas son líneas de lista bajo `## Domain Knowledge` (o todas las líneas de lista en un archivo antiguo sin esa sección); un enlace a una nota en otra sección es una mención que `index` nunca reescribe. `index` añade las notas que faltan y, si el `Summary:` cambió, reemplaza solo el resumen tras el enlace (una línea con varios enlaces queda como está); solo elimina líneas placeholder de Pota que coinciden exactamente dentro de esa sección, nunca borra entradas ni dead links y conserva el resto byte a byte. `--dry-run` muestra una vista previa. Si el punto de inserción está dentro de un bloque de código sin cerrar, `index` no escribe nada y sale con 1 con `unclosed-fence`. Los errores de uso salen con 2; `pota memory` sin subcomando sigue mostrando la guía.
+- `pota plan check|index [--archive] [--root <repo>]`: lo mismo para `PLAN.md` y `docs/plan/*.md`, cuyas entradas son líneas de lista bajo encabezados `## ` que terminan en `Plans` (como `## Superseded Plans`). `index` coloca un plan con todas sus casillas marcadas al principio de `## Completed Plans` y cualquier otro en `## Active Plans`; solo `--archive` mueve líneas a `docs/plan/ARCHIVE.md`: las entradas completadas más allá de las 20 más nuevas, con sus párrafos sangrados, y el cuerpo de una sección legacy `## Planning Rules`. `check` avisa cuando `## Completed Plans` supera 20 entradas o queda una sección legacy `## Planning Rules`.
+- `pota goal ...`: gestiona el goal del repositorio (`pota goal --help`). `goal stats --history [--limit N]` agrega los goals terminados del repositorio en todos sus worktrees: recuentos completed/cancelled, mediana y p90 de duración, medianas de tasks y receipts, tasa de reruns, decisiones de memory promotion, un `trend` older/newer desde 4 goals completados y los goals recientes; sin historial imprime `{"schemaVersion":1,"scope":"repository","goals":0}`. `completionCriteria` (`goal start --criteria`) es `advisory`: Pota lo registra pero no lo hace cumplir, y la finalización depende solo de la evidencia requerida.
+- `pota-memory`: explora domain knowledge y actualiza `MEMORY.md`.
+- `pota-plan`: crea un decision-complete plan bajo `docs/plan/`.
+- `pota-work`: ejecuta el siguiente module task del `PLAN.md` actual con dos verification gates.
+- `pota-review`: revisa completed tasks contra plan, memory y evidence.
+
+El custom marketplace lifecycle mantiene separados source y versioned runtime. Staged validation precede cada commit, el ownership manifest vincula todos los managed digests y un fallo aplica reverse-order rollback. Los artifacts modified o unmanaged se preservan y se reportan como conflict. Pota modifica solo sus propias TOML sections y no fuerza feature/agent settings públicos.
+
+Clean uninstall elimina `~/.pota/install/` y el Codex cache root `$CODEX_HOME/plugins/cache/pota` solo cuando todos los managed scaffold directories están vacíos; cualquier contenido unmanaged se conserva. No elimina el source repository, los `MEMORY.md`/`PLAN.md` del repository ni el Pota goal state de user-home, el paquete global `@comento/pota-harness`, los package-manager caches ni legacy backups/settings fuera del ownership manifest actual.
+
+Codex usa `skills/` y `commands/`. Claude Code usa comandos reflejados y definiciones de agentes bajo `.claude/`. Antigravity usa `.agents/workflows` y mirrors globales de skills.
+
+## Install Layout And Auto-Upgrade
+
+Pota guarda la instalación bajo `POTA_HOME` (por defecto `~/.pota`). Las rutas de cada host siguen definiéndose por separado con `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME` y `CODEX_CONFIG_PATH`.
+
+```text
+~/.pota/
+  install/                  archivos gestionados por el lifecycle
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime que usan todos los runtime locators y los hooks de Claude Code
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               ajustes del usuario ("autoUpgrade")
+  update/                   estado de auto-upgrade
+$CODEX_HOME/plugins/cache/pota/pota/<version>/   copia en el Codex plugin cache (solo si se elige Codex)
+```
+
+- Hosts: solo `install` y `upgrade` aceptan `--hosts`, con `all` o una lista separada por comas de `codex`, `claude` y `antigravity`. La selección queda en el ownership manifest y `upgrade`, `doctor` y `uninstall` la siguen. Se cambia con `pota upgrade --hosts <list>`; si un archivo gestionado de un host retirado fue modificado, se rechaza. El prompt interactivo (todos por defecto, solo Claude Code, solo Codex, solo Antigravity o una lista) aparece solo cuando aún no hay nada instalado.
+- Retención: un upgrade que cambia de versión conserva el canonical runtime anterior y la copia del Codex cache durante 3 días (como máximo 3 de cada tipo) para que las sesiones iniciadas antes sigan funcionando. El siguiente install o upgrade elimina las vencidas y uninstall las elimina todas. Nunca se conserva una copia del Codex cache igual o superior a la nueva versión, porque Codex carga la versión más alta del cache.
+- Claude Code plugin cache: si aún tiene otra versión, `pota upgrade` lo actualiza con `claude plugin marketplace update pota` y `claude plugin update pota@pota --scope user`. Si falla, la instalación actualizada se mantiene, se imprimen los comandos para terminar a mano y sale con exit 1.
+- Auto-upgrade: activado por defecto. Como máximo una vez cada 24 horas (y no en las 24 horas siguientes a un install o upgrade), `SessionStart` lanza un proceso separado que lee la última versión de `@comento/pota-harness` en npm, instala esa versión exacta con `--ignore-scripts` en `~/.pota/update/stage/`, la verifica y ejecuta su `pota-lifecycle.mjs upgrade --auto`. Aplica todas las versiones nuevas, incluidas las major, y nunca hace downgrade. El siguiente `SessionStart` muestra el resultado (`updated`, `failed` o `manual`) en una línea, una sola vez. No funciona en instalaciones desde un git checkout (`origin: "checkout"`) ni al ejecutar desde un source checkout.
+- Desactivar: `pota auto-upgrade off`, `POTA_AUTO_UPGRADE=0` (también `false`, `off` o `no`) o `"autoUpgrade": false` en `~/.pota/config.json`. Un `config.json` ilegible también lo desactiva. El estado y el log de la última ejecución están en `~/.pota/update/`.
+
+## Antigravity Compatibility
+
+Antigravity soporta Agent Skills y Workflows basados en `SKILL.md` invocados como `/workflow-name`. Pota instala estas rutas para esa superficie.
+
+- Antigravity IDE: `~/.gemini/config/skills/pota-*/SKILL.md`.
+- Antigravity CLI: archivos skill planos en `~/.gemini/antigravity-cli/skills/pota-*.md`.
+
+Los hooks exclusivos de Codex no se portan a Antigravity. En su lugar, los mismos procedimientos de planning, memory, complexity triage y two-gate verification se ejecutan mediante Skills y Workflows. Define `ANTIGRAVITY_HOME` o `ANTIGRAVITY_CLI_HOME` para sobrescribir las rutas.
+
+## Locale Policy
+
+Las instrucciones reutilizables de Pota están escritas en inglés para uso global. El output visible para el usuario y la documentation, los plans y los memory artifacts generados o actualizados deben seguir el OS locale configurado, salvo que el usuario pida otro idioma explícitamente. Esto incluye el contenido de `MEMORY.md`, `PLAN.md`, `docs/memory` y `docs/plan`. La CLI localiza mensajes comunes para `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` y `pt`, y vuelve a English para locales no soportados. El texto `statusMessage` de Codex hooks permanece en inglés estático, mientras que hook command output es English o Korean.
+
+## Delegation
+
+- `explorer`: maneja read-only codebase discovery, impact analysis, pattern searches y read-only verification cuando está disponible.
+- `worker`: maneja bounded implementation o verification tasks con file ownership claro.
+- Main session: mantiene local el urgent blocking work cuando el siguiente paso depende inmediatamente del resultado.
+
+Cada delegation prompt usa seis secciones: TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.

package/README.fr.md

@@ -0,0 +1,166 @@
+# Pota Harness
+
+Pota Harness est un plugin de harness multi-agent économe en tokens pour Codex, Claude Code et Antigravity.
+
+[English](README.md)
+
+L'idée centrale est de conserver des comportements utiles d'agent harness : hooks, état persistant, planification explicite, délégation ciblée et gardes au moment de l'arrêt. Pota ne fait pas des boucles répétées de vérification TDD le comportement par défaut. Il découpe plutôt le travail en petits module tasks et prouve chaque task avec deux verification gates.
+
+1. Module acceptance verification : prouve le contrat du module modifié.
+2. Surface integration verification : prouve le comportement via une surface réelle, comme CLI, HTTP, navigateur ou artefacts de fichiers.
+
+Avant qu'un task ne modifie un état externe, Pota enregistre et exécute le dry-run ou check mode disponible le plus proche. La vérification est bornée : chaque task reçoit deux verification passes par défaut, puis l'agent enregistre un blocker ou divise le task au lieu de continuer une boucle ouverte.
+
+Pota traite aussi la préparation des outils comme une partie du travail. LSP, typecheck, lint, dry-run et verification tools sont vérifiés par rapport au stack du repository. Une installation exige une approbation explicite et un installer pris en charge et épinglé ; sinon un blocker est signalé.
+
+## Complexity Triage
+
+Chaque implementation task passe d'abord par complexity triage, avant d'appliquer agent, plugin ou delegated workflow guidance. Le triage est décidé à partir de l'exploration du repository, de la portée attendue du changement et des signaux de risque, sans demander à l'utilisateur les faits découvrables.
+
+- Light Path : changements étroits dans les existing architecture layers. C'est le comportement par défaut. Implémentez directement ou utilisez un `worker` borné, puis conservez le verification gate.
+- Heavy Path : new directory/module/layer, new domain model/service/abstraction, security/session/auth, external API/message queue/payment, DB schema/migration, concurrency/transaction/cache changes, cross-domain refactor ou explicit extra-care request.
+
+Le path choisi et sa justification sont enregistrés dans `docs/plan/<topic>.md` quand un plan artifact existe. Même en Light Path, les deux verification gates restent.
+
+## Tool Readiness
+
+`pota toolcheck` inspecte le repository courant pour les stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go et Rust, puis vérifie les LSP et verification tools correspondants.
+
+```sh
+pota toolcheck --root .
+pota toolcheck --install --yes --root .
+```
+
+- `toolcheck` signale les detected stacks et missing tools.
+- `toolcheck --install` exige une approbation explicite et `--yes` ; un installer non pris en charge renvoie le résultat canonique `installer-unavailable` sans s'exécuter.
+- Les plans Pota enregistrent detected stack, required tools, install commands et blockers.
+- Un LSP server manquant n'est pas une raison valable pour ignorer precise codebase exploration tant qu'une installation ou un fallback symbol-aware équivalent n'a pas été tenté.
+
+## Dry-Run And Loop Policy
+
+- Migrations et database changes utilisent `--pretend`, dry-run, schema diff, rollback feasibility checks ou l'équivalent repository-native le plus proche avant les commandes write/apply.
+- Package, release, infrastructure, deployment, code generation et formatting work utilisent check, plan, diff, validate ou dry-run modes avant de modifier l'état quand c'est disponible.
+- Si aucun dry-run n'existe, le plan l'enregistre et choisit la plus petite commande réversible ou le test artifact disponible.
+- Si une verification gate échoue, Pota diagnostique une fois, réduit ou divise le task, puis relance les deux gates.
+- Après deux verification passes échouées pour le même task, Pota enregistre le blocker dans `docs/plan/<topic>.md` au lieu de continuer une boucle répétée.
+
+## Model Guidance
+
+Pota applique des ajustements spécifiques uniquement aux modèles Claude-family et Codex-family.
+
+- Claude-family : utile pour long context, policy interpretation et plan/evidence review.
+- Codex-family : utile pour small implementation tasks, explicit file edits, command-based verification et bounded `worker` tasks.
+
+Les détails se trouvent dans le plugin installé sous `pota://docs/model-guidance/README.md`, `pota://docs/model-guidance/claude.md` et `pota://docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+Le harness crée et maintient ces fichiers à la racine du repository cible.
+
+- `MEMORY.md` : index court de persistent domain knowledge : une ligne par note sous `## Domain Knowledge` (`- [<name>](docs/memory/<name>.md): <summary>`), plus la `## Policy` du dépôt.
+- `docs/memory/*.md` : connaissances détaillées par domaine. Chaque note commence par une ligne `Summary:` (120 caractères au maximum) que l'index et le hook affichent.
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/state.json` : état active goal/task/evidence dans user-home, isolé par projet et worktree, pour la reprise et les scoped stop gates. Le working tree ne possède pas le runtime state.
+- `PLAN.md` : index court des plans de travail : une ligne de 200 caractères au plus par plan sous `## Active Plans` et `## Completed Plans`. Les règles de planification vivent dans le skill `pota-plan`, pas dans `PLAN.md`.
+- `docs/plan/*.md` : detailed execution plans.
+- `docs/plan/ARCHIVE.md` : anciennes entrées terminées déplacées hors de `PLAN.md` par `pota plan index --archive`, de la plus récente à la plus ancienne, plus le corps d'une section legacy `## Planning Rules` sous `## Legacy Planning Rules`. Les lignes de liste avant son premier titre `## ` comptent toujours comme indexées.
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/history.jsonl` : un enregistrement de synthèse par goal terminé ou annulé (les 200 plus récents par worktree) pour `goal stats --history`.
+
+Gardez `## Completed Plans` de la plus récente à la plus ancienne. `pota plan index --archive` conserve les 20 premières entrées et déplace le reste vers `docs/plan/ARCHIVE.md` sans rien supprimer ; une liste tenue de la plus ancienne à la plus récente archiverait donc les plans les plus récents. Vérifiez d'abord avec `--dry-run`. Les `MEMORY.md`/`PLAN.md` existants fonctionnent sans migration : `init` ne les réécrit jamais et `check` signale l'ancien format uniquement par des warnings.
+
+Au `SessionStart`, le hook indique à l'agent quelles notes de mémoire existent (nom et `Summary:`, ou une seule ligne de noms quand la liste est longue) et, sans goal actif, ajoute une ligne sur l'index des plans : nombre de plans, plans actifs, derniers plans terminés et `docs/plan/ARCHIVE.md` s'il existe. Avec un goal active, paused, blocked ou détenu par une autre session, seule la liste de mémoire est ajoutée, et la capsule d'une autre session n'affiche jamais de noms de plans. Un `UserPromptSubmit` sans goal ajoute une phrase avec le nombre de notes. Le hook lit uniquement les fichiers d'index et les listes de répertoires, jamais le corps des notes, et n'écrit rien ; un dépôt sans notes ni plans reçoit la même sortie qu'avant.
+
+Avant `goal finish`, `pota-work` consigne une décision de memory promotion par goal dans l'Evidence du plan : `Memory promotion: docs/memory/<domain>.md` quand le goal a produit une connaissance réutilisable du dépôt, sinon `Memory promotion: none: <reason>`. La décision est obligatoire ; écrire une note est facultatif. Quand un goal se termine et que son fichier de plan n'a pas de ligne `Memory promotion:` renseignée, `goal finish` et `goal complete` affichent un rappel d'une ligne sur stderr sans changer l'exit code ni stdout.
+
+Les fichiers racine restent courts et les détails vont sous `docs/`, afin que les agents ne lisent que le contexte nécessaire.
+
+Pour économiser les tokens, définissez d'abord un test contract couvrant exigences, invariants, limites et modes d'échec. Prenez le tool exit code de `goal verify -- <argv>` comme autorité, résumez les succès et n'élargissez le contexte qu'en cas d'échec. Inspectez le package lifecycle et exécutez normalement `npm pack --dry-run`. Les scripts content-producing ou inconnus ne doivent jamais utiliser `--ignore-scripts`; utilisez-le seulement si les scripts sont absents ou prouvés content-neutral et si la preuve du full check reste valide.
+
+## Commands
+
+Le package publié peut être exécuté avec `bunx` ou avec des commandes `pota` installées globalement.
+
+```sh
+bunx @comento/pota-harness@latest install
+bunx @comento/pota-harness@latest upgrade
+bunx @comento/pota-harness@latest doctor
+bunx @comento/pota-harness@latest uninstall
+bunx @comento/pota-harness@latest toolcheck
+```
+
+Après une installation globale, des commandes courtes sont aussi disponibles.
+
+```sh
+bun add -g @comento/pota-harness
+pota install
+pota upgrade
+pota doctor
+pota uninstall
+pota toolcheck
+pota auto-upgrade status
+```
+
+- `pota install [--hosts all|codex,claude,antigravity]` : installe transactionnellement custom marketplace source, versioned runtime, sections config propres à Pota et mirrors actuels. Le canonical runtime se trouve sous `~/.pota/install/` et le reste n'est installé que pour les hosts choisis. Sans `--hosts`, une première installation dans un terminal demande les hosts ; les exécutions non interactives et la CI installent tous les hosts.
+- `pota upgrade [--hosts all|codex,claude,antigravity]` : remplace uniquement les entrées intactes du ownership manifest après staged validation, avec rollback en cas d'échec. Conserve les hosts enregistrés sauf si `--hosts` les change et met à jour un Claude Code plugin cache resté sur une autre version. Si la version installée est plus récente que cette CLI, `install` et `upgrade` refusent sans rien changer ; `--allow-downgrade` installe quand même la version de cette CLI.
+- `pota doctor` : valide ownership digests, features Codex effectives, état réel du plugin et runtime locators sans réparation. Affiche d'abord `Hosts: <ids>` et ne vérifie que les hosts choisis (y compris `Claude plugin cache version`).
+- `pota uninstall` : compare d'abord chaque entrée non config du ownership manifest à son installed digest et refuse tout l'uninstall, sans rien changer, si un managed artifact a été modifié ou supprimé. Sinon, supprime ou restaure les entrées gérées et les retained runtimes, nettoie les managed scaffolds vides, préserve les cibles unmanaged et leurs répertoires parents, et applique un rollback aux échecs avant commit. Supprime aussi `~/.pota/update/`, et conserve `~/.pota/config.json` et `~/.pota/projects/`. Une installation au layout legacy est supprimée sur place, sans migration.
+- `pota auto-upgrade status|on|off|run` : `status` affiche en JSON le réglage, la version installée, la dernière vérification et la notification en attente ; `on`/`off` écrivent `autoUpgrade` dans `~/.pota/config.json` et affichent le même rapport ; `run` interroge npm immédiatement, sans attendre l'intervalle de 24 heures ni le backoff. Exit 0 signifie succès, 1 une erreur d'exécution ou une exécution échouée, 2 une erreur d'usage.
+- `pota toolcheck` : détecte repository stacks et vérifie required tools ; seul un installer approuvé et pris en charge s'exécute, sinon `installer-unavailable`.
+- `pota cleanup --root <repo>` : signale par défaut, en lecture seule, les résidus legacy `.pota` locaux au projet. `--yes` migre/réconcilie le valid active state vers le stockage user-home, supprime uniquement les résidus connus state/lock/tool, préserve les fichiers inconnus et ne supprime le répertoire que s'il est vide.
+- `pota memory check|index [--root <repo>]` : `check` compare `MEMORY.md` à `docs/memory/*.md` et affiche un rapport JSON ; il sort avec 1 en cas de notes non indexées, dead links, doublons, résumés périmés, caractères de contrôle dans les résumés ou chemins non sûrs, et les warnings n'échouent qu'avec `--strict`. Les entrées sont les lignes de liste sous `## Domain Knowledge` (ou toutes les lignes de liste d'un ancien fichier sans cette section) ; un lien vers une note dans une autre section est une mention que `index` ne réécrit jamais. `index` ajoute les notes manquantes et, si le `Summary:` a changé, remplace seulement le résumé après le lien (une ligne à plusieurs liens reste telle quelle) ; il ne supprime que les lignes placeholder de Pota exactement identiques dans cette section, jamais d'entrées ni de dead links, et conserve le reste octet pour octet. `--dry-run` donne un aperçu. Si le point d'insertion est dans un bloc de code non fermé, `index` n'écrit rien et sort avec 1 avec `unclosed-fence`. Les erreurs d'usage sortent avec 2 ; `pota memory` sans sous-commande affiche toujours le guide.
+- `pota plan check|index [--archive] [--root <repo>]` : la même chose pour `PLAN.md` et `docs/plan/*.md`, dont les entrées sont les lignes de liste sous les titres `## ` finissant par `Plans` (comme `## Superseded Plans`). `index` place un plan dont toutes les cases sont cochées en tête de `## Completed Plans` et tout autre plan dans `## Active Plans` ; seul `--archive` déplace des lignes vers `docs/plan/ARCHIVE.md` : les entrées terminées au-delà des 20 plus récentes, avec leurs paragraphes indentés, et le corps d'une section legacy `## Planning Rules`. `check` avertit quand `## Completed Plans` dépasse 20 entrées ou qu'une section legacy `## Planning Rules` subsiste.
+- `pota goal ...` : gère le goal du dépôt (`pota goal --help`). `goal stats --history [--limit N]` agrège les goals terminés du dépôt sur tous ses worktrees : nombres completed/cancelled, médiane et p90 de durée, médianes de tasks et de receipts, taux de reruns, décisions de memory promotion, un `trend` older/newer dès 4 goals terminés et les goals récents ; sans historique il affiche `{"schemaVersion":1,"scope":"repository","goals":0}`. `completionCriteria` (`goal start --criteria`) est `advisory` : Pota l'enregistre sans l'imposer, et la complétion dépend uniquement des preuves requises.
+- `pota-memory` : explore domain knowledge et met à jour `MEMORY.md`.
+- `pota-plan` : crée un decision-complete plan sous `docs/plan/`.
+- `pota-work` : exécute le prochain module task du `PLAN.md` courant avec deux verification gates.
+- `pota-review` : relit completed tasks par rapport au plan, memory et evidence.
+
+Le custom marketplace lifecycle sépare source et versioned runtime. Staged validation précède chaque commit, le ownership manifest lie tous les managed digests et un échec déclenche un reverse-order rollback. Les artifacts modified ou unmanaged sont preserved et signalés comme conflict. Pota ne modifie que ses propres TOML sections et ne force aucun feature/agent setting public.
+
+Clean uninstall supprime `~/.pota/install/` et le Codex cache root `$CODEX_HOME/plugins/cache/pota` uniquement lorsque tous les managed scaffold directories sont vides ; tout contenu unmanaged est conservé. Il ne supprime ni le source repository, les `MEMORY.md`/`PLAN.md` du repository ou le Pota goal state de user-home, ni le package global `@comento/pota-harness`, les package-manager caches ou les legacy backups/settings hors du ownership manifest courant.
+
+Codex utilise `skills/` et `commands/`. Claude Code utilise les commandes miroir et définitions d'agents sous `.claude/`. Antigravity utilise `.agents/workflows` et les global skills mirrors.
+
+## Install Layout And Auto-Upgrade
+
+Pota place son installation sous `POTA_HOME` (par défaut `~/.pota`). Les chemins de chaque host restent définis séparément par `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME` et `CODEX_CONFIG_PATH`.
+
+```text
+~/.pota/
+  install/                  fichiers gérés par le lifecycle
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime utilisé par tous les runtime locators et les hooks Claude Code
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               réglages utilisateur ("autoUpgrade")
+  update/                   état de l'auto-upgrade
+$CODEX_HOME/plugins/cache/pota/pota/<version>/   copie dans le Codex plugin cache (seulement si Codex est choisi)
+```
+
+- Hosts : seuls `install` et `upgrade` acceptent `--hosts`, avec `all` ou une liste séparée par des virgules de `codex`, `claude` et `antigravity`. La sélection est enregistrée dans le ownership manifest et suivie par `upgrade`, `doctor` et `uninstall`. On la change avec `pota upgrade --hosts <list>` ; un fichier géré modifié d'un host retiré entraîne un refus. Le prompt interactif (tous par défaut, Claude Code seul, Codex seul, Antigravity seul ou une liste) n'apparaît que si rien n'est encore installé.
+- Rétention : un upgrade qui change de version garde le canonical runtime précédent et la copie du Codex cache pendant 3 jours (au plus 3 de chaque type) pour que les sessions démarrées avant continuent de fonctionner. Le install ou upgrade suivant supprime ceux qui ont expiré, et uninstall les supprime tous. Une copie du Codex cache égale ou supérieure à la nouvelle version n'est jamais gardée, car Codex charge la version la plus haute du cache.
+- Claude Code plugin cache : s'il contient encore une autre version, `pota upgrade` le met à jour avec `claude plugin marketplace update pota` et `claude plugin update pota@pota --scope user`. En cas d'échec, l'installation mise à jour est conservée, les commandes pour terminer à la main sont affichées et la sortie est exit 1.
+- Auto-upgrade : activé par défaut. Au plus une fois toutes les 24 heures (et pas dans les 24 heures qui suivent un install ou un upgrade), `SessionStart` lance un processus détaché qui lit la dernière version de `@comento/pota-harness` sur npm, installe cette version exacte avec `--ignore-scripts` dans `~/.pota/update/stage/`, la vérifie, puis exécute son `pota-lifecycle.mjs upgrade --auto`. Toutes les nouvelles versions sont appliquées, major comprises, sans jamais de downgrade. Le `SessionStart` suivant affiche le résultat (`updated`, `failed` ou `manual`) en une ligne, une seule fois. Rien ne s'exécute pour une installation depuis un git checkout (`origin: "checkout"`) ni depuis un source checkout.
+- Désactiver : `pota auto-upgrade off`, `POTA_AUTO_UPGRADE=0` (ou `false`, `off`, `no`) ou `"autoUpgrade": false` dans `~/.pota/config.json`. Un `config.json` illisible le désactive aussi. L'état et le log de la dernière exécution se trouvent dans `~/.pota/update/`.
+
+## Antigravity Compatibility
+
+Antigravity prend en charge les Agent Skills et Workflows basés sur `SKILL.md`, invoqués comme `/workflow-name`. Pota installe ces paths pour cette surface.
+
+- Antigravity IDE : `~/.gemini/config/skills/pota-*/SKILL.md`.
+- Antigravity CLI : fichiers skill plats sous `~/.gemini/antigravity-cli/skills/pota-*.md`.
+
+Les hooks propres à Codex ne sont pas portés vers Antigravity. À la place, les mêmes procédures planning, memory, complexity triage et two-gate verification s'exécutent via Skills et Workflows. Définissez `ANTIGRAVITY_HOME` ou `ANTIGRAVITY_CLI_HOME` pour remplacer les paths.
+
+## Locale Policy
+
+Les instructions réutilisables de Pota sont écrites en anglais pour un usage global. La sortie visible par l'utilisateur ainsi que la documentation, les plans et les artifacts mémoire générés ou mis à jour doivent suivre l'OS locale configurée, sauf si l'utilisateur demande explicitement une autre langue. Cela inclut le contenu de `MEMORY.md`, `PLAN.md`, `docs/memory` et `docs/plan`. La CLI localise les messages communs pour `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` et `pt`, puis revient à English pour les locales non prises en charge. Le texte `statusMessage` des Codex hooks reste en anglais statique, tandis que hook command output est English ou Korean.
+
+## Delegation
+
+- `explorer` : gère read-only codebase discovery, impact analysis, pattern searches et read-only verification quand disponible.
+- `worker` : gère des bounded implementation ou verification tasks avec file ownership clair.
+- Main session : garde local l'urgent blocking work quand l'étape suivante dépend immédiatement du résultat.
+
+Chaque delegation prompt utilise six sections : TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.

package/README.ja.md

@@ -0,0 +1,166 @@
+# Pota Harness
+
+Pota Harness は Codex、Claude Code、Antigravity のためのトークン効率の高いマルチエージェント harness plugin です。
+
+[English](README.md)
+
+Pota の基本方針は、hooks、永続状態、明示的な planning、focused delegation、stop-time guards といった有用な agent harness の動作を残すことです。Pota は反復的な TDD verification loop を既定にしません。代わりに作業を小さな module task に分け、2 つの verification gate で証明します。
+
+1. Module acceptance verification: 変更された module contract を証明します。
+2. Surface integration verification: CLI、HTTP、browser、file artifacts など実際の surface を通して動作を証明します。
+
+task が外部状態を変更する前に、Pota は最も近い dry-run または check mode を記録して実行します。verification は制限されます。既定では各 task は 2 回の verification pass を持ち、その後は反復 loop を続けず blocker を記録するか task を分割します。
+
+Pota は tool readiness も作業の一部として扱います。LSP、typecheck、lint、dry-run、verification tools を repository stack に照らして確認します。installation は明示的な承認と固定された対応 installer がある場合だけ実行し、それ以外は blocker を報告します。
+
+## Complexity Triage
+
+すべての implementation task は、agent、plugin、delegated workflow guidance を適用する前に complexity triage を通ります。triage は user に質問せず、repository exploration、想定される変更範囲、risk signals から決定します。
+
+- Light Path: 既存 architecture layer 内の狭い変更です。既定値であり、直接実装するか 1 つの bounded `worker` を使い、その後 verification gate を維持します。
+- Heavy Path: new directory/module/layer、new domain model/service/abstraction、security/session/auth、external API/message queue/payment、DB schema/migration、concurrency/transaction/cache changes、cross-domain refactor、または extra-care request です。
+
+選択した path と理由は plan artifact がある場合に `docs/plan/<topic>.md` に記録します。Light Path でも 2 つの verification gate は維持されます。
+
+## Tool Readiness
+
+`pota toolcheck` は現在の repository から JavaScript、TypeScript、Python、PHP、Java、Kotlin、Swift、Go、Rust stacks を検出し、対応する LSP と verification tools を確認します。
+
+```sh
+pota toolcheck --root .
+pota toolcheck --install --yes --root .
+```
+
+- `toolcheck` は detected stacks と missing tools を報告します。
+- `toolcheck --install` は明示的な承認と `--yes` を必要とし、非対応 installer は実行せず canonical `installer-unavailable` を返します。
+- Pota plans は detected stack、required tools、install commands、blockers を記録します。
+- LSP server がないことだけでは precise codebase exploration を省略できません。installation または同等の symbol-aware fallback を先に試す必要があります。
+
+## Dry-Run And Loop Policy
+
+- Migrations と database changes は write/apply commands の前に `--pretend`、dry-run、schema diff、rollback feasibility checks、または最も近い repository-native equivalent を使います。
+- Package、release、infrastructure、deployment、code generation、formatting work は可能な場合、状態変更の前に check、plan、diff、validate、dry-run modes を使います。
+- dry-run がない場合、plan はその事実を記録し、最小で reversible な command または test artifact を選びます。
+- verification gate が失敗した場合、Pota は一度診断し、task を縮小または分割して両方の gate を再実行します。
+- 同じ task で 2 回の verification pass が失敗した場合、反復 loop を続けず `docs/plan/<topic>.md` に blocker を記録します。
+
+## Model Guidance
+
+Pota は Claude-family と Codex-family models にのみ model-specific adjustment を適用します。
+
+- Claude-family: long context、policy interpretation、plan/evidence review に有用です。
+- Codex-family: small implementation tasks、explicit file edits、command-based verification、bounded `worker` tasks に有用です。
+
+詳細はインストール済みプラグインの `pota://docs/model-guidance/README.md`、`pota://docs/model-guidance/claude.md`、`pota://docs/model-guidance/codex.md` にあります。
+
+## Repository Artifacts
+
+harness は対象 repository root に次の files を作成して維持します。
+
+- `MEMORY.md`: persistent domain knowledge の短い index。`## Domain Knowledge` の下に note ごとに 1 行(`- [<name>](docs/memory/<name>.md): <summary>`)を置き、repository の `## Policy` も含みます。
+- `docs/memory/*.md`: domain ごとの詳細 knowledge。各 note は H1 の下に 1 行の `Summary:`(120 文字以内)を置き、index と hook がそれを表示します。
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/state.json`: 中断復旧と scoped stop gate に使う user-home の project/worktree 別 active goal/task/evidence 状態。project working tree は runtime state を所有しません。
+- `PLAN.md`: work plans の短い index。`## Active Plans` と `## Completed Plans` の下に plan ごとに 200 文字以内の 1 行を置きます。planning rules は `PLAN.md` ではなく `pota-plan` skill にあります。
+- `docs/plan/*.md`: detailed execution plans。
+- `docs/plan/ARCHIVE.md`: `pota plan index --archive` が `PLAN.md` から移した古い completed entries を新しい順に保持し、legacy `## Planning Rules` section の本文を `## Legacy Planning Rules` の下に置きます。最初の `## ` 見出しより前の list 行は index 済みとして扱われます。
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/history.jsonl`: completed/cancelled goal ごとの要約 record(worktree ごとに最新 200 件)。`goal stats --history` が読みます。
+
+`## Completed Plans` は新しい順に保ちます。`pota plan index --archive` は先頭 20 件を残し、残りを何も削除せずに `docs/plan/ARCHIVE.md` へ移すため、古い順に並べた list では最新の plans が archive されます。先に `--dry-run` で確認してください。既存の `MEMORY.md`/`PLAN.md` は migration なしで動作します。`init` は既存 file を書き換えず、`check` は古い形式を warning としてのみ報告します。
+
+`SessionStart` で hook は、どの memory notes があるか(name と `Summary:`、list が長い場合は name だけの 1 行)を agent に知らせ、active goal がなければ plan index の 1 行(plan 数、active plans、最新の completed plans、存在すれば `docs/plan/ARCHIVE.md`)を追加します。active・paused・blocked goal や別 session が所有する goal がある場合は memory list だけを載せ、別 session の capsule に plan 名は出しません。goal がないときの `UserPromptSubmit` は note 数を伝える 1 文だけを追加します。hook は index files と directory listing だけを読み、note 本文は読まず、何も書き込みません。notes と plans がない repository の hook 出力は以前と同じです。
+
+`pota-work` は `goal finish` の前に goal ごとに 1 回、memory promotion の決定を plan の Evidence に記録します。再利用できる repository knowledge ができた場合は `Memory promotion: docs/memory/<domain>.md`、そうでなければ `Memory promotion: none: <reason>` です。決定の記録は必須で、note の作成は任意です。goal が完了したのに plan file に記入済みの `Memory promotion:` 行がない場合、`goal finish` と `goal complete` は stderr に 1 行の reminder を出しますが、exit code と stdout は変わりません。
+
+root files は短く保ち、詳細は `docs/` に移すことで、agents が必要な context だけを読めるようにします。
+
+トークン効率のため、実装前に要件・不変条件・境界・失敗モードを test contract にします。`goal verify -- <argv>` の tool exit code を判定基準にし、成功は短く、失敗時だけ context を広げます。package lifecycle を確認し、通常の `npm pack --dry-run` を既定にします。content-producing または不明な script では `--ignore-scripts` を使わず、script がないか content-neutral と証明され、full-check evidence が新鮮な場合だけ使用します。
+
+## Commands
+
+published package は `bunx` または global install された `pota` command で実行できます。
+
+```sh
+bunx @comento/pota-harness@latest install
+bunx @comento/pota-harness@latest upgrade
+bunx @comento/pota-harness@latest doctor
+bunx @comento/pota-harness@latest uninstall
+bunx @comento/pota-harness@latest toolcheck
+```
+
+global installation 後は short commands も使えます。
+
+```sh
+bun add -g @comento/pota-harness
+pota install
+pota upgrade
+pota doctor
+pota uninstall
+pota toolcheck
+pota auto-upgrade status
+```
+
+- `pota install [--hosts all|codex,claude,antigravity]`: custom marketplace source、versioned runtime、Pota-owned config sections、現行 host mirrors を transaction で install します。 canonical runtime は `~/.pota/install/` に置き、上記は選択した host の分だけ install します。`--hosts` がない場合、terminal での最初の install は host を尋ね、非対話実行と CI はすべての host を install します。
+- `pota upgrade [--hosts all|codex,claude,antigravity]`: staged validation 後、ownership manifest の未変更 entry だけを置換し、失敗時は rollback します。 `--hosts` で変えない限り記録された hosts を維持し、別 version を持つ Claude Code plugin cache を更新します。 install 済み version がこの CLI より新しい場合、`install` と `upgrade` は何も変えずに拒否し、それでもこの CLI の version を入れるには `--allow-downgrade` を付けます。
+- `pota doctor`: ownership digests、effective Codex features、実際の plugin status、runtime locators を修復せず診断します。 最初の行に `Hosts: <ids>` を出力し、選択された host だけを検査します(`Claude plugin cache version` を含む)。
+- `pota uninstall`: まず config 以外のすべての ownership manifest entry を installed digest と照合し、変更または削除された managed artifact が一つでもあれば何も変えずに uninstall 全体を拒否します。そうでなければ managed entry と retained runtimes を削除・復元し、空の managed scaffold を整理し、unmanaged target とその親ディレクトリは preserve し、commit 前の失敗は rollback します。 `~/.pota/update/` も削除し、`~/.pota/config.json` と `~/.pota/projects/` は残します。legacy layout の install は移行せずにその場で削除します。
+- `pota auto-upgrade status|on|off|run`: `status` は設定、installed version、最終確認、保留中の notice を JSON で出力します。`on`/`off` は `~/.pota/config.json` の `autoUpgrade` を書き換えて同じ report を出力し、`run` は 24 時間周期と backoff を無視して今すぐ npm を確認します。exit 0 は成功、1 は実行エラーまたは失敗した run、2 は usage error です。
+- `pota toolcheck`: repository stacks と required tools を確認し、承認済み supported installer だけを実行します。それ以外は `installer-unavailable` です。
+- `pota cleanup --root <repo>`: 既定では legacy project-local `.pota` residue を read-only で報告します。`--yes` は valid active state を user-home store に移行・調整し、known state/lock/tool residue のみ削除し、unknown files を保持して空の場合だけ directory を削除します。
+- `pota memory check|index [--root <repo>]`: `check` は `MEMORY.md` と `docs/memory/*.md` を照合して JSON report を 1 つ出力します。unindexed notes、dead links、duplicates、stale summaries、summary 内の制御文字、unsafe paths があれば exit 1 で、warnings は `--strict` のときだけ失敗します。entries は `## Domain Knowledge` の下の list 行です(その section がない古い file ではすべての list 行)。他の section の note link は言及であり、`index` は書き換えません。`index` は抜けている notes を追加し、`Summary:` が変わると link の後ろの summary 部分だけを置き換えます(link が複数ある行はそのまま)。その section 内で完全に一致する Pota placeholder 行だけを削除し、entries や dead links は削除せず、それ以外は byte 単位で保持します。`--dry-run` で事前確認できます。挿入位置が閉じていない code fence の中なら、`index` は何も書かず `unclosed-fence` で exit 1 になります。usage error は exit 2 で、subcommand なしの `pota memory` は従来の案内を出力します。
+- `pota plan check|index [--archive] [--root <repo>]`: `PLAN.md` と `docs/plan/*.md` に同じ check と index を適用し、entries は見出しが `Plans` で終わる `## ` section(`## Superseded Plans` など)の list 行です。`index` は checkbox がすべて checked の plan を `## Completed Plans` の先頭に、それ以外を `## Active Plans` に追加します。行を移動するのは `--archive` だけで、最新 20 件を超える completed entries(インデントされた段落を含む)と legacy `## Planning Rules` section の本文を `docs/plan/ARCHIVE.md` へ移します。`check` は `## Completed Plans` が 20 件を超えるか legacy `## Planning Rules` section が残っていると warning を出します。
+- `pota goal ...`: repository goal を管理します(`pota goal --help`)。`goal stats --history [--limit N]` は repository のすべての worktree で終了した goals を集計します。completed/cancelled 数、所要時間の median と p90、task と receipt の median、rerun rate、memory promotion の決定数、completed goal が 4 件以上のときの older/newer `trend`、最近の goals です。history がなければ `{"schemaVersion":1,"scope":"repository","goals":0}` を出力します。`completionCriteria`(`goal start --criteria`)は `advisory` です。Pota は記録するだけで強制せず、完了は required evidence だけで判定されます。
+- `pota-memory`: domain knowledge を探索し `MEMORY.md` を更新します。
+- `pota-plan`: `docs/plan/` に decision-complete plan を作成します。
+- `pota-work`: 現在の `PLAN.md` の次の module task を実行し、2 つの verification gates を取得します。
+- `pota-review`: plan、memory、evidence に照らして completed tasks を review します。
+
+custom marketplace lifecycle は source と versioned runtime を分離します。各 commit 前に staged validation を行い、ownership manifest が全 managed digest を結び、失敗時は reverse-order rollback します。modified または unmanaged artifacts は preserve して conflict として報告します。Pota-owned TOML sections だけを変更し、public feature/agent settings は強制しません。
+
+Clean uninstall は、すべての managed scaffold directory が空の場合に限り `~/.pota/install/` と Codex cache root `$CODEX_HOME/plugins/cache/pota` を削除し、unmanaged content は保持します。source repository と repository `MEMORY.md`/`PLAN.md`、user-home Pota goal state、global `@comento/pota-harness` package、package-manager cache、現在の ownership manifest 外の legacy backup/settings は自動削除しません。
+
+Codex は `skills/` と `commands/` を使います。Claude Code は `.claude/` 配下の mirrored commands と agent definitions を使います。Antigravity は `.agents/workflows` と global skills mirrors を使います。
+
+## Install Layout And Auto-Upgrade
+
+Pota は install を `POTA_HOME`(既定 `~/.pota`)の下に置きます。host の paths は引き続き `CODEX_HOME`、`CLAUDE_HOME`、`ANTIGRAVITY_HOME`、`ANTIGRAVITY_CLI_HOME`、`CODEX_CONFIG_PATH` で個別に設定します。
+
+```text
+~/.pota/
+  install/                  lifecycle が管理する files
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      すべての runtime locator と Claude Code hooks が使う canonical runtime
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               user settings ("autoUpgrade")
+  update/                   auto-upgrade state
+$CODEX_HOME/plugins/cache/pota/pota/<version>/   Codex plugin cache copy (Codex を選択した場合のみ)
+```
+
+- Hosts: `--hosts` は `install` と `upgrade` だけが受け付け、値は `all` または `codex`、`claude`、`antigravity` のカンマ区切りです。選択は ownership manifest に記録され、`upgrade`、`doctor`、`uninstall` がそれに従います。変更は `pota upgrade --hosts <list>` で、外す host の managed file が変更されていれば拒否します。対話 prompt(すべて(既定)、Claude Code のみ、Codex のみ、Antigravity のみ、カンマ区切り)は、まだ何も install されていないときだけ表示されます。
+- 猶予: version が変わる upgrade は、直前の canonical runtime と Codex cache copy を 3 日間(種類ごとに最大 3 個)残し、upgrade 前に始まった session が動き続けるようにします。期限切れは次の install/upgrade が削除し、uninstall はすべて削除します。新しい version 以上の Codex cache copy は残しません(Codex は cache の中で最も高い version を読み込むため)。
+- Claude Code plugin cache: 別 version が残っていれば `pota upgrade` が `claude plugin marketplace update pota` と `claude plugin update pota@pota --scope user` で更新します。失敗した場合は upgrade 済みの install を残し、手動で完了する command を出力して exit 1 になります。
+- Auto-upgrade: 既定で有効です。`SessionStart` が 24 時間に 1 回まで(install・upgrade 直後の 24 時間は除く)detached process を起動し、npm の最新 `@comento/pota-harness` をその version 固定で `--ignore-scripts` 付きで `~/.pota/update/stage/` に install・検証してから、その package の `pota-lifecycle.mjs upgrade --auto` を実行します。major を含むすべての新しい version を適用し、downgrade はしません。次の `SessionStart` が結果(`updated`、`failed`、`manual`)を 1 行で 1 回だけ知らせます。git checkout からの install(`origin: "checkout"`)と source checkout からの実行では動作しません。
+- 無効化: `pota auto-upgrade off`、`POTA_AUTO_UPGRADE=0`(`false`、`off`、`no` も可)、または `~/.pota/config.json` の `"autoUpgrade": false`。読めない `config.json` も無効として扱います。状態と最後の実行 log は `~/.pota/update/` にあります。
+
+## Antigravity Compatibility
+
+Antigravity は `/workflow-name` で呼び出される `SKILL.md` based Agent Skills and Workflows をサポートします。Pota はこの surface に次の paths を install します。
+
+- Antigravity IDE: `~/.gemini/config/skills/pota-*/SKILL.md`。
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/pota-*.md` のフラットな skill files。
+
+Codex-only hooks は Antigravity へ port されません。代わりに同じ planning、memory、complexity triage、two-gate verification procedures が Skills と Workflows を通して実行されます。paths を上書きするには `ANTIGRAVITY_HOME` または `ANTIGRAVITY_CLI_HOME` を設定してください。
+
+## Locale Policy
+
+Pota の reusable instructions は global use のため英語で書かれています。user-visible output と生成または更新される documentation、plans、memory artifacts は、user が別の language を指定しない限り configured OS locale に従います。これには `MEMORY.md`、`PLAN.md`、`docs/memory`、`docs/plan` の内容が含まれます。CLI は `en`、`ko`、`ja`、`zh`、`es`、`fr`、`de`、`pt` の common messages を localize し、unsupported locales は English に fallback します。Codex hook `statusMessage` text は static English のまま、hook command output は English または Korean です。
+
+## Delegation
+
+- `explorer`: 利用可能な場合、read-only codebase discovery、impact analysis、pattern search、read-only verification を処理します。
+- `worker`: 明確な file ownership を持つ bounded implementation または verification task を処理します。
+- Main session: 次の step が結果に即座に依存する urgent blocking work を local で処理します。
+
+すべての delegation prompt は TASK、EXPECTED OUTCOME、REQUIRED TOOLS、MUST DO、MUST NOT DO、CONTEXT の 6 sections を使います。