@comento/pota-harness 0.0.0-stage → 1.0.0

package/commands/pota-upgrade.md

@@ -0,0 +1,26 @@
+# pota-upgrade
+
+Goal: update the Pota installation from the current source.
+
+Run from the published or global package, not from the installed cache copy:
+
+```sh
+bunx @comento/pota-harness@latest upgrade
+bunx @comento/pota-harness@latest upgrade --hosts codex,claude
+```
+
+The current custom marketplace lifecycle remains in use. An installed copy (`~/.pota/install/` or the Codex plugin cache) is a replacement target and must not upgrade itself.
+
+Actions:
+
+- Replace only files tracked by the ownership manifest whose current digest still matches the installed digest.
+- Recompute Pota-owned hook trust state without rewriting public feature or agent settings.
+- Replace owned Claude Code and Antigravity mirror files with the latest content.
+- Refresh runtime locators for every installed surface.
+- Stage and validate all candidates before commit; rollback committed phases in reverse order on failure.
+- Preserve and report a conflict for modified or unmanaged artifacts.
+- Keep the recorded hosts unless `--hosts` (`all` or a comma list of `codex`, `claude`, `antigravity`) changes them; deselected hosts are removed, and a modified artifact of a deselected host refuses the upgrade.
+- After a version change, keep the previous canonical runtime and Codex cache copy for 3 days (at most 3 of each); expired ones are removed by the next install or upgrade. A Codex cache copy at or above the new version is never kept, because Codex loads the highest cached version.
+- When the Claude Code plugin cache holds a different version, run `claude plugin marketplace update pota` and `claude plugin update pota@pota --scope user`. If that fails, keep the upgraded files, print those commands, and exit 1.
+- Refuse, changing nothing, when the installed version is newer than this CLI; `--allow-downgrade` moves the installation to this CLI's version anyway.
+- `upgrade --auto` is reserved for the auto-upgrade runner; it keeps the recorded hosts, never downgrades (it cannot be combined with `--allow-downgrade`), and refuses to run without an existing installation.

package/commands/pota-work.md

@@ -0,0 +1,24 @@
+# pota-work
+
+Use the `pota-work` 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 or model guidance in the target repository.
+
+Goal: execute the active goal's current task without bypassing complexity triage, then keep advancing tasks until goal-level final review completes or the goal is explicitly paused, blocked, or cancelled. Quick Path work has no plan or goal: implement, run one focused check plus the project's normal check, and report; escalate to Light Path (plan + goal) before further edits if any Quick Path criterion fails.
+
+Record the code checkpoint after exact file/caller/test inspection immediately before the first edit. After editing begins, a new Heavy Path signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize the plan artifact, `goal replan` roadmap, and native UI plan, and repeat the code checkpoint. 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 selecting or executing a task.
+2. Read `PLAN.md`, the detailed plan, relevant memory notes, and the `pota://` model guidance recorded in the plan through the installed runtime.
+3. Read the current task with `goal task status`; run `goal ready` and delegate independent ready tasks to parallel workers (same worktree, disjoint `writeScope`). Fold a new request into an unfinished goal with `goal replan` instead of cancelling it. Copy the session-start hook's `Pota CLI:` prefix literally; never store it in a shell variable. `--root` may be omitted when the cwd is inside the repository.
+4. Confirm tool readiness (installation only with explicit approval) and the recorded route.
+5. Before implementation, spend reasoning on a focused executable test contract covering requirements, invariants, boundaries, and failure modes. Confirm the intended failure, then give the `worker` the contract, failing evidence, exact file ownership, and constraints and require the minimum change.
+6. Run module acceptance and surface integration through `goal verify -- ...`; `--kind "moduleAcceptance|surfaceIntegration"` records both from one run. Treat tool exit codes as authoritative and expand context only around failing tests. Heavy Path records explicit `Tests:` evidence.
+7. 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 reported defects before fixing, and after a fix search for other implementations of the same rule or pattern.
+8. Inspect package lifecycle scripts and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it while the full check remains fresh.
+9. Relevant mutation makes the current task's evidence stale; rerun it before completing the task. Do not rerun earlier tasks' checks; finish with one goal-level check through `goal finish -- ...`. Missing, failed, skipped, stale, or placeholder evidence never completes work. `goal stats` measures receipt reruns; `goal stats --history` compares finished goals of the repository.
+10. Read the skill's reference files only when needed: `pota://skills/pota-work/verification.md`, `pota://skills/pota-work/delegation.md`, `pota://skills/pota-work/recovery.md`, and `pota://skills/pota-work/heavy-path.md` (Heavy route only).
+11. Before `goal finish`, record the memory promotion decision in the plan's Evidence: `Memory promotion: docs/memory/<domain>.md` when the goal produced reusable repository knowledge (write the note with a `Summary:` line, then run `memory index --root <repoRoot>`), otherwise `Memory promotion: none: <reason>`. The line is required and the note is optional: do not create a note when nothing qualifies. Update the plan, goal state, and `PLAN.md` only after evidence exists. Answer side questions briefly and resume unless explicitly asked to pause, stop, or switch.
+12. 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/docs/model-guidance/README.md

@@ -0,0 +1,67 @@
+# Model Guidance
+
+Pota only applies model-specific adjustment to Claude-family and Codex-family models.
+
+The goal is not to make prompts long by model. The goal is to stabilize the same `MEMORY.md`/`PLAN.md` flow according to model strengths.
+
+## Application Order
+
+1. Identify the active model name. If the model name is not directly exposed, infer it from the user's default model setting and agent role frontmatter.
+2. Resolve this installed guidance root from the active skill's `references/pota-runtime.json` or the source skill's location. Never look for Pota model guidance in the target repository. If the shared runtime or locator is missing, unreadable, or inconsistent, stop using every dependent mirror; run published/global `pota doctor`, then `pota upgrade` for recovery, rather than repairing through another mirror.
+3. For Claude-family models, apply `pota://docs/model-guidance/claude.md`.
+4. For Codex-family models, apply `pota://docs/model-guidance/codex.md`.
+5. If the model is not clearly classified, apply only the common rules and skip model-specific adjustment.
+
+## Common Rules
+
+- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore context in this order: optional root `MEMORY.md` → current phase skill → active plan → current-task references → model guidance recorded by the plan. If `MEMORY.md` is absent, continue without repository memory and do not invoke another memory service. If persisted state or an assignment requires another reference that is missing, unreadable, or inconsistent, fail closed: do not edit, delegate, approve, or complete; report or record a blocker. Delegation means the delegated agent restores on its own entry; the orchestrator does not re-read this chain after dispatching or collecting a subagent, and within one unbroken context it rereads only references that changed, which keeps the cached prompt prefix stable.
+- Keep root `MEMORY.md` and `PLAN.md` as indexes only.
+- Keep repository-specific judgment in `docs/memory/` and `docs/plan/`. Keep Pota's model guidance in the installed plugin and reference it with `pota://docs/model-guidance/...`.
+- Treat the user-home `.pota/projects/<project-id>/worktrees/<worktree-id>/state.json` as a worktree-bound active-work slot. State without `worktreeId` and state copied into another worktree are stale and are removed on the next hook/goal start. Successful completion or cancellation removes the owning copy after plan evidence is recorded; only paused or blocked work remains for resumption.
+- Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
+- Select Light Path or Heavy Path before implementation.
+- Treat complexity as three checkpoints: a provisional request checkpoint, a post-exploration planning checkpoint, and a code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
+- Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, and records evidence.
+- Delegate actual implementation edits to `worker` subagents whenever subagent tools are available, regardless of Light Path or Heavy Path.
+- When the subagent tool provides a progress-reporting channel, require subagents to report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, the orchestrator relays observable events such as assignment, waiting, and final completion.
+- When a delegated subagent finishes, require a final report before it leaves; after capturing the final report and evidence, the orchestrator closes or releases the completed subagent, then reviews the final report and evidence before marking the work complete.
+- If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
+- Detect required LSP, typecheck, lint, dry-run, and verification tools before implementation.
+- Missing required tools must be reported with a proposed install. Installation requires explicit user approval and a pinned/supported installer.
+- Treat non-trivial implementation or continuation of planned work as authorization to bind active work to a persisted Pota goal and stable task IDs, even when the user does not mention a goal. 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. For planned work, after MEMORY.md, first write an initial plan that makes triage the active task, synchronize it before exploration, and implement only from the decision-complete revision. Exclude consultation, explanation, and plan-only requests. Quick Path changes (criteria in `pota-plan`) need no plan or goal and escalate to Light Path before further edits when a criterion fails.
+- Treat missing, failed, skipped, stale, or placeholder evidence as failure. Task evidence records must be bound to the current goal, task, and plan.
+- Treat the repository Pota state as the fail-closed transition authority. Advance the matching Codex UI plan step only after the evidence-gated repository task transition succeeds.
+- Spend reasoning on a focused executable test contract before implementation: requirements, invariants, boundaries, and failure modes. Give implementation only that contract, failing evidence, file scope, and constraints; require the minimum passing change.
+- Run verification through `goal verify -- ...`; its default timeout is 600,000 ms and its maximum is 3,600,000 ms. Treat tool exit codes and bounded machine summaries as authoritative. Record evidence only when the starting goal/task identity and pre/post watched fingerprint still match, and choose the watch set and command at the semantic boundary that proves the claim. The default Git fingerprint excludes ignored files; explicitly pass every ignored artifact needed by the claim with `--watch`. Compress success output and expand context only for failing tests and related code.
+- Use a verification ladder: focused contract tests, one full check after the final change, then package dry-run while the full check remains fresh. Inspect package lifecycle scripts first and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it. Do not rerun earlier tasks' checks after later edits; finish with one goal-level check through `goal finish -- <argv>`.
+- Every implementation task must pass module acceptance verification and surface integration verification.
+- Before mutating external state, run the closest available dry-run, check, plan, diff, validate, or equivalent command.
+- Limit each task to two verification passes by default. After two failed passes, record the blocker or split it into sub-tasks instead of continuing a repeated loop.
+- User-visible responses and generated or updated documentation, plans, and memory artifacts must follow the OS locale unless the user asks for another language.
+
+## Prompt Cache Shape
+
+- Keep `.codex-plugin/plugin.json` `defaultPrompt` as a small, stable policy and recovery kernel. Put detailed bootstrap, delegation, test, package, and verification procedures in the phase skills and this installed guidance.
+- Put static instructions before dynamic goal data. Hook capsules must be deterministic for the same locale, event, and persisted state; prompt text and turn IDs must not change their content.
+- Idle capsules reference root `MEMORY.md` and `pota-plan`; active-work capsules reference the active plan, current task, and `pota-work`; all-tasks-complete capsules reference `pota-review`.
+- A foreign session receives only a generic ownership-conflict capsule on session/prompt events. It must not expose goal, plan, or task details, and it must not make stop hooks block work owned by another session.
+- Character budgets are regression proxies for cache-friendly prompt shape, not measurements of provider cache hits or cost. Pota does not require provider cache keys, breakpoints, or live API telemetry.
+- Do not add read receipts that claim model attention. Restore references on every re-entry and use readable state plus fresh bound evidence as the enforceable contract.
+
+## Model and Reasoning Effort Routing
+
+- The plan decides each task's model from its nature and records `Requested model` and `Effective model`; models are not always inherited. Tiers: fast = read-only exploration, search, inventory, summarization (Claude Code `haiku`); balanced = Light Path implementation and routine verification (`sonnet`); stronger = planning, complexity triage, Heavy Path implementation, review, and final verification/review (`opus`); strongest = Heavy Path design only (`fable`), run as a separate `kind: "design"` task dispatched to that tier rather than part of planning. Antigravity `invoke_subagent` `Model` accepts only a tier enum (fast `flash_lite`, balanced `flash`, stronger `pro`, strongest `pro`; no tier above `pro`) and has no effort option, so Effective reasoning effort is `inherited`. Codex slugs: fast `gpt-6-luna`, balanced `gpt-6.1-terra`, stronger `gpt-6-sol`, strongest `gpt-6-astra`.
+- Model Effective: the passed value plus the exact model ID the worker reports from its own system prompt (e.g. `fable (claude-fable-5-1)`; `<value> (unreported)` when absent, never guess; `goal assign --effective-model <id|unreported>`); not passed is `not-applied: <reason>`; `inherited` only when the host has no model option. If a lower-tier worker fails a gate, re-dispatch that task one tier up (fast, balanced, stronger, strongest) before recording a blocker. A subagent's model and effort are fixed at dispatch; any re-dispatch that changes either (one tier up, Light → Heavy promotion, route-change recalculation) MUST be a new dispatch (Claude Code: a new Agent call), never `SendMessage` to the existing subagent. A design model that is not the host's strongest tier (`--host claude-code` `fable`, `codex` `gpt-6-astra`, `antigravity` `pro`; any of the three when `--host` is omitted) fails completion unless `--allow-no-design-model <reason>`.
+- Routing is per dispatch only; never change model or global/user config files. `Model routing: inherited` in `MEMORY.md` or the plan disables per-task selection.
+- Light Path planning, implementation, and verification request `medium`.
+- Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
+- Every plan task records `Requested reasoning effort` and `Effective reasoning effort`. Requested is Pota's desired profile; Effective is the value confirmed by the dispatch result.
+- Every new task/worker dispatch MUST pass the task's requested effort through the host-exposed reasoning-effort option or host-native equivalent (Claude Code: Agent tool `effort`; `fork` ignores `model` and `effort`). Pass the chosen model the same way (Claude Code: Agent tool `model`). Recording without passing is a defect.
+- Effective is the requested value when the dispatch passed it and the host did not reject it, `not-applied: <reason>` when it was not passed, and `inherited` only when the host exposes no effort option. Describe host capability only from an exposed interface or dispatch result, and distinguish Pota's choice not to integrate or use an option from host non-support. Do not change the model or global config and do not silently choose a nearby value.
+- A route change synchronizes the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before edits resume. Preserve completed task profiles as audit history and recalculate incomplete task profiles for the new path.
+
+## Delegation Defaults
+
+- `explorer`: use for read-only codebase discovery, impact analysis, pattern searches, and read-only verification when available.
+- `worker`: use for actual implementation edits or verification tasks with clear file ownership.
+- Main session: orchestrate, immediately relay received subagent status events or observable subagent lifecycle events to the user, verify, and record evidence; keep only urgent non-implementation blocking work local when the next step depends immediately on the result, except that unavailable subagent tools make the main agent take over implementation directly.

