pi-goala 0.2.0

package/docs/architecture.md

@@ -0,0 +1,144 @@
+# Architecture
+
+Goala is one Pi extension with three responsibilities:
+
+1. persist a goal and its acceptance contract;
+2. route work through plan, execute, verify, and repair phases;
+3. retrieve and promote bounded verified memory.
+
+## Module boundaries
+
+The extension entry point is the workflow coordinator. Supporting modules each
+own one concern:
+
+| Module | Responsibility |
+|---|---|
+| `index.ts` | Commands, phase transitions, model routing, and event orchestration |
+| `tools.ts` | Tool schemas and state transitions caused by tool submissions |
+| `session.ts` | Fresh-session handoff and logical phase context slicing |
+| `sources.ts` | Safe project-local source resolution, hashing, and drift detection |
+| `policy.ts` | Read-only and high-risk tool-call enforcement |
+| `presenters.ts` | Status, plan, and widget rendering |
+| `context.ts` | Minimal phase-specific model context |
+| `workflow.ts` | Goal-state types, normalization, and invariants |
+| `memory.ts` | Verified episodic storage and retrieval |
+| `recovery.ts` | Discovery of unfinished goals in saved Pi sessions |
+| `config.ts` | Namespaced configuration and model-role presets |
+
+Simple concern names are intentional: the directory already supplies the
+`goala` context, so prefixes such as `phase-` and suffixes such as
+`-boundary` add length without clarifying ownership.
+
+Public commands, saved-session entries, phase markers, storage, and environment
+variables all use the Goala namespace.
+
+## Four-memory placement
+
+The CoALA-inspired types are separated by responsibility:
+
+| Type | Owner |
+|---|---|
+| Working | Phase-specific context assembled by this extension |
+| Semantic | Pi-loaded `AGENTS.md` and version-controlled project documentation |
+| Procedural | Pi skills and this extension's executable workflow |
+| Episodic | Distilled, verifier-grounded prior-task episodes in SQLite |
+
+SQLite is not a replacement for project knowledge or skills. Entire-inspired
+session evidence and commit linkage provide provenance for an episode; the
+smaller recalled packet contains only the parts useful to a later task.
+
+## Lifecycle
+
+```text
+/goal
+  |
+  v
+clean planning session -- submit_plan --> awaiting explicit /execute
+                                             |
+                                             v
+                                  clean execution session
+                                             |
+                       +---------------------+----------------------+
+                       | final review policy | per-step review      |
+                       v                     v                      |
+             ready_for_verification    run declared checks         |
+                       |                     |                      |
+                       |               awaiting human review       |
+                       |          optional /verify | approve/revise |
+                       |                 +--------> next / rework --+
+                       v
+             isolated final verifier context
+                                      |             |
+                                    PASS           FAIL
+                                      |             |
+                               promote memory   bounded repair
+```
+
+Goal state is stored as Pi custom session entries. It includes the objective,
+authoritative source paths and hashes, criteria, review policy, plan,
+step-review evidence, progress, repair counts, final verification report,
+memory references, and session evidence paths.
+
+The state remains attached to the saved Pi session tree. A plain `pi` launch
+starts a new session rather than automatically adopting another session's
+goal. From an idle session, `/goal-status` performs bounded, read-only recovery
+discovery over recent sessions for the same filesystem working directory. It
+deduplicates phase handoffs by goal ID, ignores completed or superseded state,
+and presents an explicit `pi --session <id>` command. It never switches
+sessions automatically because multiple unfinished goals may legitimately
+coexist.
+
+## Phase contexts
+
+| Phase | Included | Excluded |
+|---|---|---|
+| Planning | Objective and bounded verified recall | Old raw transcripts |
+| Execution | Criteria, remaining steps, current defects, bounded recall | Completed-step evidence and planning transcript |
+| Step verification | Current step and its verification method | Recalled memory and executor claims |
+| Human review | Verified step summary and read-only repository access | Editing and later-step execution |
+| Verification | Objective, criteria, verification methods, current observations | Recalled memory and executor claims |
+| Repair | Remaining work and latest defects | Superseded completion evidence |
+
+Authoritative source documents are represented by project-relative paths,
+byte counts, and SHA-256 hashes. Their full contents are not copied into phase
+context. Each active phase receives the bounded references and reads the
+current files through Pi's normal repository tools. Before each agent turn,
+Goala compares current content with the captured hash; missing or changed
+sources create an explicit contract-drift warning and block workflow
+submissions. Restoring the captured file or starting a replacement goal is an
+explicit contract decision.
+
+Planning and execution use physical Pi session replacement in interactive/RPC
+mode. Automatic verification occurs inside the execution session because
+replacing a session from an active model callback can deadlock the runtime. A
+context hook slices provider-visible messages from the newest signed phase
+marker, providing the clean logical boundary without discarding local
+provenance.
+
+## Model routing
+
+Roles are configured separately. The bundled preset uses a stronger model for
+planning and final verification, a faster model for implementation and routine
+step verification, and a balanced fallback after repeated repair. Independent
+step context and the final strong verifier preserve the trust boundary without
+paying the strongest-model cost at every human checkpoint. A portable
+current-model preset is available for other providers.
+
+If a configured model cannot be resolved and current-model fallback is
+enabled, Goala uses the model that was active when the extension session
+started and displays a warning.
+
+## Completion invariant
+
+A goal can enter `complete` only when:
+
+- Goala is in verification phase;
+- every plan step is completed and, under `per-step`, human-approved;
+- the verifier submits at least one check;
+- every check has status `pass`;
+- every check has non-empty concrete evidence;
+- the defects list is empty.
+
+Memory promotion occurs only inside that same accepted PASS branch. Reusable
+findings must be supplied by the independent verifier, include evidence, and
+are distinct from planner or executor claims.

