@quantmind-br/pi-goal-x 0.0.0-stage → 0.35.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+<div align="center">
+  <img src="pi-goal-x.png" alt="pi-goal-x logo" width="560">
+</div>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+  <a href="https://pi.dev/packages?type=extension" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="assets/badge-dark.svg">
+      <img src="assets/badge-light.svg" alt="TOP 0.2% of Pi coding agent extensions: #5 of 3,477 by downloads · Oct 27, 2026 (best recorded rank)" width="480">
+    </picture>
+  </a>
+</div>
+
+# pi-goal-x
+
+Adds `/goal` functionality to [pi](https://pi.dev). The agent helps you define a goal and plan, continues working on it automatically, and submits the result to an optional independent completion auditor.
+
+The extension saves goal objectives, tasks, and progress across sessions. You can pause, resume, revise, or switch goals as your work changes.
+
+## Install
+
+This is the `@quantmind-br` fork of [pi-goal-x](https://github.com/tmonk/pi-goal-x). It keeps the goal tool profile fixed so provider prompt caches survive goal lifecycle changes; see `CHANGELOG.md`.
+
+```bash
+pi install npm:@quantmind-br/pi-goal-x
+```
+
+## Create a goal
+
+```text
+/goal Add CSV export to the reports page, with documentation and tests.
+```
+
+The agent discusses the goal with you, asks focused questions where needed, and proposes an objective, task plan, and completion requirements. You review the proposal and choose whether to use the completion auditor. Once you confirm, the agent starts working and continues automatically while the goal is active.
+
+You can specify completion requirements, such as passing the test suite or producing a report with every required section. The agent tracks tasks and subtasks, records evidence, and works toward those requirements. If it gets blocked and needs your input, you can resolve the issue and resume.
+
+If you already have a complete objective, use `/goal-direct <objective>` to create the goal and start immediately without drafting.
+
+## Goal types
+
+| Type | Behaviour | Example uses |
+| --- | --- | --- |
+| **Regular** — `/goal` | An outcome to achieve, with the agent choosing and adapting the plan. | Features, debugging, research, and documentation. |
+| **Sisyphus** — `/sisyphus` | An ordered plan that the agent follows one step at a time. | Migrations, staged refactors, and release procedures. |
+
+For an ordered goal, you can provide the steps or define them with the agent:
+
+```text
+/sisyphus Migrate authentication in this order:
+1. Add the new token validator.
+2. Update login and session refresh to use it.
+3. Remove the old validator.
+4. Run the authentication tests.
+```
+
+Use `/sisyphus-direct <objective>` to start an ordered goal without drafting.
+
+## Tasks and subtasks
+
+The agent can divide a goal into tasks and subtasks, each describing part of the work required to complete it. During guided goal creation, you review the proposed plan before work begins.
+
+For example, a CSV export goal could have this task plan:
+
+```text
+Add CSV export to reports
+├─ Review the report data and active filters
+├─ Implement CSV export
+│  ├─ Generate the CSV from filtered results
+│  └─ Add a download button
+├─ Test the export
+└─ Document how to use it
+```
+
+As work progresses, the agent marks the current task, records completed work, and explains any skipped tasks. The dashboard shows what is done and what remains, including progress within subtasks. Task progress is saved when you pause and remains available in later sessions.
+
+Tasks can also have their own completion requirements—for example, “The download contains only rows matching the active filters.” The agent records evidence against those requirements, and the completion auditor uses that evidence when reviewing the overall result.
+
+Use `/goal-tweak <change>` to discuss revisions to the goal and its plan. Task tracking, completion requirements, and subtask depth are configurable in `/goal-settings`.
+
+## Completion auditor
+
+When enabled, a separate agent reviews the work before the goal is accepted as complete. It checks the objective, tasks, recorded evidence, completion requirements, and workspace.
+
+If the auditor approves, the goal is archived as complete. If it identifies unmet requirements, the goal remains open with feedback describing the work still needed. You can choose the auditor model in `/goal-settings` and toggle auditing for the focused goal with `Ctrl+Shift+A`.
+
+## Progress and goal controls
+
+The dashboard above the editor shows the goal's status, task progress, current task, elapsed time, and token usage. Press `Ctrl+Shift+T` to expand it for the full task tree, completion requirements, evidence, and recent activity. Audit progress and results appear there too.
+
+A project can have several open goals, with one focused goal per session. Switch with `/goal-focus`, pause with `/goal-pause`, or use `/goal-tweak` to discuss changes to the current goal. Pressing `Esc` during active work also pauses the goal; in the expanded dashboard, it collapses the view.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/goal [idea]` | Discuss, plan, and confirm a regular goal. |
+| `/sisyphus [idea]` | Discuss, plan, and confirm an ordered goal. |
+| `/goal-direct <objective>` | Create and start a regular goal immediately. |
+| `/sisyphus-direct <objective>` | Create and start an ordered goal immediately. |
+| `/goal-list` | List open goals. |
+| `/goal-status` | Show the focused goal and its progress. |
+| `/goal-focus` | Choose an open goal to work on. |
+| `/goal-unfocus` | Leave the current goal open without focusing on it. |
+| `/goal-tweak <change>` | Revise the current goal with the agent. |
+| `/goal-pause` | Pause work on the focused goal. |
+| `/goal-resume` | Resume a paused or blocked goal. |
+| `/goal-clear` | Archive the focused goal after confirmation. |
+| `/goal-cancel` | Cancel an unconfirmed draft. |
+| `/goal-settings` | Configure goal behaviour and the auditor. |
+
+For troubleshooting, use `/goal-status verbose` for more detail, `/goal-status health` or `/goal-recovery` to check for problems, and `/goal-refresh` to reload saved goals and settings after external changes. `/goal-recovery repair` offers repairs after confirmation.
+
+## Settings
+
+Open `/goal-settings` to change these options. You can save defaults for all projects, override them for the current project, or remove an override to use the inherited value.
+
+| Setting | What it controls |
+| --- | --- |
+| Explicit execution contracts (`strictExecutionContract`) | Opt-in ready/wait protocol with one missing-decision repair, then pause. Defaults to `false`: successful executions continue automatically. |
+| Autonomous run allowance (`maxAutonomousRuns`) | Positive whole number of extension-started runs per creation or `/goal-resume` period. **Unset means unlimited; zero disables automatic continuation.** Settings edits change the limit without resetting usage. |
+| Autonomous runs line (`showAutonomousRuns`) | Controls the `Autonomous runs: N/limit` line that appears for a finite allowance. Defaults to `true`. |
+| Task tracking (`disableTasks`) | Turn task lists on or off. Set to `true` to disable them. |
+| Subtask depth (`subtaskDepth`) | Limit how many levels of subtasks the agent can create. |
+| Completion requirements (`disableContracts`) | Turn explicit goal and task completion requirements on or off. Set to `true` to disable them. |
+| Unfocused reminder (`hideUnfocusedPrompt`) | When a session has no focused goal but open goals exist in the selected pool, the agent receives a `[PI GOAL UNFOCUSED]` reminder on every request. Set to `true` to stop that reminder. Defaults to `false`. This is independent of `hideUnfocusedBanner`, which hides only the unfocused widget and status hint. Neither setting selects or resumes a goal; the separate `autoSelectSingleGoal` setting still applies. |
+| Auditor disabled | Turn off independent completion review. |
+| Auditor provider, model, and thinking level | Choose which model reviews completed work and its reasoning effort. |
+
+## License
+
+MIT

package/assets/badge-dark.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="54" viewBox="0 0 480 54" role="img" aria-label="TOP 0.2% of Pi coding agent extensions: #5 of 3,477 by downloads · Oct 27, 2026 (best recorded rank)">
+  <!-- Dark mode -->
+  <style>
+    .frame { fill: #14181f; stroke: #2a3040; stroke-width: 1; }
+    .rank { font: 700 15px ui-monospace, 'SF Mono', Menlo, Consolas, monospace; letter-spacing: 0.04em; fill: #d4a656; }
+    .label { font: 400 13px ui-monospace, 'SF Mono', Menlo, Consolas, monospace; fill: #e8e6df; }
+    .meta { font: 400 11px ui-monospace, 'SF Mono', Menlo, Consolas, monospace; fill: #7d8494; }
+    .divider { stroke: #2a3040; stroke-width: 1; }
+    .link { text-decoration: none; }
+  </style>
+  <a class="link" href="https://pi.dev/packages?type=extension" target="_blank" rel="noopener noreferrer">
+    <rect class="frame" x="0.5" y="0.5" width="479" height="53" rx="6"/>
+    <text class="rank" x="18" y="34">TOP 0.2%</text>
+    <line class="divider" x1="128" y1="13" x2="128" y2="41"/>
+    <text class="label" x="143" y="25">of Pi coding agent extensions</text>
+    <text class="meta" x="143" y="41">#5 of 3,477 by downloads · Oct 27, 2026</text>
+  </a>
+</svg>

package/assets/badge-light.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="54" viewBox="0 0 480 54" role="img" aria-label="TOP 0.2% of Pi coding agent extensions: #5 of 3,477 by downloads · Oct 27, 2026 (best recorded rank)">
+  <!-- Light mode -->
+  <style>
+    .frame { fill: #f6f8fa; stroke: #d0d7de; stroke-width: 1; }
+    .rank { font: 700 15px ui-monospace, 'SF Mono', Menlo, Consolas, monospace; letter-spacing: 0.04em; fill: #9a6700; }
+    .label { font: 400 13px ui-monospace, 'SF Mono', Menlo, Consolas, monospace; fill: #1f2328; }
+    .meta { font: 400 11px ui-monospace, 'SF Mono', Menlo, Consolas, monospace; fill: #59636e; }
+    .divider { stroke: #d0d7de; stroke-width: 1; }
+    .link { text-decoration: none; }
+  </style>
+  <a class="link" href="https://pi.dev/packages?type=extension" target="_blank" rel="noopener noreferrer">
+    <rect class="frame" x="0.5" y="0.5" width="479" height="53" rx="6"/>
+    <text class="rank" x="18" y="34">TOP 0.2%</text>
+    <line class="divider" x1="128" y1="13" x2="128" y2="41"/>
+    <text class="label" x="143" y="25">of Pi coding agent extensions</text>
+    <text class="meta" x="143" y="41">#5 of 3,477 by downloads · Oct 27, 2026</text>
+  </a>
+</svg>

package/docs/advanced-usage.md

@@ -0,0 +1,106 @@
+# Advanced usage
+
+For installation, goal workflows, commands and the settings overview, see the [README](../README.md).
+
+## Automatic continuation and optional execution contracts
+
+Active goals continue automatically after successful executions, including reasoning-only responses and final-task verification. No tool call, task update, or scheduling declaration is required.
+
+Default continuation is immediate. To slow repeated replies without recognized work, enable **slow repeated idle replies (opt-in)** under Advanced execution in `/goal-settings` (`idleContinuationBackoff: true`). Use the scope switch to choose a global default or a project override. An explicit project `false` overrides global `true`; removing the override restores inheritance.
+
+When enabled, one execution without recognized work continues immediately. Further such executions wait 30, 60, 120, 240, then 300 seconds between attempts. Work observed anywhere in the execution or a change to the objective, requirements or tasks resets the delay. Goal inspection, echo-only calls, accounting and scheduling declarations alone do not reset it. This heuristic may delay reasoning or unfamiliar custom tools, and repeated recognized tool calls can bypass it. It reduces request rate; it does not guarantee progress or finite spending. Use a run allowance or token budget for a hard limit.
+
+The delay survives reloads and shows a relative time, local clock time and resume command. Waiting spends no autonomous runs or active time. Turning the option off cancels a pending delay promptly without renewing spent runs or resuming a paused goal. Turning it on starts observing a subsequent execution, rather than classifying work retroactively. Old saved delay metadata has no effect without opt-in. `/goal-resume` renews the run allowance and continues now; incoming user/producer messages remain ordinary host work outside that allowance. Strict waits and provider-error recovery keep their separate timing.
+
+Enable `strictExecutionContract: true` in `/goal-settings` or your global/project settings to require explicit ready/wait decisions. In that mode, a missing decision permits one repair prompt within the remaining allowance, then pauses. This is a user preference; agents should not enable it merely to continue.
+
+Set an appropriate allowance in `/goal-settings`, or in `.pi/pi-goal-x-settings.json`:
+
+```json
+{ "maxAutonomousRuns": 20 }
+```
+
+The `Autonomous runs: used/limit` line reports a finite allowance and is left out when
+allowance is unlimited. Set `showAutonomousRuns` to `false` to drop it for a finite
+allowance as well; it defaults to `true`.
+
+Agents may edit this setting. Changing it does not replenish consumed runs; explicit `/goal-resume` renews the period and continues now, including from a waiting goal. No configured allowance is required unless the effective limit is zero, which disables resume. Tool calls within a run are not separate runs. Existing token budgets still apply.
+
+`showContextUsage` defaults to `false`. Set it to `true` to include context-window occupancy in new goal prompt snapshots. Accounting, budgets and automatic compaction continue normally. Existing snapshots remain historical.
+
+Explicit `ready` is optional in default mode. A goal saved before next actions were
+removed still loads, with its `nextAction` field stripped during normalization.
+New `wait` declarations require strict mode; otherwise they return a non-terminating error. Previously saved waits retain their deadline, checks, and repair rules when upgrading or disabling strict mode, and may be re-declared with the same identity. Mode changes never resume a paused goal or renew consumed runs.
+
+```js
+update_goal({ continuation: { kind: "ready" } })
+update_goal({ continuation: {
+  kind: "wait", reason: "Await the remote build",
+  deadline: "2026-09-15T12:00:00Z",
+  polling: { interval_seconds: 60, max_checks: 3 }
+} })
+```
+
+Use a future deadline appropriate to the task. Omit `polling` for an event-only wait. Successful declarations terminate the execution segment. On a scheduled check, reuse the returned `wait_id` and original deadline, omitting `polling`; remaining checks cannot be reset. A ready decision ends the wait. Time spent waiting is not active execution time.
+
+The dashboard, `/goal-status`, and `get_goal` show scheduling state, timing, checks, and allowance consumption. Expired waits and exhausted checks or allowance pause without another model call. Waits survive reopening the same session, without replaying missed checks; Pi must remain open for timers to execute. Another session requires explicit resume to take ownership. An ambiguous interrupted dispatch requires resume instead of automatic replay.
+
+## Background producer integration
+
+Budget-controlled producers emit a scheduler signal instead of starting their own model turn:
+
+```js
+pi.events.emit("pi-goal:wake", { goalId, waitToken });
+```
+
+`waitToken` is returned in the wait declaration's tool-result details. Register it before the producer completes, or retain the completion until registration (for example, observe the `update_goal` tool result in the host adapter). The token changes after consumption and re-declaration. A matching signal received before agent settlement is retained; duplicate, stale and wrong-goal tokens are ignored. A signal and timer can claim only one wake.
+
+Existing producers that directly send `triggerTurn`/`followUp` messages still run as ordinary host work and supersede old pending decisions. Those independently started turns are **outside this extension's allowance**; use `pi-goal:wake` to put them through its spending gate. The allowance also does not limit Pi's own within-run tool loop or native retries. It bounds the goal extension's kickoff, continuation, check, signal, repair and recovery dispatches.
+
+## Prompt caching
+
+Goal state is refreshed at the request tail while the system prompt and conversation prefix stay stable. Pi retains control of provider cache settings. See [prompt caching](prompt-caching.md) for explicit-cache handling, validation, and cache invalidation boundaries.
+
+## Changing a token budget
+
+Use the existing tweak flow: `/goal-tweak remove the token budget` or `/goal-tweak set the token budget to 50000`. The proposal shows the current and proposed limits before confirmation. A budget is a total lifetime limit, not an additional allocation; consumed tokens and completed work are preserved. Omitting a budget change retains the current limit.
+
+After confirmation, a goal stopped only by its budget can continue if the revised limit allows it and scheduling permits. A still-exhausted budget keeps it stopped. Other-session ownership, interrupted execution and exhausted autonomous-run allowances still require their existing recovery steps. Creation and tweak results always show the effective budget.
+
+## Optional arguments on Responses-compatible providers
+
+Some Pi `openai-responses` configurations omit the wire-level `strict` flag. OpenAI Responses may normalize schemas into strict mode when that flag is omitted. This can conflict with optional goal arguments; it is separate from pi-goal-x's `strictExecutionContract` scheduling setting.
+
+For the reported OpenCode model, a narrowly scoped Pi `models.json` override makes the Pi adapter send `strict: false` for ordinary tools:
+
+```json
+{
+  "providers": {
+    "opencode": {
+      "modelOverrides": {
+        "gpt-6-astra": { "compat": { "supportsStrictMode": true } }
+      }
+    }
+  }
+}
+```
+
+The capability flag permits the adapter to send the explicit non-strict opt-out; it does not request strict sampling for ordinary goal tools. Merge this into existing model configuration and reload Pi. This is a provider-specific workaround, not a guarantee about third-party model behavior. The local reproduction inspects requests before transmission; the issue's live OpenCode A/B result has not been independently reproduced. See [issue #59](https://github.com/tmonk/pi-goal-x/issues/59) and [OpenAI's function-calling documentation](https://developers.openai.com/api/docs/guides/function-calling).
+
+## Sharing a goal pool across worktrees
+
+By default goals stay in `<cwd>/.pi/goals`. Set `goalsRoot` in your project or global settings to an absolute directory (or `~/path`), or set `PI_GOAL_ROOT` for the session. Precedence is environment, project, global, then the existing default. For example:
+
+```json
+{ "goalsRoot": "~/work/project-goals" }
+```
+
+Worktrees pointing to the same root share goals, archives, ledger and locks; focus remains session-local and execution ownership still requires explicit resume. The working directory for tools and audits is unchanged. Existing goals are not moved automatically. Reload/reopen the session after changing roots; `/goal-refresh` refreshes the selected pool. `/goal-status verbose` shows the effective location. Saved goal paths remain logical `.pi/goals/...` paths within that selected pool.
+
+`hideUnfocusedPrompt: true` suppresses ordinary unfocused reminders to the model independently of `hideUnfocusedBanner`; neither changes focus or bypasses stale-checkpoint checks.
+
+Token usage shown in the dashboard is cumulative across goal turns. The model receives a separate context snapshot when Pi can supply one; unavailable context is never reported as zero. Retained snapshots are bounded and newer snapshots supersede older ones.
+
+## Diagnostics and recovery
+
+Use `/goal-status verbose` for effective settings and storage location, `/goal-status health` or `/goal-recovery` to check for problems, and `/goal-refresh` to reload saved goals and settings after external changes. `/goal-recovery repair` offers repairs after confirmation.

package/docs/agent-flow-design.md

@@ -0,0 +1,306 @@
+# pi-goal Agent Flow Design
+
+This document explains the agent flow of the `pi-goal` project: how the user
+states an objective, how the executing agent works, how the independent
+auditor verifies, and how the runtime maintains state, the ledger, the UI, and
+auto-continuation.
+
+## 1. Core mental model
+
+`pi-goal` is not another general-purpose agent; it is a pi extension. It adds a
+"long-running goal runtime" layer on top of the main coding agent: goals are
+created explicitly, go through a lifecycle, and completion is independently
+audited.
+
+The system has four roles:
+
+| Role | Responsibility |
+|---|---|
+| User | Owns intent. Starts goals, pauses/resumes/clears them, chooses focus. |
+| Executing agent | Works on the confirmed focused goal. Reports terminal outcomes via `update_goal`. |
+| Auditor agent | An independent in-memory pi agent session that checks whether a completion claim actually satisfies the goal. |
+| `pi-goal` runtime | Maintains goal state, the tool surface, prompts, the ledger, the UI widget, and auto-continuation. |
+
+Core principle:
+
+> The user owns intent; the executing agent does the work; the auditor
+> independently verifies; the runtime coordinates and records.
+
+## 2. Overall flow
+
+```text
+User command
+  -> pi-goal command handler (/goal, /sisyphus, /goal-*)
+  -> guided draft and explicit confirmation, direct creation, or focus/lifecycle state update
+  -> runtime reconciles from disk, re-computes prompts and the active tool subset
+  -> executing agent works on the focused goal
+  -> tool call / turn events update accounting and the ledger
+  -> update_goal(complete) triggers the independent auditor
+  -> approved -> goal archived at turn_end; rejected -> goal stays open
+```
+
+Five model tools are registered:
+
+| Tool | Role |
+|---|---|
+| `create_goal` | Create and focus a new goal after an explicit user request |
+| `get_goal` | Read-only snapshot of the focused goal |
+| `update_goal` | Terminal outcomes: `complete` (audited) or `blocked` (three-turn rule) |
+| `set_goal_tasks` | Define/replace the task tree (with confirmation) |
+| `update_goal_task` | Per-task status updates without stopping the turn |
+
+Lifecycle actions the model does not own (pause, resume, clear, focus, tweak,
+settings) are user-owned slash commands.
+
+## 3. Main state containers
+
+The runtime keeps:
+
+- a goal pool `goalsById: Map<goalId, GoalRecord>` reconstructed from
+  `.pi/goals/active_goal_*.md` plus compatible legacy session entries;
+- a session focus `focusedGoalId` reconstructed from branch-local
+  `pi-goal-focus` custom session entries;
+- `focusRevision` — incremented on every focus change, used to invalidate
+  pending async operations (completion, task-list confirmation) so results
+  cannot mutate a goal after the session detached from it.
+
+## 4. Persistence: goal files and ledger
+
+### 4.1 Goal files
+
+```text
+.pi/goals/active_goal_<timestamp>_<id>.md
+.pi/goals/archived/goal_<timestamp>_<id>.md
+```
+
+Each file has extension-owned metadata and a user-editable `# Goal Prompt`
+section. Before focused commands, tools, and lifecycle hooks act, the runtime
+re-reads the focused active file and reconciles lifecycle state from disk, so
+external changes win over stale memory. Session focus is never written into
+these files.
+
+### 4.2 Ledger files
+
+The ledger is one project-level append-only JSONL file
+(`.pi/goals/goal_events.jsonl`). Its 18 event types cover creation,
+tweaks, focus changes, pause/resume/block/clear, completion requests, audit
+start/result/skip, budget limits, and task-list changes. The runtime reads it
+for auditor-rejection memory and compaction summaries; it is never rewritten
+in place.
+
+## 5. Command palette: the user owns intent
+
+The curated fourteen-command palette:
+
+| Command | Behavior |
+|---|---|
+| `/goal [seed]` | Guided regular-goal drafting, questionnaire where useful, then explicit confirmation |
+| `/sisyphus [seed]` | Guided Sisyphus drafting with ordered-work constraints and explicit confirmation |
+| `/goal-direct <objective>` | Direct regular-goal creation without drafting |
+| `/sisyphus-direct <objective>` | Direct Sisyphus creation without drafting |
+| `/goal-list` | List all open goals and the current focus |
+| `/goal-status` | Read-only focused-goal summary plus other-open-goal count; append `verbose` for diagnostics or `health` for storage/runtime checks |
+| `/goal-focus` | Choose this session's focused goal |
+| `/goal-unfocus` | Detach the session without modifying the shared goal |
+| `/goal-settings` | Fully operable settings editor for all eight persisted fields |
+| `/goal-tweak <change>` | Guided, user-confirmed refinement of the focused objective and task plan |
+| `/goal-clear` | Archive the focused goal after confirmation (cancel is a durable no-op) |
+| `/goal-cancel` | Cancel the in-progress guided draft without creating a goal |
+| `/goal-pause` | Pause the focused active goal (Esc also pauses) |
+| `/goal-resume` | Resume a paused or blocked goal |
+
+## 6. Goal creation flow
+
+`/goal [seed]` and `/sisyphus [seed]` start a guided draft without changing advertised tools.
+The agent can ask questions, select a questionnaire when it adds value, and
+propose both a full objective and a task tree in a single confirmation dialog.
+Confirm creates and focuses the goal atomically; Continue Chatting retains the
+draft. `/goal-direct` and `/sisyphus-direct` are the explicit immediate paths.
+
+## 7. Tool surface and runtime gates
+
+The tool surface is fixed across execution and guided drafting:
+
+- five execution tools are advertised when tasks are enabled — `create_goal`,
+  `get_goal`, `update_goal`, `set_goal_tasks`, `update_goal_task`;
+- only the three core execution tools when tasks are disabled;
+- `goal_question`, `goal_questionnaire`, and `propose_goal_draft` stay advertised
+  in both profiles, but reject calls without an active user-started draft;
+- profile installation is idempotent; only an explicit `disableTasks` change
+  alters the tool set. Focus, status, budget, completion, audit, drafting, and
+  compaction transitions never change it;
+- ordinary pi work tools (`read`, `write`, `edit`, `bash`, ...) are never
+  touched by the extension;
+- invalid lifecycle calls are rejected by the executor with a concise
+  state-aware result (e.g. `update_goal(blocked)` from a paused goal), not by
+  hiding tools.
+
+The `tool_call` interceptor:
+
+- blocks all five execution goal tools during an active draft, and for the rest
+  of a turn whose proposal confirmed or cancelled the draft, preserving the
+  confirmation boundary without changing tool declarations;
+- blocks work tools after a stop tool has fired in the same turn (post-stop
+  guard);
+- blocks work tools when the checkpoint that triggered the turn is no longer
+  actionable (stale checkpoint guard);
+- tracks whether the turn did meaningful goal work (the empty-turn gate for
+  auto-continuation).
+
+## 8. Execution loop and auto-continue
+
+When `autoContinue` is on, the extension queues continuation prompts after
+agent turns for the focused goal only. The loop stops or pauses when:
+
+- the agent calls `update_goal(status="complete")`;
+- the agent calls `update_goal(status="blocked")`;
+- the user invokes `/goal-pause`, `/goal-clear`, or the user aborts the turn;
+- a turn ends without meaningful goal-work tool activity.
+
+Continuation prompts include a goal id so stale prompts can be detected and
+neutralized. If focus changes or the goal is archived before a queued
+checkpoint runs, the checkpoint becomes stale and cannot drive task work.
+
+## 9. Completion and the visible audit phases
+
+### 9.1 The executing agent requests completion
+
+`update_goal({status: "complete"})` has no verification-summary parameter. The
+runtime validates that the goal is in a completable status, optionally warns
+about pending tasks (`blockCompletion`), appends a `completion_requested`
+ledger event, and starts the auditor. When `settings.disabled` is true the
+auditor is skipped immediately: the flow records `audit_skipped` and completes
+through the normal deferred-completion path. Legacy persisted
+`skipAuditor: true` records are honored the same way; Escape during a running
+audit remains the explicit per-attempt user bypass.
+
+### 9.2 The audit appears in the conversation
+
+A `[GOAL AUDIT STARTED]`-style message is sent with `triggerTurn`, so the
+executing agent's turn yields to the auditor. A `pi-goal-audit-event` message
+with phase `started` is displayed, and the goal widget shows an audit progress
+spinner. Escape during the audit opens a dialog to complete without audit or
+continue working.
+
+### 9.3 The independent auditor session
+
+A separate in-memory pi session runs with a focused auditor prompt. The
+auditor receives the objective, the executor's completion claim, and goal
+metadata; it can inspect the workspace with `read`, `grep`, `find`, `ls`, and
+`bash`; and it must end with exactly one marker: `<approved/>` or
+`<disapproved/>` (an error or abort also rejects).
+
+### 9.4 The audit result appears in the conversation
+
+The result is sent as a `pi-goal-audit-event` with phase `approved` or
+`rejected`, and an `audit_result` ledger event records the verdict. A rejected
+completion leaves the goal open and the verdict is remembered so future
+prompts inject the auditor's objections.
+
+### 9.5 Archiving
+
+On approval, the goal is set complete in memory and the active file is written
+without archiving; archival is deferred to `turn_end` so the agent can see the
+auditor result first. At `turn_end` the goal is archived, a `goal_completed`
+ledger event is appended, and the session focus is cleared.
+
+## 10. Blocked, pause, and post-stop behavior
+
+- `update_goal({status: "blocked"})` records a distinct `blocked` status with
+  an agent stop reason and stops continuation. The three-consecutive-turn
+  blocker rule is prompt policy, not a persisted counter.
+- `/goal-pause` and Esc set `paused` (user-owned) with `autoContinue: false`.
+- `/goal-resume` reactivates a paused or blocked goal.
+- After any stop tool fires in a turn, subsequent tool calls in the same turn
+  are blocked except read-only inspection.
+
+## 11. Compaction and auditor-rejection memory
+
+On session compaction the runtime persists the current goal, re-arms
+accounting, and arms a deterministic post-compaction summary for the next
+agent turn. Auditor rejections are read from the ledger and injected into
+future prompts so the agent addresses them before requesting completion again.
+
+## 12. Token budgets
+
+An optional `token_budget` may be set at creation. When accounted usage
+reaches the budget, the goal transitions to a distinct `budget_limited` status
+exactly once, a `goal_budget_limited` ledger event is emitted, one-time
+wrap-up steering is injected (summarize; do not start new substantive work; do
+not claim completion unless real), and pending continuations are cancelled.
+`budget_limited` never implies completion.
+
+## 13. Module map
+
+```text
+goal.ts (thin installer)
+├─ goal-state.ts     GoalCore: state + service/runtime/accounting wiring
+├─ goal-tools.ts     registration composition only
+├─ goal-core-tools.ts create/get/update handlers + blocked and agent-pause flows
+├─ goal-completion.ts audit orchestration + completion commit
+├─ goal-task-tools.ts task structure/status handlers + tree helpers
+├─ goal-task-confirmation.ts task result boundary with neutral labels
+├─ goal-draft.ts     drafting prompt/confirmation text helpers
+├─ goal-drafting.ts  guided drafting orchestration + durable draft sessions
+├─ goal-commands.ts  fourteen-command palette
+├─ goal-events.ts    13 lifecycle event handlers
+├─ goal-widget.ts    terminal keybindings + debug helpers
+├─ goal-format.ts    pure formatting/message helpers
+├─ goal-service.ts   sole mutation boundary
+├─ goal-runtime.ts   continuation/stale-checkpoint/turn-stop
+├─ goal-accounting.ts serialized accounting + budgets
+├─ goal-policy.ts    lifecycle/task validation + reports
+├─ goal-auditor.ts   independent audit session
+├─ goal-ledger.ts    ledger reads
+├─ goal-record.ts    record types/creation/migration
+├─ goal-pool.ts      pool/focus helpers
+├─ prompts/          bounded five-tool steering prompts
+├─ storage/          goal file IO (reads + serializers)
+└─ widgets/          goal widget, notifications, escape dialog, task overlay
+```
+
+## 14. Key design trade-offs
+
+- **Five tools, user-owned lifecycle.** A small stable surface is easier to
+  prompt-bound than a large phase-dependent one; lifecycle actions are user
+  commands so the model cannot pause/resume/clear on its own.
+- **GoalService as the sole mutation boundary.** Ordering (reconcile → write →
+  ledger → memory) is enforced in one place; handlers cannot corrupt files or
+  ledger state.
+- **Auditor from actual evidence, not paperwork.** Removing the
+  verification-summary field pushes the auditor to inspect real artifacts,
+  which is a stronger completion gate.
+- **Budget exhaustion is a system transition, not completion.** The
+  `budget_limited` status stops continuation and arms wrap-up steering without
+  implying the goal is done.
+- **Disk is authoritative at operation start.** Reconciliation before each
+  focused action picks up prior external edits and prevents deleted files from
+  being resurrected.
+- **Cross-process mutations are serialized.** Each goal carries a persisted
+  monotonic `revision` (missing historical values normalize to zero). A
+  short per-goal filesystem lock (atomic create under `.pi/goals/.locks` with
+  bounded acquisition and stale-lock recovery) guards reads, and
+  `GoalService.apply` re-reads the authoritative file under the lock: a stale
+  writer receives a typed conflict carrying the current revision instead of
+  overwriting blindly. `update_goal_task` retries once only when the same task
+  and status/structure remain unchanged; `set_goal_tasks` surfaces the typed
+  conflict. Old readers keep existing data readable.
+
+## 15. Hardening and runtime follow-up
+
+This document describes the shipped behavior. The 2026-08-04 hardening plan
+([`specs/2026-08-04-goal-simplification-hardening`](../specs/2026-08-04-goal-simplification-hardening/TECH.md))
+is implemented: it addresses paused-record resurrection, operation-start
+task reconciliation, task-confirmation auditor-state coupling, budget
+validation, ledger semantics, the primary legacy runtime surface, and the
+E2E/experiment migration.
+
+The runtime follow-up
+([`2026-08-04 goal runtime follow-up`](../specs/2026-08-04-goal-runtime-follow-up/TECH.md))
+then shipped the remaining work: guided drafting restored as a transient
+user-invoked workflow (durable draft sessions, `/goal-cancel`, `/goal-status`,
+per-draft auditor selection), a fully operable settings menu, `/goal-clear`
+confirmation, neutral task-confirmation labels, failure-checked completion
+commits, per-goal revision/lock serialization with typed conflicts, the
+agent-pause outcome, untrusted `completion_summary` claims, the enforced
+experiment matrix, the runner self-check, and the Pi SDK 1.0 family upgrade.