package/docs/model-guidance/claude.md

@@ -0,0 +1,49 @@
+# Claude Model Guidance
+
+Claude-family models are strong at long-context retention, policy interpretation, and plan consistency review. In Pota, use those strengths for planning, policy interpretation, and evidence review.
+
+## Use Strengths
+
+- Read policies across multiple documents and summarize conflicts.
+- Judge domain boundaries, risk, rollback ability, and user impact.
+- Check whether required LSP, typecheck, lint, dry-run, and verification tools were discovered and bootstrapped.
+- Check whether `docs/plan/<topic>.md` is decision-complete.
+- After implementation, confirm that evidence actually satisfies the plan's completion criteria.
+
+## Adjustment Rules
+
+- Do not bloat plans with long explanations. Keep decisions, rationale, and evidence.
+- Preserve frequency words such as "all", "each", and "required". Do not handle only the first item and stop.
+- Do not accept "tool missing" as a reason to skip precise codebase exploration until install or bootstrap has been attempted.
+- Do not skip the two verification gates even on Light Path.
+- Do not approve a plan that lacks dry-run or check evidence for external-state-changing work.
+- Do not allow open-ended verification loops. Require a blocker or sub-task split after two failed passes.
+- Choose the model per task (fast `haiku`, balanced `sonnet`, stronger `opus`: planning, triage, Heavy implementation, review, final verification/review; strongest `fable`: Heavy design only, as a separate `kind: "design"` task dispatched to that tier rather than part of planning) and record `Requested model`/`Effective model`; Effective is the passed value plus the exact model ID the worker reports from its own system prompt (`<value> (unreported)` when absent, never guess), `not-applied: <reason>`, or `inherited` when the host has no model option. Re-dispatch one tier up (fast, balanced, stronger, strongest) if a lower-tier worker fails a gate. A subagent's model and effort are fixed at dispatch; any re-dispatch that changes either (one tier up, Light → Heavy promotion, route-change recalculation) MUST be a new dispatch (Claude Code: a new Agent call), never `SendMessage` to the existing subagent. A design model that is not the host's strongest tier (`--host claude-code` `fable`, `codex` `gpt-6-astra`, `antigravity` `pro`; any of the three when `--host` is omitted) fails completion unless `--allow-no-design-model <reason>`. `Model routing: inherited` disables this. `Requested reasoning effort` is Pota's desired profile; `Effective reasoning effort` is what the dispatch response confirms. Every new task/worker dispatch MUST pass the task's requested effort through the host option together with the chosen model; recording without passing is a defect. Effective is the requested value when the dispatch passed it and the host did not reject it, `not-applied: <reason>` when it was not passed, and `inherited` only when the host exposes no effort option. Infer capability only from the exposed interface or dispatch response, distinguish Pota non-integration from host non-support, and change no global/user configuration.
+- In Claude Code, pass model with the Agent tool `model` parameter (`haiku|sonnet|opus|fable`) and effort with `effort` (`low|medium|high|xhigh|max`, same as Pota values), for example `{"description": "Implement task-1", "subagent_type": "general-purpose", "model": "sonnet", "effort": "medium", "prompt": "..."}`. `subagent_type: "fork"` ignores `model` and `effort`; never dispatch routed work as a fork.
+- On Heavy Path, check plan gaps before implementation.
+- Review all three complexity records: the provisional request checkpoint, post-exploration planning checkpoint, and code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
+- Before asking the user, use repository evidence and available `explorer`/`worker` delegation when it materially improves speed or quality.
+- Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+
+## Path Guidance
+
+### Policy And Risk
+
+- Summarize domain boundaries and risk from repository evidence.
+- If policy is unclear, propose candidates to record in `docs/memory/<domain>.md`.
+- Clearly name risk signals that require Heavy Path.
+
+### Planning
+
+- Keep the plan short and executable.
+- Always record complexity triage and the selected Light/Heavy Path.
+- Always record tool readiness and blockers.
+- Each module task must include files, contract, dry-run or check command when applicable, module acceptance verification, and surface integration verification.
+
+### Review
+
+- Lead with findings.
+- Do not approve without evidence.
+- Check that missing tools have install-attempt evidence before approving a fallback.
+- Check that dry-run or check evidence exists when external state could change.
+- Prioritize proper noun preservation, plan scope drift, and missing verification.

package/docs/model-guidance/codex.md

@@ -0,0 +1,68 @@
+# Codex Model Guidance
+
+Codex-family models are strong at small implementation tasks, explicit tool use, and repeatable verification. In Pota, prefer them for bounded `worker` tasks and structurally clear planning. When Codex is the user-called/main agent, it orchestrates instead of making implementation edits directly whenever subagent tools are available.
+
+## Use Strengths
+
+- Quickly handle implementation tasks with clear file scope.
+- As `worker`, make actual implementation edits within the assigned file scope.
+- As the user-called/main agent, delegate implementation edits to `worker` whenever subagent tools are available.
+- As a subagent, report status to the orchestrator when the current subagent tool provides a progress-reporting channel, including when starting work, when deciding or confirming direction, during periodic progress, and when finishing.
+- As a subagent, provide a final report before leaving when assigned work is complete.
+- Read existing patterns and make minimal changes in the same style.
+- Run repository tool readiness checks and bootstrap missing command-line tools.
+- Capture module acceptance verification and surface integration verification from command results.
+- Run dry-run, check, plan, diff, validate, or equivalent commands before mutating external state.
+- Explore independent work in parallel and sequence only dependent work.
+
+## Adjustment Rules
+
+- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore optional root `MEMORY.md` → current phase skill → active plan → current-task references → recorded model guidance. Missing `MEMORY.md` never blocks and must not trigger another memory service. If persisted state or the assignment requires another missing, unreadable, or inconsistent reference, fail closed and report a blocker before editing, delegating, approving, or completing. Delegation means the delegated agent restores on its own entry; the orchestrator does not re-read this chain after dispatching or collecting a subagent, and within one unbroken context it rereads only references that changed, which keeps the cached prompt prefix stable.
+- Do not start implementation without a plan.
+- Choose the model per task by tier (fast, balanced, stronger, strongest) and pass it through the host-native model option as fast `gpt-6-luna`, balanced `gpt-6.1-terra`, stronger `gpt-6-sol`, strongest `gpt-6-astra`; record `Requested model`/`Effective model` (`inherited` when the host exposes no model option). Re-dispatch one tier up if a lower-tier worker fails a gate. `Model routing: inherited` disables this. `Requested reasoning effort` is Pota's desired profile; `Effective reasoning effort` is what the dispatch response confirms. Every new task/worker dispatch MUST pass the task's requested effort through the host's task/subagent option together with the chosen model; recording without passing is a defect. Effective is the requested value when passed and not rejected, `not-applied: <reason>` when not passed, and `inherited` only when the host exposes no effort option. Infer capability only from the exposed interface or dispatch response, distinguish Pota non-integration from host non-support, and change no global/user configuration.
+- Do not treat complexity as a one-time choice. Require the provisional request checkpoint, post-exploration planning checkpoint, and code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
+- Do not stop before local implementation solely because subagent tools are unavailable; the main agent takes over implementation directly and records that takeover in evidence.
+- Keep work units small. Split large changes into smaller plan tasks.
+- If `apply_patch` is unstable in the environment, use an editing tool or a clear file update path.
+- Do not duplicate the same exploration. Wait for already delegated searches.
+- Do not trust success-looking output alone. Confirm real files, commands, and surface evidence.
+- Do not skip LSP, typecheck, lint, dry-run, or verification because a tool is missing. Try repository-local installation or record the failed install attempt as a blocker.
+- Do not continue an open-ended verification loop. Use at most two verification passes per task unless the plan records a risk-based exception.
+- Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+- Preserve the stable prompt prefix: keep detailed workflow in phase skills/model guidance, and do not vary a hook capsule with prompt text or turn ID when persisted state is unchanged.
+
+## Path Guidance
+
+### Planning
+
+- Use `update_plan` to display the initial triage roadmap before repository exploration, then use `create_goal` when exposed so the Codex UI has an active goal before the turn can be interrupted.
+- Treat the initial plan as decision-complete for its `triage-plan` task, not as authorization to implement. After triage, update the same repository plan and `update_plan` roadmap to the decision-complete implementation revision.
+- On Light Path, write explicit task contracts when a plan artifact exists.
+- Record detected stack, required tools, install commands, and tool blockers.
+- Specify file scope and verification commands so implementation does not need to rediscover them.
+- Specify the dry-run or check command for tasks that can mutate external state, or record why none exists.
+- On failure, prefer sub-task splitting over a repeated loop.
+
+### Implementation
+
+- Invest Codex reasoning in executable test design first, then hand the bounded failing contract to implementation and require the minimum passing patch.
+- Run verification through `goal verify -- ...`. Its default timeout is 600,000 ms (10 minutes), capped at 3,600,000 ms (1 hour). On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint; commit evidence only when the starting goal/task identity and pre/post watched fingerprint match. Choose the watch set and command at the semantic boundary that proves the claim. The default Git fingerprint excludes ignored files; explicitly `--watch` every ignored artifact needed by the claim. Expand diagnostics only for the failing test and its related file/symbol scope; reject stale evidence after related changes.
+- If acting as the user-called/main agent, orchestrate the work and delegate actual implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path.
+- If acting as the user-called/main agent, immediately relay received subagent status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion.
+- If acting as the user-called/main agent, close or release completed subagents after capturing their final report and evidence, then review the final report and evidence before marking the work complete.
+- If acting as `worker`, edit only within the file scope listed in the plan.
+- Confirm required tools are available. Install or bootstrap missing required tools before implementation.
+- Run the recorded dry-run or check command before external-state mutation when applicable.
+- After changes, run both module acceptance verification and surface integration verification.
+- Inspect package lifecycle scripts before package verification. Run normal `npm pack --dry-run` by default; content-producing or unknown lifecycle scripts must never use `--ignore-scripts`, while absent or proven content-neutral scripts may use it only when the prior full check remains fresh.
+- If a gate fails, diagnose once, shrink the task or split it into sub-tasks, and rerun both gates. Stop after the second failed pass and record the blocker.
+- Return evidence in a form that can be recorded in `docs/plan/<topic>.md`.
+
+### Delegation
+
+- Handle search, file listing, command checks, and QA artifact capture.
+- Use `explorer` for independent read-only discovery or read-only verification when available.
+- When using `worker`, state clear file ownership and tell the worker not to revert others' edits.
+- Tell subagents to report status when the tool provides a progress-reporting channel: starting work, deciding or confirming direction, periodic progress, and finishing.
+- Tell subagents to provide a final report before leaving, then close or release them after evidence is captured. Review the final report and evidence before marking the work complete.
+- If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.

