@comento/pota-harness 0.0.0-stage → 1.0.0

package/skills/pota-plan/heavy-path.md

@@ -0,0 +1,28 @@
+# Pota Plan: Heavy Path and Route Changes
+
+Reference for `pota-plan`. Read only when a Heavy Path signal is present or a route change is being considered. Quick Path and Light Path never need this file.
+
+## Heavy Path Flow
+
+Heavy Path flow: plan -> Heavy design task -> pre-implementation review -> bounded `worker` implementation -> verification worker or read-only review.
+
+- On a Heavy route, `goal replan` adds a `kind: "design"` task (`heavy-design`, `route: "heavy"`, `requiredEvidence: ["designRecord"]`) after `triage-plan`, and implementation tasks depend on it. The main agent never does this design inline: dispatch it read-only to the strongest tier (Claude Code Agent `model: "fable"`, `effort: "high"`, never `fork`), record `goal assign heavy-design --model <value> --model-source host-option --host <claude-code|codex|antigravity>`, merge the result into the plan's `## Heavy Design`, and bind that plan with `goal verify --kind designRecord`. 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>`. This is the only bypass.
+- Record the pre-implementation decisions that review must resolve before any mutation.
+- Every Heavy Path task includes an explicit automated test command and a `Tests:` evidence line; completion cannot rely on generic verification wording without test evidence.
+- Planning, review, and implementation request `high` reasoning effort; final verification and review request `xhigh` (see `pota://skills/pota-plan/delegation.md`).
+
+## Complexity Checkpoints
+
+Use three mandatory checkpoints and record each result, evidence, newly discovered Heavy Path signals, and current route in the plan artifact:
+
+1. **Request checkpoint:** before exploration, make a provisional classification from the request and `MEMORY.md`; uncertainty stays explicit and this result is not implementation authority.
+2. **Planning checkpoint:** after repository exploration, affected-surface analysis, and test design, re-evaluate the provisional route and finalize the implementation plan.
+3. **Code checkpoint:** during `pota-work`, inspect the exact files, callers, and tests, then record one final re-evaluation immediately before the first edit. A pending or missing code checkpoint blocks mutation.
+
+## Route Changes
+
+- Before the first edit, the planning or code checkpoint may change Light Path to Heavy Path or Heavy Path to Light Path when the evidence supports it.
+- Every route change rebuilds and synchronizes the plan artifact, the repository goal task roadmap through `goal replan`, and the native UI plan, including assignments, reviews, required evidence, and the reasoning effort profile. Do not mutate until all agree.
+- After editing starts, only promote Light Path to Heavy Path: stop further edits, mark affected evidence stale, revise and synchronize all roadmaps, run newly required Heavy Path review, and repeat the code checkpoint before resuming.
+- 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 Quick Path change that meets any failed Quick Path criterion escalates to Light Path first (plan + goal) before further edits; a Heavy signal then follows this file.

package/skills/pota-plan/planning-rules.md

