pi-memory-evolution 0.2.0

package/docs/progress-pipeline.md

@@ -0,0 +1,188 @@
+# Progress pipeline follow-up
+
+This **unreleased 0.2.0** follow-up fixes reproduced capture/nomination failures after
+`a3c5943`. It keeps schema 5, ordinary recall's relevance/identity gates, automatic model
+selection/authentication, and the existing transactional write boundary.
+
+## Reproduced failure chain
+
+A read-only investigation found a stale project-state claim absent from all five saved
+progress target lists in the diagnostic snapshot; all five corresponding model events
+had zero changed records. The model could not update an ID it never received. `done`
+was processing status, not proof of learning.
+
+Replay of the tool-heavy development session showed:
+
+1. A long implementation run ended with an assistant error, so no progress source was
+   captured despite completed tool operations.
+2. In its successful continuation, a 64-entry context window retained only “continue”.
+   The last-eight-unique-paths policy also dropped the repository root. No targets meant
+   no source/job, even though a full test result existed.
+3. In the later commit/push/restart turn, only the last eight tool results survived;
+   restart inspection displaced the real commit/push result.
+4. Reusing answer retrieval for update nomination required an exact absolute repository
+   path. A project-state claim containing only its bare repository name could not qualify.
+   Per-path top-2 and answer redundancy gates further restricted update opportunities.
+5. The unmodified state was less than one day old. Its freshness factor was about 0.914,
+   so time-based decay did not exclude it. Age is not evidence of task completion.
+6. The user's explicit three-part requirements statement did not match the learning cue
+   regex and no compaction occurred, so it was not captured as a user statement.
+
+This does not prove every old clause was false. Test completion and a commit do not imply
+full product acceptance; updates must preserve unverified or still-pending clauses.
+
+## User context and natural learning
+
+The public active-branch context facade remains the only context source. A bounded scan
+now considers up to 4096 entries and 4096 messages, retaining at most six sanitized user
+texts of 2048 bytes each. Repeated consecutive topic-less continuations share a slot.
+Reset and unknown-topic barriers are kept, not replaced by an older successful topic.
+Assistant/tool text, raw compaction summaries, injected digests and slash commands do not
+supply user topics. Retained user tails remain supported. No full-session archive replay,
+cross-branch traversal or persistent topic cache was introduced.
+
+`memory/learning.ts` distinguishes explicit cues and natural declarations such as:
+
+- 我比较在意的三大功能……这些你觉得做得怎么样？
+- 我们的核心需求是……
+- 我希望系统每次都能自动……
+- 我喜欢茶。
+- Our priorities are …
+- Our project must …
+
+A statement may precede a question seeking feedback. A plain recall question, quoted
+example, vague continuation or one-off execution request is not a new durable requirement.
+This is conservative pattern-based intent recognition, not universal language understanding.
+The active model still extracts provisional claims and may return no update.
+
+A mixed statement/work turn can capture a separate user source and progress source.
+Their model calls use the serial queue and retain separate write authority: tool output
+cannot create preferences, and a user request is not proof an operation succeeded. This
+can cost two background calls rather than the old single cue call that discarded progress.
+Source idempotency and existing retry caps still apply.
+
+## Evidence selection and interruptions
+
+The progress inspector considers only the current user turn, with at most 4096 trailing
+messages. It requires linked call/result IDs, a work request and at least one recognized
+work operation. Allowed observation tool names are bash/write/edit/read/grep/find/ls;
+unknown/custom tools are not automatically trusted as work observations.
+
+Operation classes prioritize evidence instead of blindly taking the newest eight:
+
+| Priority | Examples |
+|---|---|
+| 5 | git commit/push/merge/rebase/cherry-pick |
+| 4 | test/build/process runners; git status/log/show/diff/ls-remote |
+| 3 | file edits/writes and recognized mutation/deployment commands |
+| 0 | supporting inspection |
+
+The priority is a retention hint, not a success/verification classifier. Git arguments,
+Python/Node scripts or exit code alone do not prove a particular task completed. The
+model must inspect the actual operation/output, failures and qualifications. Ties favor
+newer observations; the chosen set is restored to chronological order for the model.
+The last eight most important observations fit within a 28,000-byte JSON budget; budget
+pressure removes lower-priority observations first. Each stored operation is at most
+1024 bytes, output at most 2048 bytes, with head/tail previews and redaction. Request/report
+remain bounded. The payload exposes omitted counts and scan limits, not an illusion of
+complete evidence. More than eight important distinct outcomes can still be omitted.
+
+`completion` is either `completed` or `interrupted`. Error/aborted final assistant responses
+retain already observed tool operations but omit the assistant report. This never certifies
+the whole work item as finished. A request, unmatched result, unfinished tool-use response
+or assistant-only report cannot substitute for observed work. Captures made while the
+foreground signal is cancelled remain eligible for existing automatic recovery; they do
+not require another compaction or a manual evolve command.
+
+`memory_recall`/other internal memory tools and operation arguments referencing the owned
+state directory are excluded. A mixed shell command mentioning that directory may be
+conservatively omitted rather than feeding the extension's own records back as independent
+corroboration. This is not a universal detector of indirect self-reference through renamed
+files or custom tools.
+
+There is **no new per-tool disk journal**. Hard kills before `agent_end`, work outside the
+bounded scan, lost tool-result pairs, unsupported commands and missing retained context
+remain limitations. Extending those guarantees requires a separate persistence design,
+not calling an interrupted task complete.
+
+## Operation resources and update nomination
+
+A small non-executing shell lexer extracts hints from explicit `cd` and `git -C`, including
+quoted paths and simple environment prefixes. It does not treat quoted semicolons or
+heredoc source bodies as independent commands. Dynamic paths/substitutions/globs and
+unsupported shell syntax lose hints rather than being executed or guessed.
+
+File operations can discover a real checkout root by walking parent `.git` markers
+without running git. Operation resources come from arguments, not output or the current
+cwd alone. At most 16 resources are retained, in operation-priority order; up to eight
+complete paths of at most 512 bytes each are included in the model payload as host hints.
+Longer paths can still participate locally, but are not truncated into a fictional model
+resource path.
+
+`memory/progress-targets.ts` is separate from question-answer retrieval:
+
+- Candidates are existing project states in the capture origin, excluding pinned,
+  forgotten, conflicted or explicitly incorrect records. Expired states remain eligible
+  for fresh evidence.
+- Operation resource paths or explicit bare project names provide subject hints; a
+  generic cwd/origin is not authority. Distinct absolute resources with the same basename
+  cannot qualify by falling back to generic commit/push words.
+- User-topic matches are a separate fallback, not tool-output-derived subject inference.
+- Pending states receive nomination priority over historical completed notes.
+- Up to eight IDs are nominated without per-path top-2, answer deduplication or an
+  answer-relative score cutoff. Ordinary recall's path and topic gates are unchanged.
+
+Current nomination scores are resource path 60 / explicit project name 50, plus two per
+matched user feature (up to eight), plus 20 for recognizable pending state wording. They
+are deterministic candidate heuristics, not learned confidence. Oldest evidence/ID break
+ties. Eight candidates are still a cap; large/multi-project tasks may need additional
+observations and cannot be assumed fully updated in one pass.
+
+The model still must identify the same subject/fact and use exact `replaces` IDs. Store
+checks still enforce candidate authority, source time, generation, pinning and origin.
+A nominated resource is not proof of completion. New preferences/facts from progress are
+rejected, and unsupported compound clauses must remain unchanged.
+
+## Diagnostics and activation
+
+`/memory learning` shows a bounded, sanitized transient capture/nomination snapshot:
+
+- natural/explicit learning intent and number of captured user statements;
+- no-work-request/no-work-observation/unfinished-response versus observed work;
+- scan limit, linked/ignored/retained/omitted observation counts and completion type;
+- no-update-targets, already-captured or progress-captured;
+- operation resources, selected IDs and candidate reasons, without memory bodies.
+
+It also shows recent actual model transaction changed-record counts. `/memory status`
+includes those persistent outcomes and explicitly says `done` means processed/retired,
+not necessarily learned. Zero changes remain distinguishable from a provider failure.
+Diagnostics do not persist raw provider responses or claim to know why the model chose
+not to change a fact. User feedback and aliases are not inferred from lookup frequency.
+
+No schema migration or old-record rewrite is needed. Reload/restart activates the new
+code. Updating alone does not reopen completed jobs, replay old transcripts, backfill
+previously missed requirements or invent completed states. New observations/statements
+and compaction use the repaired pipeline. Back up state before version changes as usual.
+
+## Validation
+
+- **215 passing tests**, strict typecheck and package inspection via `npm run check`.
+- Synthetic runtime tests cover long work/continuation, early commit/test preservation,
+  interruptions, cancelled foreground recovery, operation identity, ambiguous paths,
+  same-origin/pin/lifecycle boundaries, natural requirements, separate mixed-source
+  authority, replay idempotency, JSON expansion budgets and zero-change diagnostics.
+- Real installed Pi/Bun with a loopback fake model performs an actual temporary Git
+  commit and failed push followed by **12** diagnostic tool results. The early result
+  reaches the model, the bare-project pending state is nominated and updated, and the
+  next provider payload contains the new partial state with full acceptance still open.
+  A natural priorities statement also learns without an explicit remember cue. Existing
+  recall/tool/feedback/recovery and model/auth tests remain enabled.
+- Read-only replay of three relevant real-session turns (interrupted implementation,
+  successful continuation, commit/push/restart) now nominates both previously missed
+  stale states. The continuation retains test counts; the commit turn retains the actual
+  commit result. The connection reported `total_changes() = 0`.
+
+The real-data replay exercises host selection only, not a paid model consolidation or
+production update. It does not claim the historical records are already corrected. The
+real-Pi update test uses synthetic data and a fake model, not a multi-day natural-language
+accuracy benchmark. See [design.md](design.md) and [core-quality.md](core-quality.md).

package/docs/quality-validation.md

@@ -0,0 +1,85 @@
+# Recall and progress quality follow-up
+
+This follows `f6599d0` (global cross-session recall), not the earlier directory-isolation
+review. Version 0.2.0 remains unreleased. Validation was run on Node 26.8.1 and the
+installed Pi 0.85 standalone Bun host.
+
+## Three causes and changes
+
+1. **Weak secondary recall:** partial CJK fragments and repository-name components could
+   qualify unrelated records. Raw overlap lacked enough query coverage and relative
+   relevance filtering. Retrieval now uses words/concepts, exact literals, document
+   frequency, coverage and redundant-facet filtering. Body/alias/origin-identifier field
+   factors are 1/0.8/0.2. Source IDs/current cwd have no authority bonus. Generic internal
+   `scope` fields are not treated as cross-context semantics: doing so distorted frequency
+   weights and could promote storage-directory facts over a cross-session preference.
+2. **Stale progress:** ordinary work turns did not enter the cue/compaction-only evolution
+   loop. Completed work can now supply linked tool observations, including failures,
+   targeting at most 8 existing same-origin project states. Expired states can be updated
+   with fresh evidence, but forgotten/conflicted/pinned states cannot. Explicit operation
+   paths are not crowded out by generic task words. Store checks prevent even accidentally
+   widened candidates from relabeling facts as project progress.
+3. **Cross-language misses:** literal matching could not connect an English question to
+   the Chinese preference. A bounded bilingual concept map supports existing records;
+   optional model-generated bilingual aliases extend matching without recall-time model
+   calls. Aliases are validated, persisted, copied defensively and undoable. Alias-only
+   changes do not refresh evidence dates; correction clears old aliases. Excerpts apply
+   the same literal/prose boundary, rather than locating a topic word inside an earlier
+   filename and omitting the actual relevant passage.
+
+The detailed formula, caps, update restrictions and migration contract are in
+[design.md](design.md). No project files/configuration are modified by memory evolution.
+
+## Validation
+
+- **122/122 tests**, strict TypeScript checking, and package dry-run inspection.
+- Runtime coverage: **100% lines / 91.44% branches / 98.68% functions**. Coverage is not
+  a correctness proof, and host-specific behavior also needs the real-Pi check below.
+- Real Pi RPC tests passed repeatedly using fresh processes, separate working directories,
+  a shared temporary memory database and a loopback fake model. They verify active-model/
+  auth reuse, cross-session recall, contextual continuation, topic changes, Chinese queries,
+  learned aliases, provenance, forget and absence of approval prompts.
+- The real-host test also performs a real local Git commit in a temporary repository,
+  followed by a push that fails because no remote exists. Actual tool events reach the
+  progress model input. The fake model replaces “not committed or pushed” with “commit
+  created; push pending”; the next turn receives the updated state. Three memory-model
+  calls are observed: two explicit learning inputs and one work observation.
+- Schema-2-to-3 upgrade tests preserve records/history/dates. Malformed aliases/targets,
+  invalid model updates, forgetting queued targets and manual correction are covered.
+- One synthetic 600-summary/1,800-record sample: capture 662 ms, reopen 1 ms, cold/warm
+  recall 196/99 ms. Segmentation is memoized only within a query for repeated text/origins;
+  this is a local timing sample, not a large-corpus performance guarantee.
+
+## Real-data replay, separately read-only
+
+A direct SQLite read-only connection (`query_only`, no `MemoryStore` construction) read
+146 existing records. Nine query/context cases passed; the connection reported zero
+changes and the existing schema marker stayed at 2. No migration, correction, deletion,
+model evolution or paid call was triggered by this replay. The active Pi session may
+independently capture new memories; these counts are a snapshot, not a frozen fixture.
+
+- The Chinese project-boundary question selected the actual cross-session preference.
+- The equivalent English question ranked that preference first, with a relevant provenance
+  qualification second; the weak storage-directory fact was no longer selected.
+- The reload/injection question selected two relevant rules, not old CI/setup filler.
+- The model/auth question retrieved corresponding implementation/reuse context.
+- Context-free continuation and unrelated networking topics were empty. A memory-topic
+  continuation recalled the preference; a later topic switch did not revive it.
+
+## Limits and activation
+
+These checks establish orchestration and bounded regression cases, not general live-model
+accuracy. Tool results/reports and aliases remain untrusted evidence; generated states
+are provisional. A quoted command is not execution, and a successful commit/test is not
+proof of a successful push. The model can still make semantic mistakes.
+
+The vocabulary is not universal translation; corpus-sensitive thresholds can miss useful
+results. Cross-origin semantic identity is not automatically resolved. Upgrading does not
+invent completion for existing stale entries or replay old tool transcripts. New eligible
+observations/compactions can update tracked progress; exact-ID correction remains available.
+
+The local installation references the checkout. Back up with Pi stopped before schema
+upgrade, then reload/restart all instances sharing the database. Status should report
+`SQLite ok (schema 3)` and global topic-based recall. Older builds require a matching
+backup for rollback; do not manually downgrade the schema marker. No npm/tag release or
+live paid-provider/multi-day TUI validation was performed.