package/hooks/hooks.json

@@ -0,0 +1,65 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/pota-state.mjs\" session-start",
+            "timeout": 10,
+            "statusMessage": "Pota: loading read-only repository context"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/pota-state.mjs\" user-prompt-submit",
+            "timeout": 10,
+            "statusMessage": "Pota: loading read-only work context"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(apply_patch|write|Write|edit|Edit|multi_edit|multiedit|MultiEdit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/pota-state.mjs\" post-tool-use",
+            "timeout": 10,
+            "statusMessage": "Pota: reminding current goal evidence requirements"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/pota-state.mjs\" stop",
+            "timeout": 10,
+            "statusMessage": "Pota: checking the active goal task"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/pota-state.mjs\" subagent-stop",
+            "timeout": 10,
+            "statusMessage": "Pota: checking this subagent's assigned task"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@comento/pota-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
+  "license": "MIT",
+  "author": {
+    "name": "WkNam"
+  },
+  "homepage": "https://github.com/comento/pota-harness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comento/pota-harness.git"
+  },
+  "keywords": [
+    "codex",
+    "claude-code",
+    "antigravity",
+    "agent",
+    "harness",
+    "plugin",
+    "workflow"
+  ],
+  "bin": {
+    "pota": "scripts/pota.mjs"
+  },
+  "files": [
+    ".agents/",
+    ".claude/",
+    ".codex-plugin/",
+    "agents/",
+    "commands/",
+    "docs/model-guidance/",
+    "hooks/",
+    "scripts/pota",
+    "scripts/*.mjs",
+    "skills/",
+    "templates/",
+    "README.md",
+    "README.*.md"
+  ],
+  "scripts": {
+    "check": "node --check scripts/pota.mjs && node --check scripts/pota-paths.mjs && node --check scripts/pota-safe-fs.mjs && node --check scripts/pota-goal.mjs && node --check scripts/pota-state.mjs && node --check scripts/pota-cleanup.mjs && node --check scripts/pota-lifecycle.mjs && node --check scripts/pota-lifecycle-layout.mjs && node --check scripts/pota-lifecycle-hosts.mjs && node --check scripts/pota-update-state.mjs && node --check scripts/pota-auto-upgrade.mjs && node --check scripts/pota-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8'))\" && npm test",
+    "test": "node --test",
+    "prepack": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/pota

@@ -0,0 +1,14 @@
+#!/bin/sh
+set -eu
+
+script_path="$0"
+link_target="$(readlink "$script_path" 2>/dev/null || true)"
+if [ -n "$link_target" ]; then
+  case "$link_target" in
+    /*) script_path="$link_target" ;;
+    *) script_path="$(dirname "$script_path")/$link_target" ;;
+  esac
+fi
+script_dir="$(cd "$(dirname "$script_path")" && pwd)"
+
+exec node "$script_dir/pota.mjs" "$@"