@@ -0,0 +1,78 @@
+# Pota Plan: Planning Rules
+
+Reference for `pota-plan`. Read when writing or finalizing a Light or Heavy Path plan. Quick Path work has no plan and never needs this file.
+
+## When Planning Is Required
+
+Do not treat planning as optional for implementation that is more than a Quick Path change. Produce or update a plan when the request changes behavior, architecture, data, or multiple files, or when an external operation requires code edits, conflict resolution, destructive recovery, release/deploy, or design. External-state mutation alone is not a planning trigger: routine known-target Git/GitHub operations such as status, fetch, checkout, branch, merge, push, and PR management stay plan/goal-free.
+
+Plan from the whole work down. First understand the full requested outcome and affected surfaces, then classify the work into small executable tasks. If one task is still too broad to verify cleanly, split it into sub-tasks.
+
+## Reuse Before Planning
+
+Reuse recorded knowledge before exploring from scratch. Do not read every note or plan; pick by the index lines.
+
+- From `MEMORY.md` entries (`- [<name>](docs/memory/<name>.md): <summary>`), pick only the notes whose summary matches the request's modules, surfaces, or failures. The session-start hook lists the same notes; with no notes, continue without repository memory.
+- From `PLAN.md` (older topics in `docs/plan/ARCHIVE.md`), pick at most 3 completed plans that changed the same modules or solved the same kind of problem. Read only their goal, design decisions, and evidence sections, and reuse their verification commands, constraints, and rejected approaches.
+- Record the picks in the plan's `## Memory Inputs`: the selected `docs/memory/<domain>.md` paths and `Related completed plans:` with the plan paths, or `none related`.
+- Pass the selected note paths to delegated agents in the prompt `CONTEXT:` line (`delegation.md`).
+- When you create a plan file, add one line of 200 characters or fewer for it under `## Active Plans` in `PLAN.md` (`- [<topic>](docs/plan/<topic>.md): <title>`), or run `node "<pluginRoot>/scripts/pota.mjs" plan index --root "<repoRoot>"`. Entries are list lines under `## ` headings ending in `Plans`; a plan link elsewhere is a mention that `plan index` never rewrites. `## Completed Plans` stays newest first; `plan index --archive --root "<repoRoot>"` moves entries beyond the newest 20 to `docs/plan/ARCHIVE.md` without deleting them, and `plan check --root "<repoRoot>"` reports dead links and unindexed plans.
+
+## Planning Rules
+
+- Every initial plan must be decision-complete for its triage task and explicitly not implementation-ready; the post-triage revision must be decision-complete for implementation.
+- Every non-trivial implementation or planned-work continuation plan must be shown through Codex `update_plan` and `create_goal` before triage when those tools are available (host task-list tools `update_plan`, `create_goal`, `wrap_up` are called by the main agent only; a worker or subagent skips them and reports in its final report), then synchronized again after triage. Routine known-target Git/GitHub operations and Quick Path work do not create a plan or goal.
+- Every plan must describe the whole work first, then classify it into executable tasks and any needed sub-tasks.
+- Every plan must treat the user-called/main agent as the orchestrator and assign implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path (see `pota://skills/pota-plan/delegation.md`).
+- Every plan must include complexity triage, the selected path, and the Heavy Path signals checked, even when Light Path is selected.
+- Every plan must include applied model guidance and rationale.
+- Every plan must include tool readiness results: detected stack, required LSP/check tools, installed tools, and blockers.
+- Every executable plan must include a stable goal ID, stable task IDs, explicit terminal states, and fail-closed required evidence. A missing evidence section never means success.
+- Every implementation task must be small enough to verify with two checks: module acceptance verification and surface integration verification. Plan one goal-level final check (`finalReview`) run once through `goal finish` instead of rerunning earlier task checks after later edits.
+- Spend planning tokens on executable test design: requirements, invariants, boundaries, failure modes, expected initial failure, and authoritative tool result. Give implementation a bounded test contract and exact file scope; require the minimum passing change rather than renewed broad discovery.
+- Plan focused tests first, one final full check, and a package dry-run when no change occurred after the full check. Require lifecycle inspection, normal script execution for content-producing or unknown scripts, and `--ignore-scripts` only for absent or proven content-neutral scripts.
+- Heavy Path tasks must include an explicit automated test command and a `Tests:` evidence line.
+- Every risky or external-state-changing task must include the closest available dry-run or check command before the write/apply command.
+- Verification can expand for risk, but the reason must be recorded.
+- The default loop budget is two verification passes per task. If a gate fails, diagnose once, shrink or split the task, and rerun both gates. After two failed passes, record the blocker in `docs/plan/<topic>.md`.
+- Give every plan and ordered task a stable ID and declare task-level and goal-level required evidence, so Codex UI and hook context can show the roadmap and restore the current task after side questions.
+- Ask the user only when agents, repository evidence, or local verification cannot answer the decision.
+- User-visible responses and generated or updated documentation, plans, and memory artifacts follow the OS locale unless the user asks for another language.
+
+## Light Path Detail
+
+Light Path examples: one new API endpoint within existing layers; add or modify a controller or service method; strengthen validation rules; adjust query logic; change copy text or constants; fix one clearly scoped bug that exceeds Quick Path limits.
+
+Light Path flow: main-agent orchestration -> bounded `worker` implementation when subagent tools are available -> main-agent takeover when they are unavailable -> focused verification by the main agent or a scoped verification `worker` -> report. Planning/review agents may be skipped; the verification gate stays.
+
+## Route Record
+
+`docs/plan/<topic>.md` must record:
+
+- Selected path and selection rationale.
+- Heavy Path conditions found, if any, and conditions checked and not found.
+- Roles or delegation omitted in Light Path and why.
+- Any main-agent takeover because subagent tools were unavailable, and its evidence record.
+- Pre-implementation decisions that review must resolve in Heavy Path.
+- Request checkpoint, planning checkpoint, and code checkpoint status, evidence, newly found signals, and route.
+- Every route change and the synchronized plan artifact, repository goal task roadmap, native UI plan, assignments, reviews, required evidence, and stale evidence invalidation.
+
+## Tool Readiness Policy
+
+Do not silently skip LSP, typecheck, lint, dry-run, or verification because the tool is missing. Tool installation is a separate external-state change and requires explicit user approval.
+
+- Detect the codebase stack from repository files before choosing tools.
+- Prefer repository-local installation through the existing package manager and lockfile; use ephemeral runners only when project-local installation is not appropriate.
+- After approval, use the runtime's `toolcheck --install --yes --root "<repoRoot>"` only for pinned/supported installers, or the approved repository-native command. Run the tool after installation and record the result.
+- If installation was not approved or is impossible, record the proposed or attempted command, failure summary, and blocker in `docs/plan/<topic>.md`.
+- Treat "LSP server not installed" as an unresolved blocker until installation or an equivalent symbol-aware fallback has been attempted.
+
+## Dry-Run Policy
+
+Prefer repository-native dry-run and check modes before mutating external state.
+
+- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
+- Package and release work: inspect lifecycle scripts first, then use normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Never skip content-producing or unknown lifecycle scripts with `--ignore-scripts`; it is allowed only for absent or proven content-neutral scripts while prior full-check evidence remains fresh.
+- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
+- Code generation and formatting: check mode before write mode when available.
+- If no dry-run mode exists, record that fact and select the smallest reversible command or test artifact available.