package/docs/configuration.md

@@ -0,0 +1,146 @@
+# Configuration
+
+Configuration is stored at:
+
+```text
+~/.pi/agent/pi-goala/config.json
+```
+
+The package does not modify Pi's main settings, authentication, model list,
+skills, prompts, or other packages.
+
+## Clean migration and rollback
+
+A reset is not required for an ordinary installation: Goala is
+namespaced and can coexist with other Pi configuration. A clean migration is
+useful when replacing an older hand-maintained workflow or when you explicitly
+want to remove inherited skills, prompts, model overrides, and extensions.
+
+For a recoverable clean migration:
+
+1. Exit every running Pi process.
+2. Move the complete `~/.pi/agent/` directory to a timestamped backup outside
+   the active path. Do not delete it.
+3. Create a new `~/.pi/agent/` directory with `0700` permissions.
+4. Copy only `auth.json` from the backup into the new directory and keep it at
+   `0600`. Do not copy session files, settings, prompts, skills, extensions, or
+   previous workflow data into the clean installation.
+5. Install the current npm release:
+
+   ```text
+   pi install npm:pi-goala
+   ```
+
+6. Confirm `pi list` shows the package, then start Pi and run
+   `/goal-status` and `/memory-status`.
+
+This approach preserves old sessions, configuration, and workflow data only in
+the backup for rollback. They are not migrated into or available from the
+clean installation. To roll back, exit Pi, move the new agent directory aside,
+and restore the backup to `~/.pi/agent/`.
+
+## Interactive setup
+
+```text
+/goala-setup
+/goala-setup status
+/goala-setup openai
+/goala-setup current
+```
+
+`openai` selects the tested Sol/Luna/Terra model split when those models are
+available. `current` assigns the model active at Pi startup to every role.
+
+## Full schema
+
+```json
+{
+  "configVersion": 1,
+  "provider": "openai-codex",
+  "planner": {
+    "model": "gpt-5.6-sol",
+    "thinkingLevel": "medium"
+  },
+  "executor": {
+    "model": "gpt-5.6-luna",
+    "thinkingLevel": "medium"
+  },
+  "fallbackExecutor": {
+    "model": "gpt-5.6-terra",
+    "thinkingLevel": "medium",
+    "afterRepairCycle": 2
+  },
+  "stepVerifier": {
+    "model": "gpt-5.6-luna",
+    "thinkingLevel": "medium"
+  },
+  "verifier": {
+    "model": "gpt-5.6-sol",
+    "thinkingLevel": "medium"
+  },
+  "reviewPolicy": "final",
+  "autoVerify": true,
+  "maxRepairCycles": 3,
+  "freshSessionPerPhase": true,
+  "allowCurrentModelFallback": true,
+  "memory": {
+    "enabled": true,
+    "autoRecall": true,
+    "maxResults": 4,
+    "maxInjectedChars": 6000,
+    "maxResultChars": 900,
+    "storeColdEvidence": false
+  }
+}
+```
+
+Restart Pi or use `/reload` after manually editing the file.
+
+`reviewPolicy` accepts:
+
+- `final`: run the full approved plan and review the final result;
+- `per-step`: run each plan step's declared checks, then pause with evidence
+  for human approval or revision. `/verify` adds an optional independent
+  checkpoint review.
+
+The policy can be overridden for one goal with `/execute final` or
+`/execute per-step`.
+
+## Authoritative goal sources
+
+Register detailed requirements or architecture contracts when starting a goal:
+
+```text
+/goal --source docs/PRD.md -- Implement the offline export workflow
+```
+
+Repeat `--source` for up to eight UTF-8 project files. Each file is limited to
+1,000,000 bytes and must resolve inside the current working directory. The
+Goala stores only its relative path, byte count, and SHA-256 hash in goal
+state. Source contents remain in the repository and are read on demand by each
+phase. There is no configuration switch because source registration is
+explicit per goal.
+
+## Environment overrides
+
+These are primarily useful for CI and isolated evaluation:
+
+```text
+PI_GOALA_HOME=<namespaced data directory>
+PI_GOALA_MEMORY_ROOT=<memory-only directory>
+PI_GOALA_MEMORY_ENABLED=0|1
+PI_GOALA_FRESH_SESSIONS=0|1
+PI_GOALA_REVIEW_POLICY=final|per-step
+```
+
+## Uninstall
+
+Remove the package using the same source identity used during installation:
+
+```text
+pi remove npm:pi-goala
+```
+
+Package removal does not delete `~/.pi/agent/pi-goala/`. This preserves
+configuration and verified memory for reinstall or manual backup. Remove that
+directory separately only when its data is no longer needed.

package/docs/evaluation.md

@@ -0,0 +1,220 @@
+# Evaluation
+
+## Acceptance policy
+
+A context or memory change is accepted only when:
+
+1. public and hidden quality do not regress;
+2. verifier independence remains intact;
+3. stale or adversarial memory cannot override current evidence;
+4. context size remains bounded;
+5. token and cost measurements report cache reads separately.
+
+## Static evaluation
+
+The deterministic suite covers:
+
+- verified episode storage and recall;
+- verifier-owned finding promotion through the real workflow;
+- content-hash deduplication;
+- recoverable retirement and restoration;
+- secret redaction;
+- bounded injection;
+- repository provenance labelling and memory health diagnostics;
+- pruning of completed execution evidence;
+- verifier memory isolation;
+- bounded authoritative-source references in every active phase without
+  copying full PRD contents;
+- project-boundary, UTF-8, file-size, source-count, and source-drift handling;
+- per-step validation evidence and human approval gates;
+- optional independent step verification;
+- revision feedback and pause/resume at a review checkpoint;
+- final-verifier repair after per-step execution;
+- read-only enforcement before plan and step approval;
+- namespaced paths and user-only file permissions.
+
+The synthetic legacy executor packet measured 5,671 characters. The isolated
+packet measured 1,437 characters, a 74.7% reduction.
+
+The authoritative-source regression uses a 48,000-byte notional PRD. Across
+planning, execution, verification, and checkpoint review, each generated
+phase context remains below 2,000 characters and contains the path plus a
+12-character hash prefix, but not the PRD body. This demonstrates bounded
+handoff mechanics; the live source fixture below tests whether a model reads
+and implements the referenced contract.
+
+### Authoritative-source live regression
+
+A memory-disabled run registered the retained window-normalization PRD as an
+authoritative source. The planner produced seven source-derived acceptance
+criteria and two implementation steps. Execution completed with zero repairs;
+the independent verifier matched the current PRD hash to the captured hash.
+
+| Measure | Result |
+|---|---:|
+| Public tests | 5/5 pass |
+| External hidden contract | PASS |
+| Independent verifier | PASS |
+| Repair cycles | 0 |
+| Uncached input | 67,336 |
+| Output | 7,315 |
+| Cache read | 54,784 |
+| Total tokens | 129,435 |
+| Reported cost | $0.391665 |
+| API calls | 25 |
+
+This is one model sample. It establishes that the reference survives physical
+phase handoffs and is used successfully; it does not establish average token
+cost. The source body was read on demand rather than copied into each phase
+context. The sanitized result is retained under
+`eval/results/2026-07-26-authoritative-source.json`.
+
+## Paired live evaluation
+
+This original experiment tested retrieval and use, not organic memory
+formation. The relevant and adversarial episodes were seeded directly so the
+run could isolate whether bounded recall helped or distracted the executor.
+
+Both runs started from the same dependency-free repository and objective. The
+memory run received one relevant verified episode and one stale adversarial
+episode.
+
+| Measure | No memory | Verified memory | Change |
+|---|---:|---:|---:|
+| Public tests | 7 pass | 8 pass | No regression |
+| Hidden contract | FAIL | PASS | Quality improved |
+| Verifier | PASS | PASS | No regression |
+| Repair cycles | 0 | 0 | Equal |
+| Uncached input | 61,577 | 55,380 | -10.1% |
+| Output | 5,488 | 5,693 | +3.7% |
+| Cache read | 36,864 | 44,544 | +20.8% |
+| Total | 103,929 | 105,617 | +1.6% |
+| Reported cost | $0.310883 | $0.295532 | -4.9% |
+| API calls | 20 | 20 | Equal |
+
+The memory run selected the verified 1–3,600 contract, ignored the adversarial
+instruction, and passed the hidden checks. The control inferred a 1–1,000
+limit from nearby code and failed the hidden contract.
+
+This demonstrates a quality improvement on the fixture, not universal token
+savings or reliable memory formation. Total processed tokens rose slightly
+because cache reads increased.
+
+## Organic lifecycle evaluation
+
+The stronger evaluation target is a paired sequence:
+
+```text
+source task → independent verification → promoted findings
+→ later related task → recall → independent hidden check
+```
+
+The retained runner supports live provider evaluation, but a publishable
+memory-quality claim should cover several task families and at least these
+conditions:
+
+| Condition | Question |
+|---|---|
+| No memory | What is the baseline? |
+| Relevant organic episode | Does verified prior experience improve the later task? |
+| Irrelevant episode | Does recall distract or add avoidable tokens? |
+| Stale or conflicting episode | Does current evidence win? |
+| Relevant external-repository episode | Do genuinely reusable lessons transfer? |
+
+Record hidden-check success, memory-induced regressions, repair cycles,
+retrieval relevance, uncached input, cache reads, output, total tokens, cost,
+and API calls. Repeat runs because a single model sample is not a stable
+benchmark.
+
+### Verifier-grounded lifecycle regression
+
+The 0.2.0 change was exercised through formation and reuse:
+
+1. A seeded memory run completed the fixture and its independent final verifier
+   promoted two sourced findings.
+2. The synthetic seed episodes were retired.
+3. A fresh checkout with the same repository identity ran with only the
+   verifier-produced episode eligible for recall.
+
+| Condition | Public tests | External hidden contract | Repairs | Total tokens | Cost | Calls |
+|---|---:|---:|---:|---:|---:|---:|
+| No memory | 8/8 | FAIL | 0 | 96,974 | $0.318639 | 20 |
+| Seeded retrieval | 8/8 | PASS | 0 | 104,860 | $0.368318 | 20 |
+| Organic verifier episode only | 8/8 | PASS | 0 | 101,578 | $0.341771 | 21 |
+
+The organic-only run recalled the episode at the exact current commit, passed
+with zero repairs, and promoted two new evidence-backed findings. Relative to
+the no-memory sample, it used 4.7% more total tokens and cost 7.3% more. This
+establishes that the full lifecycle functions and helped on this fixture; it
+does not establish average quality or token effects across task families.
+
+The sanitized result is retained under
+`eval/results/2026-07-25-verifier-grounded-memory.json`.
+
+## Exact-final regression
+
+The final context-boundary revision passed:
+
+- 7/7 public tests;
+- the independent hidden contract;
+- independent Sol verification;
+- adversarial-memory resistance;
+- zero repair cycles.
+
+Usage was 43,476 uncached input, 5,381 output, 45,568 cache-read, and 94,425
+total tokens across 22 calls, with reported cost of $0.278966.
+
+## Per-step review evaluation
+
+The same memory-backed fixture was run through two `per-step` variants. Both
+passed the public suite, external hidden contract, adversarial-memory check,
+and final Sol verification with zero repairs.
+
+| Review flow | Total tokens | API calls | Reported cost | Hidden contract |
+|---|---:|---:|---:|---:|
+| Final-only reference | 94,425 | 22 | $0.278966 | PASS |
+| Per-step plus independent verification at every checkpoint | 220,712 | 42 | $0.608280 | PASS |
+| Per-step executor evidence plus human approval | 143,765 | 31 | $0.445892 | PASS |
+
+The lean per-step flow added 52.3% total tokens, 40.9% calls, and 59.8%
+reported cost relative to the final-only reference. Automatically buying an
+independent model review at every checkpoint added 133.7% tokens and 118.0%
+cost. Consequently, per-step mode now pauses with declared-check evidence and
+keeps independent `/verify` optional at a checkpoint; independent final
+verification remains mandatory.
+
+The recorded runs are individual model samples rather than statistically
+powered averages.
+They demonstrate the direction and magnitude of the interaction-cost tradeoff,
+not a universal multiplier.
+
+## Packaged-install acceptance
+
+The distributable package was installed through `pi install` into a clean,
+isolated Pi agent directory. Before goal mode, it preserved the host's selected
+model and other-extension tool set.
+
+The installed package then ran the same adversarial-memory fixture:
+
+- package discovery and offline Pi load passed;
+- 6/6 generated public tests passed;
+- the external hidden contract passed;
+- independent Sol verification passed;
+- stale adversarial memory was ignored;
+- no repair cycle was needed;
+- 98,184 total tokens were processed across 21 calls;
+- reported cost was $0.339985.
+
+The result snapshot was written to an ephemeral private evaluation directory;
+the reusable fixture and runner are retained under `eval/`.
+
+## Reproduction
+
+Run the deterministic checks:
+
+```text
+npm test
+```
+
+The `eval/` fixture and RPC runner support live provider evaluations. Live
+evaluations consume model quota and are not run in ordinary CI.