package/docs/review-0.2.md

@@ -0,0 +1,82 @@
+# Follow-up review of memory evolution 0.2
+
+**Historical implementation review at `038de65`.** Its directory-scoped recall assumption
+was subsequently identified as a requirements error: memory must follow the conversation,
+not the working directory. Current behavior is documented in [design.md](design.md):
+all-origin recall, recent-user topic context, visible provenance and conservative writes.
+The test counts below describe that earlier review, not the current test suite.
+
+Baseline: `9c84010` on `main`. Scope: all implementation modules, tests, the real-Pi
+smoke script, package metadata and documentation. This review keeps automatic memory
+updates, Pi's active model/authentication and the no-tools/no-approval boundary.
+
+## Reproduced issues and fixes
+
+The first nine isolated regression cases all failed against the baseline before fixes.
+Additional tests were added while inspecting lifecycle sequences and host contracts.
+
+| Area | Defect | Fix |
+|---|---|---|
+| Privacy | Removing controls after matching could assemble an unchecked `password` label. Multiline quoted/JSON values and indented YAML secrets leaked past line-only matching. | Normalize controls first; suppress quoted values and indented continuation blocks before capture, model submission and display. |
+| Markdown extraction | Inner triple backticks could close a four-backtick fence. Bold stripping changed recursive globs, including globs inside code spans. Recognized nested headings caused later progress siblings to disappear. | Match fence character/length, protect code spans, only remove simple bold labels, and maintain a heading stack. |
+| Identity and scope | Colon-concatenated scope/kind/content could collide for valid colon-containing paths. An undocumented `*` scope was included in every scoped read. | Hash a JSON tuple for new IDs and use exact scope lookup. Existing IDs remain valid. |
+| Forget/retry | Forget retired only the first parent; other pending sources repeating the same fact could still feed a model and relearn a paraphrase. | Retire known repeating pending/failed sources, including formatted claims beyond the normal ingestion quota. Keep the current valid replacement transaction's source intact. |
+| Legacy migration | Parent correction erased unchanged children; earlier child edits could prevent later corrected parents from deriving new facts. Corrected legacy claims lost old-content suppression when adopted. | Preserve unchanged children, distinguish newer parent corrections from obsolete child content, and carry suppression hashes through adoption. |
+| Undo/integrity | A structurally corrupted before/after pair could write an unrelated record during undo. Indexed identity/hash and source job errors were incompletely checked; unsupported schemas could receive DDL before rejection. | Validate paired/unique IDs, record metadata and indexed values; validate sources/history in status; reject unsupported versions before DDL. |
+| Batch deduplication | The same content with different kinds could be inserted twice within one local/model batch. | Deduplicate staged claims by exact content as well as persisted records. |
+| Model provenance | Reading the live `ctx.model` again after awaiting completion could label an old response with the newly selected model or throw after context invalidation. | Capture the model and its identity before the call. |
+| Async lifecycle/UI | A throwing context getter outside the queue's `try` could poison later work and shutdown. Notification failure could masquerade as rollback after a successful commit. Commands could reopen storage after shutdown. | Bound the entire queued task, isolate notifications from commits, retain truthful skipped/failed outcomes, and stop commands after shutdown. |
+| Inspection commands | Only 20 unpaginated records were accessible; older legacy imports could not be reached for adoption. `show` omitted useful provenance. | Paginated current/all/legacy lists with stable ordering; `show` includes source and timestamps. Truncated previews are marked. |
+| Excerpts | English sentences were not separated, and a long matching sentence could be clipped before its actual match. Tiny byte budgets could be exceeded by an ellipsis. | Sentence-aware and match-centered excerpts, code-point-safe clipping, and explicit tiny-budget handling. |
+| Evidence dates | Pin/unpin, adoption and undo could make old project-state evidence appear fresh for another seven days. | Preserve or restore the prior evidence date; retain operation time separately in event history. |
+| Smoke harness | Spawn failure and early process exit were not handled cleanly; cleanup could finish before the child exited. | Handle process/stdin errors, await close with bounded termination, and clean temporary state on failure. |
+
+The wildcard case requires such a row to exist; there is no public command creating
+one. The unsafe undo case requires corrupted/edited local history, not ordinary model
+JSON. Neither is evidence that production data was attacked or overwritten.
+
+## Validation
+
+- **88/88 tests passed**, including a deterministic 150-step mixed lifecycle sequence.
+- Strict TypeScript check passed.
+- Node coverage: **100% lines, 90.28% branches, 98.25% functions**. Coverage alone is not
+  a correctness guarantee; the baseline's high coverage did not catch these state-order bugs.
+- Four real Node processes concurrently writing SQLite remain covered.
+- Real Pi 0.85/Bun with a loopback fake OpenAI-compatible endpoint verified default-model
+  and authentication reuse, two automatic updates, recall injection, removal of the digest
+  after `/memory forget`, integrity checks and absence of approval dialogs.
+- A nonexistent Pi executable fails without leaving new temporary state or a live server.
+- Packaging is checked using `npm pack --dry-run`; tests and scripts are not runtime files.
+- Synthetic performance sample: 600 summaries / 1,800 claims captured in about 1.05 s;
+  reopening about 2 ms; cold/warm recall about 169/69 ms. These are local observations,
+  not cross-machine benchmarks or a guaranteed performance budget.
+
+All tests use temporary state and synthetic inputs. No paid model call, production-state
+migration, cleanup or reset was performed as part of the validation.
+
+Main regression files (links refer to a Git checkout; tests/scripts are not shipped in
+an npm tarball):
+Tests and maintenance scripts live in the Git checkout, not the runtime tarball:
+
+- [State/privacy/parser regressions](https://github.com/btnalit/pi-memory-evolution/blob/main/src/memory/review-regressions.test.ts)
+- [Pi lifecycle and command tests](https://github.com/btnalit/pi-memory-evolution/blob/main/src/index.test.ts)
+- [Adapter tests](https://github.com/btnalit/pi-memory-evolution/blob/main/src/adapter/pi-api.test.ts)
+- [Retriever tests](https://github.com/btnalit/pi-memory-evolution/blob/main/src/memory/retriever.test.ts)
+- [Real-Pi smoke script](https://github.com/btnalit/pi-memory-evolution/blob/main/scripts/test-pi.mjs)
+
+## Remaining boundaries
+
+- Semantic model accuracy, arbitrary paraphrase equivalence and exhaustive secret
+  detection are not guaranteed. Inferred claims remain provisional.
+- Suppression conservatively skips an entire known repeating source's pending model
+  pass. Unrelated local claims remain, but unlearned prose may need a new explicit source.
+- Forget/undo is logical, not secure erasure. Previous files/history are preserved.
+- Migration fixes apply to new imports; completed imports are not replayed and previously
+  discarded revision information is not automatically reconstructed.
+- Structural checks are not authentication of all well-formed local database edits.
+- No live-provider quality evaluation, multi-day TUI trial or minimum-Node-version matrix
+  was run. Local validation used Node 26.8.1 and the real Pi 0.85 standalone binary.
+- History retention/export and periodic backlog draining remain outside this small design.
+
+See [README.md](../README.md) for current commands and recovery procedures, and
+[design.md](design.md) for runtime invariants.

package/docs/testing.md

@@ -0,0 +1,102 @@
+# Testing
+
+Run these commands from a Git checkout after `npm ci --ignore-scripts`.
+Tests use synthetic data and temporary directories, not production memories.
+
+## Regression and package checks
+
+```bash
+npm run check
+```
+
+This runs strict TypeScript checking, the `src/**/*.test.ts` regression suite and
+`check:package`. Package checking asserts that the Pi manifest points to the current
+entry, host APIs remain peer dependencies, all production TypeScript sources are
+packed, and local documentation links resolve to packaged files. Test sources,
+helper scripts and memory state must not ship in the package.
+
+`check:package` inspects `npm pack --dry-run --json`; it does not publish to npm.
+
+## Installation smoke test
+
+```bash
+npm run test:install
+# Or select another installed Pi executable:
+PI_TEST_BINARY=/path/to/pi npm run test:install
+```
+
+Requires Pi 0.85+, Node.js 22.19+, npm, Git and `tar`. npm scripts can resolve the
+bundled Pi from dev dependencies first; use `PI_TEST_BINARY` to select your installed
+host explicitly. The script prints the tested host version. The test:
+
+1. Builds and extracts the actual npm tarball, outside the development checkout.
+2. Uses real `pi install`, `pi list` and default package discovery—no explicit `-e`
+   entry or memory-extension wrapper. Checks `/memory status`, `/memory learning`
+   and `/memory explain`, including schema 5, with no checkout `node_modules`.
+3. Verifies repeated installation does not duplicate the package setting, then
+   removes it and confirms the command disappears while records/history remain.
+4. Creates a local Git origin from the packed files and the real lockfile. A
+   fixture-only Git URL rewrite redirects an `.invalid` URL to this origin; only
+   `file` transport is permitted. No GitHub access is needed.
+5. Exercises the native Git installer and its real npm dependency step, updates to
+   a new commit, switches from an old pinned tag back to the default branch, and
+   verifies source switching and removal preserve schema-5 state.
+6. Serves the actual tarball through a loopback npm registry, with a fresh cache,
+   then checks native `pi install npm:pi-memory-evolution`, repeat installation,
+   normal loading and removal. No host peer packages are served or installed.
+
+The test whitelists child environment variables, gives Pi a fresh agent directory
+and HOME, disables startup network operations, and uses private npm caches/config with
+lifecycle scripts, audit and update notifications disabled. npm is offline for Git
+installation; only the npm fixture uses the loopback registry. Explicit Git updates
+need `PI_OFFLINE=0` (otherwise Pi silently skips them), but file-only Git transport
+and offline npm still prevent public network access. No real credentials are copied.
+Only diagnostic slash commands are submitted; a model turn is a test failure.
+Temporary files and child Pi processes are cleaned up.
+
+This checks Pi's package-management and extension-loading path, **not** public
+GitHub/public-registry availability, npm publication, every platform or the
+behavior of dependency lifecycle scripts. There is no project-specific installer:
+users install with Pi's native package manager. These tests are maintenance checks,
+not an extra installation step for users.
+
+## Real host with a simulated model
+
+```bash
+npm run test:pi
+# PI_TEST_BINARY=/path/to/pi is also supported here.
+```
+
+This uses actual Pi processes with a loopback fake provider, testing active-model
+and auth plumbing, automatic replacement, fresh cross-directory sessions,
+contextual follow-ups, unknown-topic barriers, bilingual aliases, provenance,
+feedback, forget and the read-only recall tool without approval dialogs.
+
+It executes real Git commits in temporary repositories and intentionally failed
+pushes with no remote. Long tool streams verify that early work evidence still
+nominates old pending states. Persisted failures, malformed model output, startup
+recovery and the real 15-second timer are also exercised; only synthetic retry due
+times are accelerated.
+
+These are real-host integration tests, **not live-provider semantic accuracy tests**.
+
+## Live-provider validation
+
+A live-provider run must use Pi's actual selected model/auth, synthetic fixtures and
+an isolated memory state directory. Check actual records and transaction history,
+not just an assistant acknowledgement or a job marked `done`. Inspect outgoing
+provider context for recall, and retain unverified portions of composite states.
+
+Use explicit time/call budgets and preserve failures. Do not replay production
+transcripts, copy credentials, or hand-edit production claims to make a test pass.
+`--offline` disables Pi startup probes, not model requests. Background learning can
+consume provider quota and is not included in foreground session token totals.
+
+There is no paid live-provider command in the repository's automatic checks.
+A single successful live scenario does not establish multi-day reliability or full
+product acceptance. Historical design/review documents describe their own tested
+revisions; see [progress pipeline](progress-pipeline.md), [core quality](core-quality.md)
+and [quality validation](quality-validation.md) for context.
+
+No GitHub Actions workflow is configured. Run the local checks before submitting
+changes; the Pi-dependent scripts are explicit commands, not part of `npm run check`.