package/skills/pota-review/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: pota-review
+description: Review completed Pota tasks against MEMORY.md, PLAN.md, domain policy, and two-gate evidence.
+---
+
+# Pota Review
+
+Use this after meaningful implementation with Pota.
+
+## Purpose
+
+Review is not another implementation loop. Confirm that the completed task satisfies the plan and that memory and plan artifacts are useful to the next agent.
+
+Every review run and delegated review agent reads project-root `MEMORY.md` when present. If it is absent, continue without repository memory and do not invoke another memory service.
+
+At the start and after compaction, restart, delegation, or handoff, restore context in this order: optional root `MEMORY.md` → `pota-review` → the active plan → completed/current-task references → model guidance recorded by the plan. Missing `MEMORY.md` is not an inconsistency. Confirm the remaining references agree with persisted goal state before reviewing. If any required reference is missing, unreadable, or inconsistent, do not approve, delegate, record final review, or complete the goal; report a blocker. Do not use a read-receipt field as evidence that a model understood a reference. 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.
+
+When subagent tools are available, each agent may recursively delegate bounded review 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.
+
+Resolve any `pota://...` resource through `references/pota-runtime.json` next to this `SKILL.md` (or this skill's `../..` source root during development). Never look for Pota runtime resources in the target repository. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover from the published/global package with `pota doctor` followed by `pota upgrade`; do not use another mirror as a repair source.
+
+## Procedure
+
+1. Read the completed task in `docs/plan/<topic>.md`.
+2. Read `MEMORY.md` when present and relevant `docs/memory/*.md`; continue when repository memory is absent.
+3. Check changed files, tool readiness evidence, and evidence paths. 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 `node "<pluginRoot>/scripts/pota.mjs" 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.
+4. Delegate independent review when it materially improves speed or quality and the current tool policy allows it.
+   - Use `explorer` for read-only impact analysis, pattern checks, and independent diff inspection.
+   - Use `worker` for scoped verification command re-runs or QA artifact capture.
+   - Recursive subagent delegation is allowed only for bounded sub-tasks when the current surface supports it.
+   - Keep blocking review work local when the next step depends immediately on the result.
+5. Report findings first, ordered by severity, with file and line references. If there are no issues, say so clearly and record remaining test gaps or residual risk.
+6. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+
+## Reviewer Prompt Format
+
+```text
+TASK: Review correctness, scope, and evidence for task <task-id>.
+EXPECTED OUTCOME: Findings ordered by severity with file and line references, or an explicit no-issue result with residual risk.
+REQUIRED TOOLS: Read-only diff inspection, tool readiness checks, verification command execution, plan/memory reading.
+MUST DO: Read the project-root `MEMORY.md` before doing assigned work. Check tool readiness and install-attempt evidence. Check dry-run or check evidence when external state could change. Check both module evidence and surface evidence. Check the `Memory promotion:` decision line and the `memory check` and `plan check` results. Preserve proper nouns exactly. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
+MUST NOT DO: Edit files. Ask the user. Approve skipped LSP/typecheck/lint without install evidence. Approve weakened, skipped, or deleted tests or verification commands without a recorded plan reason. Approve missing evidence or open-ended verification loops.
+CONTEXT: docs/plan/<topic>.md, MEMORY.md, relevant docs/memory notes, changed files.
+```
+
+## Completion Criteria
+
+- Findings are resolved or recorded as residual risk.
+- Tool readiness evidence is present for required LSP/check/verification tools.
+- Dry-run or check evidence is present when required, or the plan records why no dry-run exists.
+- Failed gates followed the bounded loop policy and did not continue past two verification passes without a recorded blocker.
+- Review evidence exists in `docs/plan/<topic>.md`.
+- The plan records its `Memory promotion:` decision, and `memory check` and `plan check` pass.
+- Goal-level final review evidence is stored as a successful structured evidence record before the goal is marked `completed`.
+- The next agent can understand verification without rereading the full conversation.

package/skills/pota-work/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: pota-work
+description: Use after pota-plan to execute the next incomplete docs/plan module task with the recorded Light/Heavy Path route, bounded worker delegation, dry-run/check evidence, and two verification gates.
+---
+
+# Pota Work
+
+Implement a `pota-plan` plan, never as a shortcut around planning: one module task at a time, advancing the goal until every task and the goal-level final review complete. Quick Path work (criteria in `pota-plan`) has no plan or goal: implement, run one focused check plus the project's normal check, and report; if any Quick Path criterion fails, escalate to Light Path (create plan + goal) before further edits.
+
+The user-called/main agent orchestrates (selects, assigns, verifies, records). Implementation edits go to `worker` whenever subagent tools are available; otherwise the main agent takes over and records it. Answer side questions briefly and resume the current task unless the user asks to pause, stop, or switch.
+
+## Re-entry and Required References
+
+At the start and after compaction, restart, delegation, or handoff, restore context in this order: optional root `MEMORY.md` → `pota-work` → the active plan → current-task references → model guidance recorded by the plan. Confirm that plan task, persisted current task, and assignment agree. Missing `MEMORY.md` is not an inconsistency. If state, plan, assignment, or another required reference is missing, unreadable, or inconsistent, do not edit, delegate, record completion evidence, or complete work; report a blocker. No read receipts: state and fresh tool-bound evidence are the authority. A delegated agent restores on its own entry; the orchestrator rereads only changed references, keeping the cached prefix stable.
+
+## Runtime Location
+
+Resolve the read-only runtime from `references/pota-runtime.json` next to this `SKILL.md` (its `pluginRoot`; in a source checkout without it, this file's `../..`). Never search the target repository for Pota files; resolve `pota://...` IDs through `pluginRoot`. If the runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover with published/global `pota doctor` then `pota upgrade`.
+
+The session-start hook prints `Pota CLI: node "<abs>/scripts/pota.mjs" goal <command>`. Copy that prefix literally into each command; never store it in a shell variable (shell variables do not persist between tool calls). `--root` is optional for every `goal` subcommand: when omitted it resolves via `HARNESS_REPO_ROOT`, else the nearest `.git` ancestor of the cwd.
+
+```sh
+node "<pluginRoot>/scripts/pota.mjs" goal task status --root "<repoRoot>"
+node "<pluginRoot>/scripts/pota.mjs" goal ready --root "<repoRoot>"
+node "<pluginRoot>/scripts/pota.mjs" goal replan --quiet --root "<repoRoot>" --tasks '[{"id":"<task-id>","title":"<task-title>","requiredEvidence":["moduleAcceptance","surfaceIntegration"]}]'
+node "<pluginRoot>/scripts/pota.mjs" goal assign --quiet --root "<repoRoot>" --task "<task-id>" --agent "<agent-id>" --effort "<value>" --effort-source "<host-option|inherited|not-applied>"
+node "<pluginRoot>/scripts/pota.mjs" goal verify --quiet --root "<repoRoot>" --task "<task-id>" --kind "moduleAcceptance|surfaceIntegration" --watch "<path|path>" -- <tool> <arg> ...
+node "<pluginRoot>/scripts/pota.mjs" goal task --quiet --root "<repoRoot>" --task "<task-id>" --status completed
+node "<pluginRoot>/scripts/pota.mjs" goal finish --quiet --root "<repoRoot>" --watch "<path|path>" -- <tool> <arg> ...
+node "<pluginRoot>/scripts/pota.mjs" goal stats --root "<repoRoot>"
+```
+
+- `goal verify` runs the argv after `--` without a shell and binds exit code, output digest, and watched fingerprint. One run with `--kind "a|b"` records one receipt per kind. Evidence scopes are only `task` and `goal`.
+- `goal finish` completes the active task (its required evidence must already be fresh), fails if any other task is not completed, runs the argv once, records every goal requiredEvidence kind (default `finalReview`) at goal scope, and completes the goal. It replaces the long form `task --status completed` → `verify --scope goal` → `complete`.
+- Read full `goal status` only when receipts are needed. `goal stats` prints JSON receipt counts, reruns, and stale receipts.
+- Use `--quiet` on state mutations. Pause, block, cancel, and claim: `recovery.md`.
+
+## Reference Files
+
+Read a reference only when the selected path or situation requires it (Quick and Light Path never need `heavy-path.md`):
+
+- `pota://skills/pota-work/verification.md`: timeouts, watch sets, freshness, defect investigation, tool readiness, dry-run policy.
+- `pota://skills/pota-work/delegation.md`: subagent lifecycle, parallel tasks, builder prompt, reasoning effort.
+- `pota://skills/pota-work/heavy-path.md`: Heavy gates and route changes; read only on a Heavy route or signal.
+- `pota://skills/pota-work/recovery.md`: failed gates, blocked/paused goals, ownership conflicts.
+
+## Procedure
+
+1. Read `MEMORY.md` when present, `PLAN.md`, the plan, relevant memory notes, and the `pota://docs/model-guidance/*.md` inputs it records.
+2. Read the current task with `goal task status`, then run `goal ready`: activate (`goal task --task <id> --status active`) and delegate independent ready tasks to parallel workers in the same worktree with disjoint `writeScope` and `--watch` inside it (`delegation.md`); rerun `goal ready` after each completion. Fold new requests in with `goal replan`, never cancel; with no goal, create one from the plan.
+3. Confirm tool readiness, route, and the request and planning checkpoints; inspect exact files, callers, and tests and record the code checkpoint just before the first edit (pending blocks mutation).
+4. Use the test contract first: spend reasoning on requirements, invariants, boundaries, and failure modes, write focused tests, confirm the intended failure, then give the `worker` only the contract, failing evidence, file scope, and constraints; require the minimum implementation.
+5. Before mutating external state, run the recorded dry-run or check (or record its absence).
+6. Run both gates through `goal verify -- ...` (module acceptance, surface integration). Treat the tool exit code as authoritative; keep successes short and expand context only for the failing test.
+7. Complete the task only with fresh required evidence, then continue. For the last task, run one goal-level final check through `goal finish -- ...`.
+8. Record evidence and the memory promotion decision (`verification.md`) in the plan and state before updating `PLAN.md`. Workers report only their assigned task.
+
+## Evidence Rules
+
+- Verification ladder: focused contract tests, then one full repository check after the final change, then package verification. 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 `--ignore-scripts` while the full check is fresh.
+- Any relevant mutation after a gate makes that result stale evidence; rerun the affected gate before completing the current task. Do not rerun earlier completed tasks' checks after later edits: one fresh goal-scope receipt for every goal requiredEvidence kind recorded after all task receipts supersedes their fingerprints (if goal requiredEvidence is empty, task freshness is still rechecked).
+- Never edit, weaken, skip, or delete existing tests, fixtures, snapshots, or recorded verification commands to make a gate pass; record a genuine contract change in the plan first. After a defect fix, search for other implementations of the same rule or pattern.
+- At most two verification passes per task; after two failures, record the blocker (`recovery.md`).
+- Model and reasoning effort: This skill explicitly instructs the effort level for delegated work. Use each task's recorded model and request Light `medium`, Heavy `high`, final verification/review `xhigh`. Every new task/worker dispatch MUST pass the task's model and effort through the host option (Claude Code: Agent `model`/`effort`; never `fork`). Recording without passing is a defect. Record Requested/Effective model and reasoning effort per task (details, Heavy completion gate: `delegation.md`). Route changes resync the reasoning effort profile: completed profiles are preserved, incomplete profiles are recalculated.
+- Missing, failed, skipped, stale, or placeholder evidence never completes work. Use the OS locale for output and artifacts.
+
+## Completion Criteria
+
+- Both gates passed with fresh evidence (Heavy: `Tests:`); the goal finished through `goal finish` or is explicitly `paused`, `blocked`, or `cancelled` with a reason.
+- Delegation, tool readiness, dry-run, route, and model guidance followed the plan; no judge weakened; defect fixes record the same-rule sweep.
+- Evidence is in the plan before `PLAN.md` is updated.

package/skills/pota-work/delegation.md

@@ -0,0 +1,65 @@
+# Pota Work: Delegation and Reasoning Effort
+
+Reference for `pota-work`. Read before dispatching a `worker` or `explorer`, or when recording reasoning effort. Quick Path work done directly by the main agent does not need this file.
+
+## Subagent Lifecycle
+
+- The user-called/main agent is the orchestrator: it selects the task, assigns implementation, verifies results, and records evidence. Actual implementation edits belong to `worker` subagents whenever subagent tools are available, regardless of Light Path or Heavy Path.
+- Delegate implementation with exact files, ownership, constraints, and model-specific adjustment rules. For Light Path use one bounded `worker`. Use `explorer` for parallel read-only discovery or verification when useful.
+- When the subagent tool provides a progress-reporting channel, subagents report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing. The orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, the orchestrator relays observable events such as assignment, waiting, and final completion.
+- Delegated subagents must provide a final report before leaving. After the orchestrator captures the final report and evidence, it must close or release the completed subagent, then review the final report and evidence before marking the work complete.
+- When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Every child subagent reads project-root `MEMORY.md` when present and continues when absent, keeps the assigned scope, and preserves others' edits.
+- Put the selected `docs/memory/<domain>.md` note paths (picked from `MEMORY.md` entries) in the prompt `CONTEXT:` line. A delegated agent may not receive the session-start memory list, so do not rely on it reaching subagents.
+- Host task-list tools (`update_plan`, `create_goal`, `wrap_up`) are called by the main agent only; a worker or subagent skips them (hosts reject them from subagents) and reports in its final report.
+- If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
+- `worker` returns a structured handoff for only its assigned goal/task: changed files, tool readiness result, dry-run or check result when applicable, automated test result for Heavy Path, module acceptance command and result, surface integration command or QA artifact, blocker, and cleanup notes. A worker must not select the next task.
+
+## Parallel Tasks
+
+- `goal ready` (read-only) prints `{"active":[...],"ready":[...],"blocked":[...]}` task ids. A ready task is pending with every dependency completed.
+- Only ready tasks can be activated: `goal task --task <id> --status active`. At most 4 tasks are active at once; active `writeScope`s must not overlap (segment-wise prefix, case-insensitive), and a task without `writeScope` is active only alone. start/replan/completion auto-activate only the first ready task when nothing is active; open further parallel tasks explicitly.
+- Assign one `worker` per active task (`goal assign`); assignment, evidence, and completion stay per task. Workers stay inside their `writeScope` and exchange data only through the plan's handoff files.
+- Parallel workers must run in the same Git worktree: goal state is stored per worktree, so another worktree sees no goal.
+- While other tasks are active, task-scope `goal verify` needs `--watch` paths inside that task's `writeScope`, so sibling edits cannot stale or fail its evidence; goal-scope verify needs `--watch` when 2 or more tasks are active.
+- Rerun `goal ready` after each completion. A blocked task keeps its dependents pending while unrelated branches continue; the goal becomes blocked only when no task is active or ready.
+- Main Stop gates on all active tasks; SubagentStop gates the stopping agent's own assigned active task. The hook adds one `Parallel active:` line only when 2 or more tasks are active.
+
+## Builder Prompt Format
+
+```text
+TASK: Implement task <task-id> for <topic>.
+EXPECTED OUTCOME: Minimal code or documentation change satisfying the task contract.
+REQUIRED TOOLS: Scoped file editing, tool readiness checks, existing test/build commands, surface QA commands.
+MODEL: <tier/value> (passed via host option)
+REASONING EFFORT: <value> (passed via host option)
+MUST DO: Read the project-root `MEMORY.md` before doing assigned work and follow its policy. Stay within the listed file scope and the task's `writeScope`. Assume you are not alone in the codebase; do not revert others' edits. Follow the subagent lifecycle rules (status reporting when a channel exists, final report before leaving, recursive delegation only for bounded sub-tasks with these same constraints, passing each child's reasoning effort through the host option; report the exact model ID from your own system prompt in the final report, `unreported` if absent, never guess; skip host task-list tools `update_plan`, `create_goal`, `wrap_up`). Obtain explicit user approval before installing missing tools. Run dry-run or check mode before external-state mutation when available. Provide module evidence, surface evidence, and a structured handoff scoped to the assigned goal/task. Never edit, weaken, skip, or delete existing tests, fixtures, or verification commands to pass a gate without a reason recorded in the plan. After a defect fix, search for other implementations of the same rule or pattern and report them. Copy the Pota CLI prefix line literally; never store it in a shell variable. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
+MUST NOT DO: Ask the user. Skip LSP/typecheck/lint because a tool is missing without attempting installation. Refactor unrelated code. Continue an open-ended verification loop. Treat a side question as permission to abandon the active task. Delegate vague or unbounded work. Claim completion without evidence. Modify files outside the assigned ownership.
+CONTEXT: docs/plan/<topic>.md task, selected `docs/memory/<domain>.md` note paths, applied model guidance, exact files, verification commands, Pota CLI prefix line.
+```
+
+## Model and Reasoning Effort Routing
+
+This skill explicitly instructs the effort level for delegated work. It also instructs each task's model.
+
+- The plan decides each task's model from its nature and records `Requested model` and `Effective model`; models are not always inherited. Tiers: fast = read-only exploration, search, inventory, summarization (Claude Code `haiku`); balanced = Light Path implementation and routine verification (`sonnet`); stronger = planning, complexity triage, Heavy Path implementation, review, and final verification/review (`opus`); strongest = Heavy Path design only (`fable`).
+- Model Effective is the passed value plus the exact model ID the worker reports from its own system prompt, e.g. `fable (claude-fable-5-1)`; when the report has no ID, record `<value> (unreported)` and never guess, via `goal assign --effective-model <id|unreported>`. Not passed is `not-applied: <reason>`; `inherited` only when the host has no model option. Codex passes the tier's slug (table below) through the host-native model option, else `inherited`.
+- If a lower-tier worker fails a gate, re-dispatch that task one tier up (fast, balanced, stronger, strongest) before recording a blocker.
+- A subagent's model and effort are fixed at dispatch. Any re-dispatch that changes either (one tier up, Light → Heavy promotion, route-change recalculation) MUST be a new dispatch (Claude Code: a new Agent call); never continue the existing subagent with `SendMessage`, which keeps its original model and effort.
+- Routing is per dispatch only; never change model or global/user config files. `Model routing: inherited` in `MEMORY.md` or the plan disables per-task selection.
+- Light Path planning, implementation, and verification request `medium`.
+- Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
+- Every new task/worker dispatch MUST pass the task's requested effort through the host option. Recording without passing is a defect. Pass the chosen model the same way (Claude Code: Agent `model`). Child (recursive) dispatches follow the same rule.
+- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`. Requested is Pota's desired profile; Effective is decided by the dispatch call:
+  - Effort passed and not rejected: Effective is the requested value.
+  - Effort not passed: `not-applied: <reason>`; the reason is required.
+  - `inherited` only when the host exposes no effort option. Describe host capability only from the exposed interface or dispatch response, and distinguish Pota non-integration from host non-support.
+
+| Host | Model / effort option | Effective |
+| --- | --- | --- |
+| Claude Code | Agent tool `model` parameter (`haiku\|sonnet\|opus\|fable`). `effort` parameter (`low\|medium\|high\|xhigh\|max`), matching Pota values one to one. `subagent_type: "fork"` ignores `model` and `effort`, so never dispatch routed work as a fork. | requested value |
+| Codex | Host-native model option (fast `gpt-6-luna`, balanced `gpt-6.1-terra`, stronger `gpt-6-sol`, strongest `gpt-6-astra`) and task/subagent reasoning-effort option or equivalent. | requested value |
+| Antigravity | `invoke_subagent` `Model` takes only a tier enum: fast `flash_lite`, balanced `flash`, stronger `pro`, strongest `pro` (no tier above `pro`); `inherit` is not used for routed work. No effort option. | model: passed value; effort: `inherited` |
+| Host without an option | None. | `inherited` |
+
+- After each dispatch, record state with `goal assign --task <id> --agent <id> --effort <value> --effort-source <host-option|inherited|not-applied>`; for a `kind: "design"` task also `--model <value> --model-source host-option --host <claude-code|codex|antigravity>`. A design model that is not the host's strongest tier (`--host claude-code` `fable`, `codex` `gpt-6-astra`, `antigravity` `pro`; any of the three when `--host` is omitted) fails completion unless `--allow-no-design-model <reason>`. Mark Heavy tasks with `route: "heavy"` (tasks JSON field or `goal assign --route heavy`). A Heavy task with no effort, `not-applied`, or `inherited` fails `goal task --status completed` unless `--allow-inherited-effort <reason>` records why.
+- On every route change, synchronize the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before edits resume. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.

package/skills/pota-work/heavy-path.md

@@ -0,0 +1,18 @@
+# Pota Work: Heavy Path and Route Changes
+
+Reference for `pota-work`. Read only when the recorded route is Heavy Path, a new Heavy Path signal appears, or a route change is being considered. Quick Path and Light Path never need this file.
+
+## Heavy Path Execution
+
+- Follow the full planning and review pipeline recorded in the plan without role-mapping shortcuts: pre-implementation review before mutation, bounded `worker` implementation, then verification worker or read-only review after evidence exists.
+- Heavy implementation cannot complete until a completed `kind: "design"` task exists (record it with `--host <claude-code|codex|antigravity>`). A design model that is not the host's strongest tier (`--host claude-code` `fable`, `codex` `gpt-6-astra`, `antigravity` `pro`; any of the three when `--host` is omitted) fails completion unless `--allow-no-design-model <reason>`. This is the only bypass.
+- Run the recorded automated test command and record explicit `Tests:` evidence in the plan before claiming completion. This is required even when module acceptance uses a broader check command.
+- Planning, review, and implementation request `high` reasoning effort; final verification and review request `xhigh`.
+
+## Route Changes During Work
+
+1. Confirm the request checkpoint and planning checkpoint, inspect the exact files, callers, and tests, then record the code checkpoint immediately before the first edit. Missing or pending checkpoints block mutation.
+2. Before the first edit, evidence may change Light Path to Heavy Path or Heavy Path to Light Path. On every route change, update the plan artifact first, replace the incomplete repository goal task roadmap with `goal replan`, update the native UI plan to the same stable task order, and synchronize assignments, reviews, required evidence, and the reasoning effort profile. Do not mutate until all agree.
+3. After editing starts, only promote Light Path to Heavy Path. On a new Heavy Path signal, stop further edits, mark affected evidence stale, revise and synchronize the plan artifact, repository goal task roadmap, and native UI plan, run newly required Heavy Path review, and repeat the code checkpoint before resuming.
+4. 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.
+5. Quick Path work that hits any failed Quick Path criterion first escalates to Light Path (create plan + goal) before further edits; a Heavy signal then follows step 3.

package/skills/pota-work/recovery.md

@@ -0,0 +1,29 @@
+# Pota Work: Recovery
+
+Reference for `pota-work`. Read only when a gate fails twice, a goal must be paused, blocked, or cancelled, another session owns the goal, or state and plan disagree.
+
+## Bounded Loop Policy
+
+- Run at most two verification passes per task by default.
+- If a gate fails, diagnose the cause once, shrink the task or split it into sub-tasks, then rerun both gates.
+- After two failed passes, stop implementation for the task, record the blocker in `docs/plan/<topic>.md`, and transition the task or goal to `blocked` with a concrete reason instead of continuing automatically.
+- Do not imitate repeated red-green loops unless the plan explicitly records a risk-based reason.
+
+## Truthful Goal States
+
+```sh
+node "<pluginRoot>/scripts/pota.mjs" goal task --quiet --root "<repoRoot>" --task "<task-id>" --status blocked --reason "<concrete blocker>"
+node "<pluginRoot>/scripts/pota.mjs" goal block --quiet --root "<repoRoot>" --reason "<concrete blocker>"
+node "<pluginRoot>/scripts/pota.mjs" goal pause --quiet --root "<repoRoot>"
+node "<pluginRoot>/scripts/pota.mjs" goal resume --quiet --root "<repoRoot>"
+node "<pluginRoot>/scripts/pota.mjs" goal cancel --quiet --root "<repoRoot>"
+```
+
+- `active` is not a completion state. Successful completion or cancellation removes the user-home active state because completed evidence already lives in the plan document; paused and blocked state remains resumable.
+- Resume a paused or blocked goal before folding new work into it with `goal replan`. Start a separate goal only when the user explicitly switches work.
+
+## Ownership and State Conflicts
+
+- When a hook reports that another session owns the goal and this session continues that same work, take ownership with `goal claim --quiet --root "<repoRoot>" --session "<session-id-shown-by-hook>"`. Never guess or invent a session ID.
+- If the plan task, persisted current task, and worker assignment disagree, or a required reference is missing, unreadable, or inconsistent, do not edit, delegate, record completion evidence, or complete work; report a blocker to the orchestrator.
+- If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover with published/global `pota doctor` followed by `pota upgrade`; do not use another mirror as a repair source.

package/skills/pota-work/verification.md

@@ -0,0 +1,79 @@
+# Pota Work: Verification Detail
+
+Reference for `pota-work`. Read when a gate needs more than the evidence rules in `SKILL.md`: watch sets, timeouts, freshness, defect investigation, missing tools, or external-state dry-runs, and before `goal finish` for the memory promotion decision.
+
+## Goal Verify Semantics
+
+- `goal verify --task "<task-id>" --kind "<kind>[|<kind>]" [--watch "<path|path>"] [--timeout-ms N] -- <argv>` executes the argv without a shell and records exit code, bounded tool output, output digest, and watched-workspace fingerprint. With several kinds, one run records one receipt per kind.
+- Evidence scopes are only `task` and `goal`. Goal scope is normally recorded by `goal finish`; the long form is `goal task --status completed` → `goal verify --scope goal --kind finalReview -- <argv>` → `goal complete`.
+- Verification defaults to 600,000 ms (10 minutes), accepts a shorter `--timeout-ms`, and is capped at 3,600,000 ms (1 hour).
+- The external command never holds the state lock. A receipt is committed only when the starting goal/task identity and the pre/post watched fingerprint still match.
+- Choose the watch set and verification command at the semantic boundary that proves the claimed behavior. With no explicit watch, Git-ignored files are excluded; pass each ignored artifact required by the claim with `--watch <path>` or watch its containing directory.
+- The legacy `goal receipt` command imports declared evidence for compatibility; declared evidence does not satisfy a default tool-bound goal.
+
+## Freshness
+
+- A task's required evidence must be fresh when that task is completed. Any relevant mutation after a gate makes that result stale evidence: rerun the affected focused gate and, when integration could change, the full gate.
+- At goal completion, task evidence fingerprints are not rechecked when a fresh goal-scope receipt for every goal requiredEvidence kind was recorded after every task receipt. Do not rerun earlier tasks' checks after later edits; run one final goal-level check instead (`goal finish`).
+- If goal requiredEvidence is empty, task freshness is still rechecked at goal completion.
+- `goal stats` prints JSON with verify receipt counts (total, by kind), reruns (repeated scope+task+kind), and currently stale receipts. Use it to measure verification overhead.
+- The PostToolUse evidence reminder is emitted once per goal/task/session, not after every edit; its absence is not evidence.
+
+## Token-Efficient Test Contract
+
+1. Run the focused contract tests.
+2. Implement the minimum change and rerun only those tests while diagnosing.
+3. Run the full repository check once after the final change.
+4. Before package verification, inspect lifecycle scripts such as `prepack`, `prepare`, and `prepublishOnly` and classify whether they produce package contents.
+5. Run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never be skipped with `--ignore-scripts`; their generated contents are part of the package contract.
+6. Only when lifecycle scripts are absent or proven content-neutral, the full check is still fresh, and the dry-run only checks the file list may package verification use `npm pack --dry-run --ignore-scripts`.
+
+On success retain only the command, exit code, and pass count needed for evidence. Do not reread unrelated files or replay successful output.
+
+## Verification Integrity
+
+- The implementer must not be able to change the judge. Never edit, weaken, skip, or delete existing tests, fixtures, snapshots, or recorded verification commands to make a gate pass. When a contract genuinely changes, record the reason in `docs/plan/<topic>.md` before that edit; review rejects any judge change without a recorded reason.
+- Prefer executable checks (test, lint, script, hook) for machine-checkable rules; keep prose only for rules that need judgment.
+
+## Memory Promotion
+
+Decide once per goal, before `goal finish`, whether the goal produced repository knowledge the next agent should reuse, and record the decision in the plan's `## Evidence` as exactly one of:
+
+- `Memory promotion: docs/memory/<domain>.md`: the note written or updated for this goal.
+- `Memory promotion: none: <reason>`: nothing worth promoting, with the reason.
+
+The decision line is required; the note is optional. When nothing qualifies, do not create a note; record `none: <reason>`.
+
+- Promote: non-obvious constraints or invariants the next task would have to rediscover, decisions with their rejected alternatives, recurring failures and their fixes, and verification recipes.
+- Do not promote: what the code or tests already state, details that apply only to this task, or a restatement of the plan.
+- When promoting, write or update `docs/memory/<domain>.md` with its `Summary:` line (`pota-memory`), then run `node "<pluginRoot>/scripts/pota.mjs" memory index --root "<repoRoot>"` and `memory check --root "<repoRoot>"`.
+- The `Memory promotion:` key and the `none` value are fixed English tokens. When a goal completes through `goal finish` or `goal complete` and its plan file has no filled `Memory promotion:` line, Pota prints a one-line reminder on stderr; exit code and stdout are unchanged and completion is never blocked. `goal stats --history` counts the decisions across goals.
+
+## Defect Investigation
+
+- Reproduce a reported defect with repository tools before fixing it; do not wait for more detail when a local reproduction is possible.
+- For unclear or non-reproducible failures, test one hypothesis at a time and close it with a measurement before changing code. Never fix on speculation.
+- Answer feasibility questions with a bounded experiment or measurement instead of an unverified "not possible". Stop and ask only when the experiment would bypass a security policy or mutate external state without approval.
+- After fixing a defect, search the repository for other implementations of the same rule or pattern. Fix them within the assigned scope or record them as follow-up in the plan.
+
+## Two Verification Gates
+
+- Module acceptance: targeted unit, typecheck, lint, parser, schema, or command that proves the module contract.
+- Surface integration: HTTP, browser, CLI, tmux, desktop, or parsed artifact evidence proving behavior through the real surface.
+- Heavy Path test gate: an explicit automated test command recorded as `Tests:` evidence, even when module acceptance uses a broader check.
+
+## Tool Readiness Policy
+
+- Run the tool readiness command recorded in the plan before implementation; if none is recorded, run the runtime's `toolcheck --root "<repoRoot>"`.
+- Missing LSP, typecheck, lint, dry-run, or verification tools must be reported with an install proposal. Installation requires explicit user approval and a pinned/supported installer (`toolcheck --install --yes`) or an approved repository-native command.
+- After installation, rerun the exact tool command and record evidence. If installation fails, stop the task and record the blocker rather than silently falling back to less precise exploration.
+
+## Dry-Run Policy
+
+Run the closest available dry-run or check mode before commands that mutate external state.
+
+- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
+- Package and release work: inspect lifecycle scripts, then run normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Use `--ignore-scripts` only for absent or proven content-neutral lifecycle scripts while prior full-check evidence remains fresh.
+- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
+- Code generation and formatting: check mode before write mode when available.
+- If no dry-run mode exists, record that fact in `docs/plan/<topic>.md` before continuing.

package/templates/MEMORY.md

@@ -0,0 +1,12 @@
+# MEMORY
+
+Index of repository knowledge. Each line under Domain Knowledge locates one note in `docs/memory/`; the knowledge itself lives in the note. Maintain with `pota memory index` and `pota memory check`.
+
+## Domain Knowledge
+
+## Policy
+
+- Prefer precise repository exploration before implementation.
+- Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
+- Read only the detailed memory files needed for the current task.
+- Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.

package/templates/PLAN.md

@@ -0,0 +1,9 @@
+# PLAN
+
+Index of work plans. Each line locates one plan in `docs/plan/`; details and evidence live in the plan. Planning rules live in the `pota-plan` skill. Maintain with `pota plan index` and `pota plan check`.
+
+## Active Plans
+
+## Completed Plans
+
+Newest first; one line per plan. `pota plan index --archive` moves older entries to `docs/plan/ARCHIVE.md`.

package/templates/domain-memory.md

@@ -0,0 +1,22 @@
+# Domain: <name>
+
+Summary: <one line, at most 120 characters: what this note answers and when to read it>
+
+## Scope
+
+Describe the domain boundary covered by this note.
+
+## Facts
+
+- Source:
+- Evidence:
+- Impact:
+
+## Policy
+
+- Rule:
+- Rationale:
+
+## References
+
+- Path or command: