@comento/pota-harness 0.0.0-stage → 1.0.0

package/README.pt.md

@@ -0,0 +1,166 @@
+# Pota Harness
+
+Pota Harness e um plugin de harness multiagente eficiente em tokens para Codex, Claude Code e Antigravity.
+
+[English](README.md)
+
+A ideia central e manter comportamentos uteis de agent harness: hooks, estado persistente, planejamento explicito, delegacao focada e guardas no momento de parada. Pota nao torna loops repetidos de verificacao TDD o padrao. Em vez disso, divide o trabalho em pequenos module tasks e prova cada task com dois verification gates.
+
+1. Module acceptance verification: prova o contrato do modulo alterado.
+2. Surface integration verification: prova o comportamento por uma superficie real, como CLI, HTTP, navegador ou artefatos de arquivo.
+
+Antes que um task altere estado externo, Pota registra e executa o dry-run ou check mode mais proximo disponivel. A verificacao e limitada: cada task recebe duas verification passes por padrao; depois, o agente registra um blocker ou divide o task em vez de continuar um loop aberto.
+
+Pota tambem trata tool readiness como parte do trabalho. LSP, typecheck, lint, dry-run e verification tools sao verificados contra o stack do repositorio. A instalacao ocorre apenas com aprovacao explicita e um installer suportado e fixado; caso contrario, um blocker e informado.
+
+## Complexity Triage
+
+Cada implementation task passa primeiro por complexity triage, antes de aplicar agent, plugin ou delegated workflow guidance. O triage e decidido a partir da exploracao do repositorio, do escopo esperado da mudanca e de sinais de risco, sem perguntar ao usuario por fatos descobriveis.
+
+- Light Path: mudancas estreitas dentro de existing architecture layers. E o padrao. Implemente diretamente ou use um `worker` limitado, depois mantenha o 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.
+
+O path escolhido e sua justificativa sao registrados em `docs/plan/<topic>.md` quando houver um plan artifact. Mesmo no Light Path, os dois verification gates permanecem.
+
+## Tool Readiness
+
+`pota toolcheck` inspeciona o repositorio atual para stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go e Rust, depois verifica os LSP e verification tools correspondentes.
+
+```sh
+pota toolcheck --root .
+pota toolcheck --install --yes --root .
+```
+
+- `toolcheck` informa detected stacks e missing tools.
+- `toolcheck --install` exige aprovacao explicita e `--yes`; um installer sem suporte retorna o resultado canonico `installer-unavailable` sem ser executado.
+- Os planos Pota registram detected stack, required tools, install commands e blockers.
+- Um LSP server ausente nao e motivo valido para pular precise codebase exploration antes de tentar installation ou um fallback symbol-aware equivalente.
+
+## Dry-Run And Loop Policy
+
+- Migrations e database changes usam `--pretend`, dry-run, schema diff, rollback feasibility checks ou o equivalente repository-native mais proximo antes de write/apply commands.
+- Package, release, infrastructure, deployment, code generation e formatting work usam check, plan, diff, validate ou dry-run modes antes de alterar estado quando disponiveis.
+- Se nao houver dry-run, o plan registra esse fato e escolhe o menor command reversivel ou test artifact disponivel.
+- Se um verification gate falhar, Pota diagnostica uma vez, reduz ou divide o task e executa novamente os dois gates.
+- Depois de duas verification passes falhas para o mesmo task, Pota registra o blocker em `docs/plan/<topic>.md` em vez de continuar um loop repetido.
+
+## Model Guidance
+
+Pota aplica model-specific adjustment apenas a modelos Claude-family e Codex-family.
+
+- Claude-family: util para long context, policy interpretation e plan/evidence review.
+- Codex-family: util para small implementation tasks, explicit file edits, command-based verification e bounded `worker` tasks.
+
+A orientação detalhada fica no plugin instalado em `pota://docs/model-guidance/README.md`, `pota://docs/model-guidance/claude.md` e `pota://docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+O harness cria e mantem estes arquivos na raiz do repositorio alvo.
+
+- `MEMORY.md`: indice curto de persistent domain knowledge: uma linha por nota em `## Domain Knowledge` (`- [<name>](docs/memory/<name>.md): <summary>`) mais a `## Policy` do repositorio.
+- `docs/memory/*.md`: conhecimento detalhado por dominio. Cada nota comeca com uma linha `Summary:` (no maximo 120 caracteres) que o indice e o hook exibem.
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/state.json`: active goal/task/evidence state no user-home, isolado por projeto e worktree, para retomada e scoped stop gates. O working tree nao possui runtime state.
+- `PLAN.md`: indice curto de planos de trabalho: uma linha de ate 200 caracteres por plano em `## Active Plans` e `## Completed Plans`. As regras de planejamento ficam no skill `pota-plan`, nao em `PLAN.md`.
+- `docs/plan/*.md`: detailed execution plans.
+- `docs/plan/ARCHIVE.md`: entradas concluidas antigas movidas de `PLAN.md` por `pota plan index --archive`, da mais nova para a mais antiga, mais o corpo de uma secao legacy `## Planning Rules` sob `## Legacy Planning Rules`. Linhas de lista antes do seu primeiro titulo `## ` continuam contando como indexadas.
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/history.jsonl`: um registro resumido por goal concluido ou cancelado (os 200 mais recentes por worktree) para `goal stats --history`.
+
+Mantenha `## Completed Plans` da mais nova para a mais antiga. `pota plan index --archive` mantem as primeiras 20 entradas e move o restante para `docs/plan/ARCHIVE.md` sem apagar nada; uma lista mantida da mais antiga para a mais nova arquivaria os planos mais recentes. Confira antes com `--dry-run`. `MEMORY.md`/`PLAN.md` existentes funcionam sem migracao: `init` nunca os reescreve e `check` apenas avisa sobre o formato antigo com warnings.
+
+No `SessionStart`, o hook informa ao agente quais notas de memoria existem (nome e `Summary:`, ou uma linha so com nomes quando a lista e longa) e, sem goal ativo, adiciona uma linha sobre o indice de planos: quantidade de planos, planos ativos, os ultimos planos concluidos e `docs/plan/ARCHIVE.md` quando existe. Com um goal active, paused, blocked ou de outra sessao, so a lista de memoria e adicionada, e a capsula de outra sessao nunca mostra nomes de planos. Um `UserPromptSubmit` sem goal adiciona uma frase com a quantidade de notas. O hook le apenas os arquivos de indice e listagens de diretorio, nunca o corpo das notas, e nao escreve nada; um repositorio sem notas nem planos recebe a mesma saida de antes.
+
+Antes de `goal finish`, `pota-work` registra uma decisao de memory promotion por goal na Evidence do plano: `Memory promotion: docs/memory/<domain>.md` quando o goal gerou conhecimento reutilizavel do repositorio, ou `Memory promotion: none: <reason>` caso contrario. A decisao e obrigatoria; escrever uma nota e opcional. Quando um goal e concluido e o arquivo do plano nao tem uma linha `Memory promotion:` preenchida, `goal finish` e `goal complete` imprimem um lembrete de uma linha no stderr sem alterar o exit code nem o stdout.
+
+Arquivos raiz ficam curtos e os detalhes vao para `docs/`, para que agentes leiam apenas o contexto necessario.
+
+Para economizar tokens, crie primeiro um test contract com requisitos, invariantes, limites e modos de falha. Use o tool exit code de `goal verify -- <argv>` como autoridade, resuma o sucesso e expanda o contexto apenas em falhas. Inspecione o package lifecycle e execute normalmente `npm pack --dry-run`. Scripts content-producing ou desconhecidos nunca devem usar `--ignore-scripts`; use-o apenas quando os scripts estiverem ausentes ou comprovadamente content-neutral e a evidencia do full check continuar atual.
+
+## Commands
+
+O pacote publicado pode ser executado com `bunx` ou 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
+```
+
+Apos a instalacao global, comandos curtos tambem ficam disponiveis.
+
+```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 transacional custom marketplace source, versioned runtime, secoes config do Pota e mirrors atuais. O canonical runtime fica em `~/.pota/install/` e o resto e instalado apenas para os hosts escolhidos. Sem `--hosts`, a primeira instalacao em um terminal pergunta os hosts; execucoes nao interativas e CI instalam todos.
+- `pota upgrade [--hosts all|codex,claude,antigravity]`: substitui apenas entradas intactas do ownership manifest apos staged validation e usa rollback em falhas. Mantem os hosts registrados, a menos que `--hosts` os altere, e atualiza um Claude Code plugin cache que ainda tenha outra versao. Se a versao instalada for mais nova que esta CLI, `install` e `upgrade` recusam sem mudar nada; `--allow-downgrade` instala mesmo assim a versao desta CLI.
+- `pota doctor`: valida ownership digests, features efetivos do Codex, status real do plugin e runtime locators sem reparar. Imprime primeiro `Hosts: <ids>` e verifica apenas os hosts escolhidos (incluindo `Claude plugin cache version`).
+- `pota uninstall`: primeiro compara cada entrada nao config do ownership manifest com seu installed digest e recusa todo o uninstall, sem mudar nada, se algum managed artifact foi modificado ou removido. Caso contrario, remove ou restaura as entradas gerenciadas e os retained runtimes, limpa os managed scaffolds vazios, preserva alvos unmanaged e seus diretorios pai e aplica rollback a falhas antes do commit. Tambem remove `~/.pota/update/`, e mantem `~/.pota/config.json` e `~/.pota/projects/`. Uma instalacao com layout legacy e removida no lugar, sem migracao.
+- `pota auto-upgrade status|on|off|run`: `status` imprime em JSON a configuracao, a versao instalada, a ultima verificacao e o aviso pendente; `on`/`off` gravam `autoUpgrade` em `~/.pota/config.json` e imprimem o mesmo relatorio; `run` consulta o npm agora, sem esperar o intervalo de 24 horas nem o backoff. Exit 0 e sucesso, 1 erro de execucao ou execucao com falha, 2 erro de uso.
+- `pota toolcheck`: detecta repository stacks e verifica required tools; apenas um installer suportado e aprovado e executado, caso contrario `installer-unavailable`.
+- `pota cleanup --root <repo>`: por padrao relata em modo read-only residuos legacy `.pota` locais do projeto. `--yes` migra/reconcilia valid active state para o user-home store, remove apenas residuos conhecidos de state/lock/tool, preserva arquivos desconhecidos e remove o diretorio somente quando vazio.
+- `pota memory check|index [--root <repo>]`: `check` compara `MEMORY.md` com `docs/memory/*.md` e imprime um relatorio JSON; sai com 1 para notas nao indexadas, dead links, duplicatas, resumos desatualizados, caracteres de controle em resumos ou caminhos inseguros, e warnings so falham com `--strict`. Entradas sao linhas de lista sob `## Domain Knowledge` (ou todas as linhas de lista num arquivo antigo sem essa secao); um link de nota em outra secao e uma mencao que `index` nunca reescreve. `index` adiciona notas ausentes e, quando o `Summary:` muda, troca so o resumo apos o link (uma linha com varios links fica como esta); remove apenas linhas placeholder do Pota que coincidem exatamente nessa secao, nunca apaga entradas nem dead links e preserva o restante byte a byte. `--dry-run` mostra uma previa. Se o ponto de insercao estiver dentro de um bloco de codigo nao fechado, `index` nao escreve nada e sai com 1 com `unclosed-fence`. Erros de uso saem com 2; `pota memory` sem subcomando continua imprimindo a orientacao.
+- `pota plan check|index [--archive] [--root <repo>]`: o mesmo para `PLAN.md` e `docs/plan/*.md`, cujas entradas sao linhas de lista sob titulos `## ` que terminam em `Plans` (como `## Superseded Plans`). `index` coloca um plano com todas as caixas marcadas no topo de `## Completed Plans` e qualquer outro em `## Active Plans`; so `--archive` move linhas para `docs/plan/ARCHIVE.md`: entradas concluidas alem das 20 mais novas, com seus paragrafos recuados, e o corpo de uma secao legacy `## Planning Rules`. `check` avisa quando `## Completed Plans` passa de 20 entradas ou resta uma secao legacy `## Planning Rules`.
+- `pota goal ...`: gerencia o goal do repositorio (`pota goal --help`). `goal stats --history [--limit N]` agrega os goals encerrados do repositorio em todos os worktrees: contagens completed/cancelled, mediana e p90 de duracao, medianas de tasks e receipts, taxa de reruns, decisoes de memory promotion, um `trend` older/newer a partir de 4 goals concluidos e os goals recentes; sem historico imprime `{"schemaVersion":1,"scope":"repository","goals":0}`. `completionCriteria` (`goal start --criteria`) e `advisory`: o Pota registra mas nao o impoe, e a conclusao depende apenas da evidencia exigida.
+- `pota-memory`: explora domain knowledge e atualiza `MEMORY.md`.
+- `pota-plan`: cria um decision-complete plan em `docs/plan/`.
+- `pota-work`: executa o proximo module task no `PLAN.md` atual com dois verification gates.
+- `pota-review`: revisa completed tasks contra plan, memory e evidence.
+
+O custom marketplace lifecycle separa source e versioned runtime. Staged validation precede cada commit, o ownership manifest vincula todos os managed digests e uma falha aciona reverse-order rollback. Artifacts modified ou unmanaged sao preserved e relatados como conflict. O Pota altera apenas suas TOML sections e nao forca feature/agent settings publicos.
+
+Clean uninstall remove `~/.pota/install/` e o Codex cache root `$CODEX_HOME/plugins/cache/pota` somente quando todos os managed scaffold directories estao vazios; qualquer conteudo unmanaged e preservado. O source repository, repository `MEMORY.md`/`PLAN.md` e user-home Pota goal state, o package global `@comento/pota-harness`, package-manager caches e legacy backups/settings fora do ownership manifest atual nao sao removidos automaticamente.
+
+Codex usa `skills/` e `commands/`. Claude Code usa comandos espelhados e agent definitions em `.claude/`. Antigravity usa `.agents/workflows` e global skills mirrors.
+
+## Install Layout And Auto-Upgrade
+
+O Pota guarda a instalacao em `POTA_HOME` (padrao `~/.pota`). Os caminhos de cada host continuam definidos separadamente por `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME` e `CODEX_CONFIG_PATH`.
+
+```text
+~/.pota/
+  install/                  arquivos gerenciados pelo lifecycle
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime usado por todos os runtime locators e pelos hooks do Claude Code
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               configuracoes do usuario ("autoUpgrade")
+  update/                   estado do auto-upgrade
+$CODEX_HOME/plugins/cache/pota/pota/<version>/   copia no Codex plugin cache (somente se Codex for escolhido)
+```
+
+- Hosts: apenas `install` e `upgrade` aceitam `--hosts`, com `all` ou uma lista separada por virgulas de `codex`, `claude` e `antigravity`. A selecao fica no ownership manifest e `upgrade`, `doctor` e `uninstall` a seguem. Ela muda com `pota upgrade --hosts <list>`; um arquivo gerenciado modificado de um host removido causa recusa. O prompt interativo (todos por padrao, apenas Claude Code, apenas Codex, apenas Antigravity ou uma lista) aparece somente quando nada esta instalado.
+- Retencao: um upgrade que muda a versao mantem o canonical runtime anterior e a copia do Codex cache por 3 dias (no maximo 3 de cada tipo) para que sessoes iniciadas antes continuem funcionando. O install ou upgrade seguinte remove os vencidos, e uninstall remove todos. Uma copia do Codex cache igual ou superior a nova versao nunca e mantida, porque o Codex carrega a versao mais alta do cache.
+- Claude Code plugin cache: se ainda tiver outra versao, `pota upgrade` o atualiza com `claude plugin marketplace update pota` e `claude plugin update pota@pota --scope user`. Se falhar, a instalacao atualizada e mantida, os comandos para concluir manualmente sao impressos e a saida e exit 1.
+- Auto-upgrade: ativado por padrao. No maximo uma vez a cada 24 horas (e nao nas 24 horas apos um install ou upgrade), `SessionStart` inicia um processo separado que le a versao mais recente de `@comento/pota-harness` no npm, instala essa versao exata com `--ignore-scripts` em `~/.pota/update/stage/`, verifica e executa o `pota-lifecycle.mjs upgrade --auto` dela. Todas as versoes novas sao aplicadas, inclusive major, e nunca ha downgrade. O `SessionStart` seguinte mostra o resultado (`updated`, `failed` ou `manual`) em uma linha, uma unica vez. Nao funciona para instalacoes a partir de um git checkout (`origin: "checkout"`) nem ao executar de um source checkout.
+- Desativar: `pota auto-upgrade off`, `POTA_AUTO_UPGRADE=0` (ou `false`, `off`, `no`) ou `"autoUpgrade": false` em `~/.pota/config.json`. Um `config.json` ilegivel tambem desativa. O estado e o log da ultima execucao ficam em `~/.pota/update/`.
+
+## Antigravity Compatibility
+
+Antigravity suporta Agent Skills e Workflows baseados em `SKILL.md` chamados como `/workflow-name`. Pota instala estes paths para essa superficie.
+
+- Antigravity IDE: `~/.gemini/config/skills/pota-*/SKILL.md`.
+- Antigravity CLI: arquivos skill planos em `~/.gemini/antigravity-cli/skills/pota-*.md`.
+
+Codex-only hooks nao sao portados para Antigravity. Em vez disso, os mesmos procedimentos de planning, memory, complexity triage e two-gate verification rodam por Skills e Workflows. Defina `ANTIGRAVITY_HOME` ou `ANTIGRAVITY_CLI_HOME` para sobrescrever paths.
+
+## Locale Policy
+
+As instrucoes reutilizaveis do Pota sao escritas em English para global use. User-visible output e documentation, plans e memory artifacts gerados ou atualizados devem seguir o OS locale configurado, a menos que o usuario peca explicitamente outro idioma. Isso inclui conteudo em `MEMORY.md`, `PLAN.md`, `docs/memory` e `docs/plan`. A CLI localiza mensagens comuns para `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` e `pt`, e volta para English em unsupported locales. O texto `statusMessage` dos Codex hooks permanece static English, enquanto hook command output e English ou Korean.
+
+## Delegation
+
+- `explorer`: lida com read-only codebase discovery, impact analysis, pattern searches e read-only verification quando disponivel.
+- `worker`: lida com bounded implementation ou verification tasks com file ownership claro.
+- Main session: mantem urgent blocking work local quando o proximo passo depende imediatamente do resultado.
+
+Todo delegation prompt usa seis sections: TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.