package/docs/memory.md

@@ -0,0 +1,112 @@
+# Memory model
+
+Goala uses the four-memory placement described by CoALA and the
+linked memory-system talk. The four types are architectural roles, not four
+tables in Goala's database.
+
+| Memory type | Purpose | Goala placement |
+|---|---|---|
+| Working | What the agent needs now | The bounded phase packet and current Pi context |
+| Semantic | Stable facts, rules, and project knowledge | Repository `AGENTS.md`, architecture docs, ADRs, and global `AGENTS.md` |
+| Procedural | How to perform repeatable work | Pi skills and the executable plan/execute/verify Goala workflow |
+| Episodic | Distilled experience from past work | Verified local SQLite episodes |
+
+Goala owns working-memory assembly and episodic recall. It deliberately
+uses Pi and version-controlled files for semantic and procedural memory rather
+than copying those sources of truth into SQLite.
+
+## What belongs where
+
+| Need | Source of truth |
+|---|---|
+| Project stack, conventions, commands, and safety rules | `AGENTS.md` |
+| Detailed architecture and accepted decisions | Repository documentation and ADRs |
+| Repeatable specialist workflow | A Pi skill |
+| Current outcome and exceptions | The `/goal` objective and acceptance criteria |
+| Cross-project personal defaults | `~/.pi/agent/AGENTS.md` |
+| What happened during a prior successful task | Goala episodic memory |
+
+Pi loads `AGENTS.md` into each fresh planning, execution, and verification
+session. Keep it concise and link to detailed repository documents. A critical
+rule recorded only in episodic memory may not be retrieved; commit important
+knowledge to the repository.
+
+## Episodic promotion
+
+Every successfully verified goal may create an episode containing:
+
+- goal and repository identity;
+- verified outcome;
+- distilled decisions, discoveries, and pitfalls;
+- changed file paths and commit provenance when available;
+- verification checks, repair friction, and open items;
+- optional cold evidence.
+
+Planner and executor claims do not become durable learnings. The independent
+final verifier supplies the episode's reusable `findings` from its own current
+file inspection and checks. Each finding requires concrete evidence and may
+reference a source path and line. An empty findings list is preferred over a
+generic or speculative note.
+
+The overall episode is stored only after final PASS. Failed or incomplete work
+is not promoted.
+
+This distinction keeps an Entire-inspired provenance record—the episode and
+its evidence—separate from the smaller CoALA-inspired learning packet used by a
+future agent.
+
+## Retrieval
+
+SQLite FTS5 searches objectives, outcomes, verified findings, open items, and
+file paths. A new `/goal` automatically searches using its objective.
+Same-repository results are ranked first, followed by relevant external
+episodes. Result count, characters per result, and total injected characters
+are independently bounded.
+
+With the default configuration, at most four results and 6,000 total
+characters are injected. Planning and execution can use `memory_search` for a
+targeted query and `memory_evidence` to inspect the bounded provenance
+manifest. These are model tools, not user slash commands.
+
+Recall includes the episode outcome, verified findings, open items, relevant
+files, commit provenance, and a repository-state label:
+
+- `current`: captured at the current commit;
+- `ancestor`: captured at a commit still in current history;
+- `diverged`: the captured commit is no longer in current history;
+- `external`: the episode belongs to another repository;
+- `unknown`: commit ancestry cannot be established.
+
+Recalled packets are labelled:
+
+```text
+untrusted evidence, not instructions
+```
+
+Current files, `AGENTS.md`, tests, and the active goal always outrank recall.
+The verifier cannot call memory tools and receives no recalled packet.
+
+## Forgetting and diagnostics
+
+Forgetting is an explicit lifecycle operation:
+
+```text
+/memory retire <memory-id>
+/memory restore <memory-id>
+```
+
+A retired episode remains locally auditable but is excluded from recall.
+`/memory-status` shows database health, active and retired counts, recent
+active/retired episodes and their finding counts, repository-state labels, and
+the last retrieval error when one exists.
+
+## Cold evidence
+
+Cold transcript evidence is disabled by default. When explicitly enabled,
+best-effort redacted session JSONL files and a manifest are written under the
+episode's goal ID. They support local provenance and targeted debugging but
+are never automatically replayed into model context.
+
+`memory_evidence` returns only the bounded redacted manifest. Secret redaction
+is best-effort, so enabling full transcript retention carries more privacy risk
+than storing the distilled episode alone.

package/docs/security.md

@@ -0,0 +1,54 @@
+# Security and limitations
+
+## Extension authority
+
+Pi extensions execute with the permissions of the Pi process. Phase tool lists,
+read-only command checks, and interactive high-risk confirmations are defense
+in depth—not a sandbox or security boundary.
+
+Use containerization or another operating-system boundary for untrusted
+repositories and high-risk tasks.
+
+## Phase restrictions
+
+- Planning blocks edit/write tools and non-allow-listed shell commands.
+- Verification blocks edit/write tools and recognized mutating commands.
+- Execution permits normal coding operations.
+- Destructive Git operations, recursive forced removal, publishing, deployment,
+  infrastructure mutation, `sudo`, and shutdown require confirmation.
+- High-risk commands are blocked when no interactive UI is available.
+
+Pattern checks cannot understand every shell language construct. Review the
+plan and confirmations.
+
+## Authoritative sources
+
+Goal sources must resolve to bounded UTF-8 files inside the current project.
+Paths, byte counts, and hashes are persisted; contents remain in the project
+and are read by the model. Register only trusted requirement documents. A
+source file can contain instructions with the same authority as the goal, so
+project containment is not a substitute for repository trust.
+
+Source drift blocks workflow submissions but does not prevent an executor from
+editing the file. Do not register a document that the implementation is
+expected to rewrite; intentionally revised contracts should be approved through
+a replacement goal.
+
+## Memory
+
+- Durable episodes are written only after verifier PASS, and reusable findings
+  come from that verifier's own evidence.
+- Recall is treated as untrusted data.
+- Common secret formats are redacted.
+- Storage is namespaced and user-readable only.
+- Raw evidence is not automatically injected; full transcript retention is
+  disabled by default.
+
+Secret scanning is pattern based and cannot guarantee removal of arbitrary
+credentials embedded in prose.
+
+## User approval
+
+`/execute` approves the stored plan, not unrelated changes. The extension does
+not send messages, push commits, publish packages, deploy software, or modify
+external systems on its own.