package/README.zh.md

@@ -0,0 +1,166 @@
+# Pota Harness
+
+Pota Harness 是面向 Codex、Claude Code 和 Antigravity 的高 token 效率 multi-agent harness plugin。
+
+[English](README.md)
+
+Pota 的核心思路是保留有用的 agent harness 行为：hooks、persistent state、explicit planning、focused delegation 和 stop-time guards。Pota 不把重复的 TDD verification loops 作为默认流程，而是把工作拆成小的 module tasks，并用两个 verification gates 证明每个 task。
+
+1. Module acceptance verification: 证明被修改的 module contract。
+2. Surface integration verification: 通过 CLI、HTTP、browser 或 file artifacts 等真实 surface 证明行为。
+
+在 task 修改外部状态之前，Pota 会记录并运行最接近的 dry-run 或 check mode。verification 是有边界的：默认每个 task 有两次 verification pass，然后 agent 会记录 blocker 或拆分 task，而不是继续开放式循环。
+
+Pota 也把 tool readiness 视为工作的一部分。它会根据 repository stack 检查 LSP、typecheck、lint、dry-run 和 verification tools。只有在获得明确批准且存在固定版本的受支持 installer 时才安装，否则报告 blocker。
+
+## Complexity Triage
+
+每个 implementation task 都先经过 complexity triage，然后才应用 agent、plugin 或 delegated workflow guidance。triage 根据 repository exploration、expected change scope 和 risk signals 判断，不向用户询问可发现的信息。
+
+- Light Path: existing architecture layers 内的窄范围修改。这是默认路径。可以直接实现，或使用一个 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，也保留两个 verification gates。
+
+## 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 会记录该事实，并选择最小且可逆的 command 或 test artifact。
+- 如果 verification gate 失败，Pota 会诊断一次，缩小或拆分 task，然后重新运行两个 gates。
+- 同一 task 两次 verification pass 失败后，Pota 会在 `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 创建并维护这些文件。
+
+- `MEMORY.md`: persistent domain knowledge 的短索引。在 `## Domain Knowledge` 下每个 note 一行(`- [<name>](docs/memory/<name>.md): <summary>`)，并包含 repository 的 `## Policy`。
+- `docs/memory/*.md`: 按 domain 记录的详细 knowledge。每个 note 在 H1 下有一行 `Summary:`(不超过 120 个字符)，索引和 hook 会显示它。
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/state.json`: user-home 中按 project/worktree 隔离的 active goal/task/evidence 状态，用于中断恢复和 scoped stop gate。project working tree 不拥有 runtime state。
+- `PLAN.md`: work plans 的短索引。在 `## Active Plans` 和 `## Completed Plans` 下每个 plan 一行，不超过 200 个字符。planning rules 位于 `pota-plan` skill，而不在 `PLAN.md` 中。
+- `docs/plan/*.md`: detailed execution plans。
+- `docs/plan/ARCHIVE.md`: 按从新到旧保存 `pota plan index --archive` 从 `PLAN.md` 移出的较旧 completed 条目，并把 legacy `## Planning Rules` section 的正文放在 `## Legacy Planning Rules` 下。第一个 `## ` 标题之前的列表行仍视为已索引。
+- `~/.pota/projects/<project-id>/worktrees/<worktree-id>/history.jsonl`: 每个 completed 或 cancelled goal 一条摘要记录(每个 worktree 保留最新 200 条)，供 `goal stats --history` 读取。
+
+`## Completed Plans` 保持从新到旧排列。`pota plan index --archive` 保留前 20 条，把其余条目移到 `docs/plan/ARCHIVE.md` 且不删除任何内容；如果列表按从旧到新排列，被归档的会是最新的 plans。请先用 `--dry-run` 预览。现有 `MEMORY.md`/`PLAN.md` 无需迁移即可使用：`init` 不会重写已有文件，`check` 只以 warning 报告旧格式。
+
+在 `SessionStart`，hook 会告诉 agent 有哪些 memory notes(name 和 `Summary:`，列表过长时改为只列 name 的一行)；没有 active goal 时，还会添加一行 plan 索引摘要(plan 数量、active plans、最近 completed plans，以及存在时的 `docs/plan/ARCHIVE.md`)。存在 active、paused、blocked 或其他 session 拥有的 goal 时，只附加 memory 列表，其他 session 的 capsule 绝不显示 plan 名称。没有 goal 时的 `UserPromptSubmit` 只增加一句 note 数量提示。hook 只读取索引文件和目录列表，不读取 note 正文，也不写入任何内容；没有 notes 和 plans 的 repository，hook 输出与以前相同。
+
+`pota-work` 在 `goal finish` 之前，每个 goal 在 plan 的 Evidence 中记录一次 memory promotion 决定：产生了可复用的 repository knowledge 时写 `Memory promotion: docs/memory/<domain>.md`，否则写 `Memory promotion: none: <reason>`。记录决定是必需的，编写 note 是可选的。goal 完成但 plan 文件中没有已填写的 `Memory promotion:` 行时，`goal finish` 和 `goal complete` 会在 stderr 输出一行提醒，exit code 和 stdout 不变。
+
+root files 保持简短，细节移到 `docs/` 下，让 agents 只读取当前任务需要的 context。
+
+为节省 token，先把需求、不变量、边界和失败模式写成 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
+
+发布后的 package 可以通过 `bunx` 或全局安装的 `pota` commands 执行。
+
+```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
+```
+
+全局安装后也可以使用短命令。
+
+```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。 canonical runtime 位于 `~/.pota/install/`，其余内容只为所选 host 安装。未提供 `--hosts` 时，在 terminal 中首次安装会询问 host，非交互运行和 CI 会安装所有 host。
+- `pota upgrade [--hosts all|codex,claude,antigravity]`: staged validation 后只替换 ownership manifest 中未修改的 entry，失败时 rollback。 除非用 `--hosts` 修改，否则沿用已记录的 hosts，并更新仍为其他版本的 Claude Code plugin cache。 已安装版本比当前 CLI 更新时，`install` 和 `upgrade` 不做任何更改并拒绝；如仍要安装当前 CLI 的版本，加 `--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，preserve unmanaged target 及其父目录，并 rollback commit 前的失败。 同时删除 `~/.pota/update/`，保留 `~/.pota/config.json` 和 `~/.pota/projects/`。legacy layout 的安装不经迁移直接原地删除。
+- `pota auto-upgrade status|on|off|run`: `status` 以 JSON 输出设置、已安装版本、上次检查时间和待显示的 notice；`on`/`off` 将 `autoUpgrade` 写入 `~/.pota/config.json` 并输出同样的报告；`run` 忽略 24 小时周期和 backoff，立即检查 npm。exit 0 表示成功，1 表示执行错误或运行失败，2 表示用法错误。
+- `pota toolcheck`: 检测 repository stacks 和 required tools；只执行已批准的 supported installer，否则返回 `installer-unavailable`。
+- `pota cleanup --root <repo>`: 默认只读报告 legacy project-local `.pota` residue。`--yes` 将 valid active state 迁移/协调到 user-home store，只删除 known state/lock/tool residue，保留 unknown files，并且仅在目录为空时清理目录。
+- `pota memory check|index [--root <repo>]`: `check` 对照 `MEMORY.md` 与 `docs/memory/*.md` 并输出一个 JSON 报告；存在 unindexed notes、dead links、duplicates、stale summaries、summary 中的控制字符或 unsafe paths 时 exit 1，warnings 仅在 `--strict` 下失败。条目是 `## Domain Knowledge` 下的列表行(没有该 section 的旧文件则为所有列表行)；其他 section 中的 note 链接只是提及，`index` 不会改写。`index` 添加缺失的 notes，`Summary:` 变化时只替换链接后的 summary 部分(含多个链接的行保持原样)；只删除该 section 内完全匹配的 Pota placeholder 行，不删除条目或 dead links，其余内容逐字节保留。可用 `--dry-run` 预览。插入位置位于未闭合的 code fence 内时，`index` 不写入任何内容，并以 `unclosed-fence` exit 1。用法错误 exit 2；不带子命令的 `pota memory` 仍输出原有指引。
+- `pota plan check|index [--archive] [--root <repo>]`: 对 `PLAN.md` 和 `docs/plan/*.md` 执行相同的检查和索引，条目是标题以 `Plans` 结尾的 `## ` section(如 `## Superseded Plans`)中的列表行。`index` 把 checkbox 全部勾选的 plan 放到 `## Completed Plans` 顶部，其他 plan 放到 `## Active Plans`；只有 `--archive` 会移动行：把超出最新 20 条的 completed 条目(连同缩进段落)和 legacy `## Planning Rules` section 的正文移到 `docs/plan/ARCHIVE.md`。`## Completed Plans` 超过 20 条或仍有 legacy `## Planning Rules` section 时，`check` 会给出 warning。
+- `pota goal ...`: 管理 repository goal(`pota goal --help`)。`goal stats --history [--limit N]` 汇总 repository 所有 worktree 中已结束的 goals：completed/cancelled 数量、耗时的中位数和 p90、task 与 receipt 的中位数、rerun rate、memory promotion 决定数、completed goal 达到 4 个后的 older/newer `trend`，以及最近的 goals；没有历史时输出 `{"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，并收集两个 verification gates。
+- `pota-review`: 根据 plan、memory 和 evidence review completed tasks。
+
+custom marketplace lifecycle 将 source 与 versioned runtime 分离。每次 commit 前执行 staged validation，ownership manifest 绑定全部 managed digests，失败时执行 reverse-order rollback。modified 或 unmanaged artifacts 会 preserve 并报告 conflict。Pota 只修改自身 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、全局 `@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 将安装内容放在 `POTA_HOME`(默认 `~/.pota`)下。各 host 的路径仍分别由 `CODEX_HOME`、`CLAUDE_HOME`、`ANTIGRAVITY_HOME`、`ANTIGRAVITY_CLI_HOME`、`CODEX_CONFIG_PATH` 决定。
+
+```text
+~/.pota/
+  install/                  lifecycle 管理的文件
+    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               用户设置 ("autoUpgrade")
+  update/                   auto-upgrade 状态
+$CODEX_HOME/plugins/cache/pota/pota/<version>/   Codex plugin cache copy (仅在选择 Codex 时)
+```
+
+- Hosts: 只有 `install` 和 `upgrade` 接受 `--hosts`，值为 `all` 或 `codex`、`claude`、`antigravity` 的逗号列表。选择会记录在 ownership manifest 中，`upgrade`、`doctor`、`uninstall` 都遵循它。用 `pota upgrade --hosts <list>` 修改；被移除 host 的 managed file 若已被修改则拒绝。交互式 prompt(全部(默认)、仅 Claude Code、仅 Codex、仅 Antigravity、逗号列表)只在尚未安装任何内容时出现。
+- 保留期: 改变版本的 upgrade 会把上一个 canonical runtime 和 Codex cache copy 保留 3 天(每类最多 3 个)，让 upgrade 前启动的 session 继续工作。过期的由下一次 install/upgrade 删除，uninstall 会全部删除。不低于新版本的 Codex cache copy 不会保留，因为 Codex 会加载 cache 中最高的版本。
+- Claude Code plugin cache: 若仍为其他版本，`pota upgrade` 会用 `claude plugin marketplace update pota` 和 `claude plugin update pota@pota --scope user` 更新。更新失败时保留已升级的安装，输出手动完成的命令并以 exit 1 结束。
+- Auto-upgrade: 默认开启。`SessionStart` 每 24 小时最多一次(install 或 upgrade 后 24 小时内不检查)启动一个 detached process：从 npm 读取最新的 `@comento/pota-harness` 版本，以该确切版本加 `--ignore-scripts` 安装到 `~/.pota/update/stage/` 并验证，然后运行该 package 的 `pota-lifecycle.mjs upgrade --auto`。包括 major 在内的所有新版本都会应用，从不降级。下一个 `SessionStart` 用一行只提示一次结果(`updated`、`failed`、`manual`)。从 git checkout 安装(`origin: "checkout"`)或从 source checkout 运行时不会执行。
+- 关闭: `pota auto-upgrade off`、`POTA_AUTO_UPGRADE=0`(也可用 `false`、`off`、`no`)，或在 `~/.pota/config.json` 中设置 `"autoUpgrade": false`。无法读取的 `config.json` 也视为关闭。状态和上次运行日志位于 `~/.pota/update/`。
+
+## Antigravity Compatibility
+
+Antigravity 支持通过 `/workflow-name` 调用的 `SKILL.md` based Agent Skills and Workflows。Pota 会为该 surface 安装这些 paths。
+
+- Antigravity IDE: `~/.gemini/config/skills/pota-*/SKILL.md`。
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/pota-*.md` 下的扁平 skill 文件。
+
+Codex-only hooks 不会移植到 Antigravity。相同的 planning、memory、complexity triage 和 two-gate verification procedures 会通过 Skills 和 Workflows 运行。设置 `ANTIGRAVITY_HOME` 或 `ANTIGRAVITY_CLI_HOME` 可以覆盖 paths。
+
+## Locale Policy
+
+Pota 的 reusable instructions 为了 global use 使用英文编写。除非用户明确要求其他语言，user-visible output 以及生成或更新的 documentation、plans、memory artifacts 应遵循 configured OS locale。这包括 `MEMORY.md`、`PLAN.md`、`docs/memory` 和 `docs/plan` 内容。CLI 会本地化 `en`、`ko`、`ja`、`zh`、`es`、`fr`、`de` 和 `pt` 的 common messages，不支持的 locales fallback 到 English。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: 当下一步立即依赖结果时，本地处理 urgent blocking work。
+
+每个 delegation prompt 都使用六个 sections: TASK、EXPECTED OUTCOME、REQUIRED TOOLS、MUST DO、MUST NOT DO、CONTEXT。

package/agents/explorer.md

@@ -0,0 +1,36 @@
+---
+name: explorer
+description: Read-only discovery agent for codebase questions, impact analysis, pattern search, and verification.
+tools: Read, Grep, Glob, Bash
+---
+
+# explorer
+
+Handle read-only discovery and verification tasks.
+
+Before an assigned task, read project-root `MEMORY.md` when present. If absent, continue without repository memory and do not invoke another memory service. Then open only the `docs/memory/*.md` notes whose `MEMORY.md` entries (one line and summary per note) match the task, plus any note paths the assignment names; do not read every note.
+
+At the start and after compaction, restart, or handoff, restore context in this order: root `MEMORY.md` → the phase skill named by the assignment → the active plan → current-task references → model guidance recorded by that plan. The assignment must identify the plan and current task whenever persisted work is active. If a required reference is missing, unreadable, or inconsistent with the assignment or goal state, report a blocker and do not perform the assigned discovery or delegate it.
+
+When subagent tools are available, you may recursively delegate bounded read-only 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.
+
+Use for:
+
+- Codebase questions.
+- Impact analysis.
+- Pattern searches.
+- Exact file and symbol discovery.
+- Read-only verification that can run independently.
+
+Do not edit files. Do not ask the user before exhausting repository evidence. Do not delegate vague or unbounded work. Preserve proper nouns exactly as written. Report only important paths, commands, and outputs accurately.
+
+Use this prompt format:
+
+```text
+TASK:
+EXPECTED OUTCOME:
+REQUIRED TOOLS:
+MUST DO:
+MUST NOT DO:
+CONTEXT:
+```

package/agents/worker.md

@@ -0,0 +1,45 @@
+---
+name: worker
+description: Focused execution agent for repository search, small edits, command checks, and QA artifacts.
+tools: Read, Grep, Glob, Bash, Write, Edit, MultiEdit
+---
+
+# worker
+
+Handle narrow, focused tasks.
+
+Before an assigned task, read project-root `MEMORY.md` when present. If absent, continue without repository memory and do not invoke another memory service. Then open only the `docs/memory/*.md` notes whose `MEMORY.md` entries (one line and summary per note) match the task, plus any note paths the assignment names; do not read every note.
+
+At the start and after compaction, restart, or handoff, restore context in this order: root `MEMORY.md` → the phase skill named by the assignment → the active plan → current-task references → model guidance recorded by that plan. The assignment must identify the plan and current task whenever persisted work is active. If a required reference is missing, unreadable, or inconsistent with the assignment or goal state, report a blocker and do not edit, delegate, or claim completion.
+
+When subagent tools are available, you 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.
+
+Use for:
+
+- Finding exact files and symbols.
+- Checking and bootstrapping LSP, typecheck, lint, dry-run, and verification tools.
+- Small mechanical edits.
+- Checking command availability.
+- Capturing evidence artifacts.
+- Cleanup verification.
+
+Do not make architecture decisions. Do not ask the user. Do not delegate vague or unbounded work. Do not treat a missing tool as unavailable until install or bootstrap has been attempted. Report only important paths, commands, and outputs accurately.
+
+Never edit, weaken, skip, or delete existing tests, fixtures, or verification commands to make a gate pass unless the plan records the contract change. Reproduce a reported defect before fixing it, and after the fix search for other implementations of the same rule or pattern; report them in the handoff.
+
+Before the first edit, inspect the assigned exact files, callers, and tests and report evidence for the plan's code checkpoint. If you discover a new Heavy Path signal before or during implementation, stop further edits and report it to the orchestrator so the plan artifact, repository goal task roadmap, native UI plan, review requirements, and stale evidence can be updated. Resume only after a new code checkpoint is recorded.
+
+Read the task's `Requested model` and `Effective model` too: model is chosen per task (fast `haiku`, balanced `sonnet`, stronger `opus`, strongest `fable`). Read the task's `Requested reasoning effort` and `Effective reasoning effort`: Requested is Pota's desired profile; Effective is what the dispatch response confirms. Every child task/worker you dispatch MUST receive the requested model and effort through the host-exposed task/subagent reasoning-effort option or host-native equivalent (Claude Code: Agent `model`/`effort`, never `fork`); recording without passing is a defect. Report Effective as the requested value when passed and not rejected, `not-applied: <reason>` when not passed, and `inherited` only when the host exposes no effort option. Describe capability only from the exposed interface or dispatch response, distinguish Pota non-integration from host non-support, and do not alter global/user config.
+
+Include the exact model ID from your own system prompt in the final report (`unreported` if not stated; never guess). A dispatch that changes a child's model or effort MUST be a new dispatch (Claude Code: a new Agent call), never `SendMessage`. Host task-list tools (`update_plan`, `create_goal`, `wrap_up`) are called by the main agent only; skip them and report in your final report.
+
+Use this prompt format:
+
+```text
+TASK:
+EXPECTED OUTCOME:
+REQUIRED TOOLS:
+MUST DO:
+MUST NOT DO:
+CONTEXT:
+```

package/commands/pota-doctor.md

@@ -0,0 +1,28 @@
+# pota-doctor
+
+Goal: diagnose Pota installation status.
+
+Run from the published or global package:
+
+```sh
+bunx @comento/pota-harness@latest doctor
+```
+
+The doctor validates the custom marketplace installation and ownership manifest without repairing it. Diagnostics are read-only; rollback is performed only by lifecycle transaction recovery.
+
+The first line is `Hosts: <ids>`; only the selected hosts are checked and only their host CLIs are run.
+
+Checks:
+
+- Source plugin manifest.
+- Canonical runtime under `~/.pota/install/runtime/<version>/`.
+- Codex cached installation.
+- Marketplace file.
+- Hook manifest link in the installed copy.
+- ownership manifest presence and managed destination digests.
+- `pota@pota` installed/enabled/version from the actual Codex CLI.
+- effective Codex plugin/hook/multi-agent feature state (reported, never forced).
+- hook trust state.
+- Claude Code commands and agents mirror files, plugin files, and `pota@pota` registered/enabled state and `Claude plugin cache version`.
+- Antigravity IDE/CLI skills and workflows mirror files.
+- Installed runtime locators and their referenced scripts, templates, and model guidance.

package/commands/pota-install.md

@@ -0,0 +1,29 @@
+# pota-install
+
+Goal: install Pota into Codex, Claude Code, and Antigravity.
+
+Run from the published or global package, not from the installed cache copy:
+
+```sh
+bunx @comento/pota-harness@latest install
+bunx @comento/pota-harness@latest install --hosts claude
+```
+
+The current custom marketplace lifecycle remains in use; this is not a migration to `codex plugin add`. Do not invoke lifecycle install/upgrade from an installed copy (`~/.pota/install/` or the Codex plugin cache) because that copy is the replacement target.
+
+Hosts: `--hosts all` or a comma list of `codex`, `claude`, `antigravity` (also `--hosts=<list>`). Without it, a first install at a terminal asks once (all hosts is the default); non-interactive runs and CI install every host. The selection is recorded in the ownership manifest and followed by upgrade, doctor, and uninstall.
+
+Actions:
+
+- Stage and validate the Pota installation, then transactionally commit the canonical runtime `~/.pota/install/runtime/<version>/` (`POTA_HOME` overrides `~/.pota`) and, for Codex, the marketplace source `~/.pota/install/codex/` and the versioned runtime cache `$CODEX_HOME/plugins/cache/pota/pota/<version>/`.
+- Add the `hooks/hooks.json` link to the installed manifests.
+- Register only Pota-owned marketplace, plugin, and hook trust sections in `~/.codex/config.toml`; do not rewrite public feature or agent settings.
+- Install `pota-*` commands and agents mirror files for Claude Code.
+- Generate the Claude Code plugin `pota@pota` (four skills plus hooks that call the canonical runtime) in the Pota-owned local marketplace `~/.pota/install/claude/`, then register it with `claude plugin marketplace add` and `claude plugin install pota@pota --scope user` after the files commit. Skip with a manual command when the `claude` CLI is missing, and never touch a different marketplace named `pota`.
+- Install `pota-*` skills and workflows mirror files for Antigravity IDE/CLI.
+- Write runtime locators so all mirrors resolve scripts, templates, and model guidance from the installed plugin root.
+- Install only the surfaces of the selected hosts; the canonical runtime is always installed.
+- Record every current managed destination and digest, the host selection, and the install origin in the ownership manifest `~/.pota/install/lifecycle.json`, and rollback committed phases in reverse order on failure.
+- Automatic upgrades are on by default for a package install; see `pota auto-upgrade status|on|off|run`.
+- Preserve and reject artifacts that are modified or not recorded in the ownership manifest.
+- Refuse, changing nothing, when the installed version is newer than this CLI; `--allow-downgrade` installs this CLI's version anyway.

package/commands/pota-memory.md

@@ -0,0 +1,17 @@
+# pota-memory
+
+Use the `pota-memory` skill.
+
+Prerequisite: resolve the installed Pota runtime from the plugin or skill locator. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror; run published/global `pota doctor`, then `pota upgrade` to recover it. Never repair through another mirror or look for Pota scripts in the target repository.
+
+Goal: create or update repository memory without asking the user for discoverable facts.
+
+Procedure:
+
+1. Run the installed plugin state initialization script with an explicit target `--root`.
+2. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before assigned discovery or update work.
+3. Explore repository facts with focused tools.
+4. Use `explorer` for read-only domain discovery and contradiction checks when available; use `worker` for exact references, command checks, and bounded evidence capture. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits.
+5. Write details to `docs/memory/<domain>.md` with a `Summary:` line under the H1 (one line, at most 120 characters: what the note answers and when to read it). 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.
+6. Keep `MEMORY.md` as a short index: one line per note under `## Domain Knowledge`; a note link in another section is a mention that `index` never rewrites. Run the installed Pota CLI with `memory index --root <repoRoot>` to add unlisted notes and refresh changed summaries (`--dry-run` previews; it never deletes entries and writes nothing when the insertion point is inside an unclosed code fence), then `memory check --root <repoRoot>` and fix the unindexed notes, dead links, duplicates, stale summaries, or control characters it reports.
+7. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/commands/pota-plan.md

@@ -0,0 +1,22 @@
+# pota-plan
+
+Use the `pota-plan` skill.
+
+Prerequisite: resolve the installed Pota runtime from the plugin or skill locator. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror; run published/global `pota doctor`, then `pota upgrade` to recover it. Never repair through another mirror or look for Pota scripts, templates, or model guidance in the target repository.
+
+Goal: show an initial plan and goal before triage can be interrupted, then leave a decision-complete implementation plan before non-trivial implementation.
+
+Paths: routine known-target Git/GitHub operations (status, fetch, checkout, branch, merge, push, PR management) stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design. Quick Path needs no `docs/plan` artifact and no goal when all hold: unambiguous requirements; about 3 files or fewer inside existing layers; no Heavy Path signal; no external-state mutation; one or two verification commands. Implement, run one focused check plus the project's normal check, and report; if any criterion fails, escalate to Light Path (plan + goal) before further edits. Otherwise use Light Path by default and Heavy Path only when a Heavy Path condition clearly applies.
+
+Complexity is staged: request checkpoint, planning checkpoint after exploration, and code checkpoint immediately before the first edit. Before editing, either route may change; after editing begins, only Light → Heavy promotion is allowed. Every change synchronizes the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile. Choose each task's model by its nature (fast, balanced, stronger, strongest) and pass it with effort through the host option; request Light `medium`, Heavy `high`, final verification/review `xhigh`.
+
+Procedure:
+
+1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before repository exploration, tool selection, work, or delegation.
+2. For non-trivial implementation or continuation of planned work, write an initial `docs/plan/<topic>.md` and `PLAN.md` entry with `triage-plan` as the first active task. The `PLAN.md` entry is one line of 200 characters or fewer under `## Active Plans`; the installed Pota CLI's `plan index --root <repoRoot>` adds missing entries and `plan check --root <repoRoot>` verifies them. This initial plan is decision-complete for triage and explicitly not implementation-ready.
+3. Before exploration, toolcheck, triage, or delegation, call Codex `update_plan` and then `create_goal` when available (main agent only; subagents skip), and start the repository Pota goal with the same roadmap. Copy the session-start hook's `Pota CLI:` prefix literally into each command; never store it in a shell variable. `--root` may be omitted when the cwd is inside the repository. Fold new work into an unfinished goal with `goal replan` instead of cancelling it; when a hook reports another session owns the goal you continue, run `goal claim --session <id>`.
+4. Reuse before exploring: pick related `docs/memory` notes from the `MEMORY.md` entries and at most 3 completed plans from `PLAN.md` (older ones in `docs/plan/ARCHIVE.md`) that changed the same modules or solved the same kind of problem; read only those plans' goal, design decisions, and evidence, and record the picks in the plan's `## Memory Inputs` with `Related completed plans:` (or `none related`). Read the picked notes and the installed model guidance, run `toolcheck --root <repoRoot>` (installation only with explicit approval), and explore before asking the user.
+5. Classify the whole work into executable tasks with `dependsOn`, `writeScope`, and handoff files, finalize triage, and update the same plan and `update_plan` roadmap to a decision-complete implementation plan: selected path, checked Heavy Path signals, tool readiness, file scope, dry-run/check, module acceptance, surface integration, stable IDs, and fail-closed evidence. Heavy Path adds an explicit automated test command and `Tests:` evidence line.
+6. Read the skill's reference files only when needed: `pota://skills/pota-plan/planning-rules.md` when finalizing, `pota://skills/pota-plan/delegation.md` before dispatching, `pota://skills/pota-plan/heavy-path.md` only on a Heavy signal or route change.
+7. The user-called/main agent orchestrates; implementation edits go to `worker` when subagent tools are available, otherwise the main agent takes over and records it. Advance a UI step only after the matching repository task transition succeeds with its required bound evidence.
+8. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/commands/pota-review.md

@@ -0,0 +1,16 @@
+# pota-review
+
+Use the `pota-review` skill.
+
+Prerequisite: resolve Pota from its installed runtime locator. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror; run published/global `pota doctor`, then `pota upgrade` to recover it. Never repair through another mirror or look for Pota runtime files in the target repository.
+
+Goal: review completed work against plan, memory, policy, and evidence.
+
+Procedure:
+
+1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before review work, then reads the plan task and available memory inputs.
+2. Check changed files, tool readiness evidence, and verification evidence. Inspect test, fixture, and verification-command diffs and reject any weakening without a recorded plan reason. For defect fixes, confirm the same-rule sweep was performed and its result recorded. Confirm the plan's Evidence has a filled `Memory promotion:` line (`docs/memory/<domain>.md` or `none: <reason>`) and that the installed Pota CLI's `memory check --root <repoRoot>` and `plan check --root <repoRoot>` exit 0. A `none: <reason>` decision is acceptable: do not create a note or demand one; flag a missing or placeholder line, or a named note that does not exist.
+3. Delegate independent read-only review to `explorer` when it materially improves speed or quality; use `worker` only for scoped verification reruns or QA artifacts. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits.
+4. Report findings first, ordered by severity, with file and line references. If no issues are found, say so clearly and mention remaining test gaps or residual risk.
+5. Record review evidence in `docs/plan/<topic>.md` and as the goal-level final review evidence record before completing the goal.
+6. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/commands/pota-toolcheck.md

@@ -0,0 +1,17 @@
+# pota-toolcheck
+
+Goal: detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
+
+From a globally installed package:
+
+```sh
+bunx @comento/pota-harness@latest toolcheck --root /path/to/repository
+```
+
+From the installed plugin runtime (resolve `pluginRoot` from its locator, not the target repository):
+
+```sh
+node "<pluginRoot>/scripts/pota.mjs" toolcheck --root "/path/to/repository"
+```
+
+Default toolcheck is read-only. When a required tool is missing, report the proposed change and obtain explicit user approval. Only then use `--install --yes`; unpinned or unsupported installers remain unavailable. Record detected stacks, missing tools, approvals, install attempts, timeouts, and blockers in the related `docs/plan/<topic>.md`.

package/commands/pota-uninstall.md

@@ -0,0 +1,27 @@
+# pota-uninstall
+
+Goal: remove the Codex, Claude Code, and Antigravity entries installed by Pota.
+
+Run from the published or global package:
+
+```sh
+bunx @comento/pota-harness@latest uninstall
+```
+
+The custom marketplace ownership manifest is authoritative. Uninstall first compares every non-config managed destination with its recorded installed digest and refuses the whole uninstall, changing nothing, if any managed artifact was modified or removed. Otherwise it removes or restores the managed destinations; unmanaged targets and their parent directories are preserved. A failure rolls back the transaction.
+
+Managed items:
+
+- Pota marketplace, plugin, and hook trust state blocks in `~/.codex/config.toml`.
+- `~/.pota/install/` (ownership manifest, canonical and retained runtimes, Codex marketplace source, Claude Code marketplace).
+- `$CODEX_HOME/plugins/cache/pota` (Codex versioned runtime cache and retained copies).
+- The Claude Code plugin `pota@pota` registration.
+- Auto-upgrade state in `~/.pota/update/`.
+- Claude Code `pota-*` commands and agents mirror files.
+- Antigravity IDE/CLI `pota-*` skills and workflows mirror files.
+
+Only the hosts recorded in the ownership manifest are touched.
+
+After the transaction commits, Pota removes empty managed scaffold directories bottom-up and removes `~/.pota/install/` and `$CODEX_HOME/plugins/cache/pota` only when empty, after releasing its own lifecycle lock. `~/.pota/update/` loses its known state files and is removed when empty. A directory containing any unmanaged child is preserved; pruning never uses recursive deletion.
+
+The source work folder, repository `MEMORY.md`, `PLAN.md`, `docs/`, and user-home Pota goal state (`~/.pota/projects/`) and settings (`~/.pota/config.json`) are not deleted. The globally installed `@comento/pota-harness` package, package-manager download caches, legacy backup files, and legacy shared settings not recorded by the current ownership manifest are also outside this command's scope and require a separate, explicit cleanup decision.