# Upstream provenance

This package, `@minhduydev/pi-learning`, is a **selective fork** of
`pi-continuous-learning` from the `MattDevy/pi-extensions` monorepo. It is **not**
a compatibility fork: the upstream runtime was rewritten to remove unsafe
unbounded automatic capture/injection and to ship a bounded, auditable, append-only
project-local learning store.

## Upstream source

- **Repository**: <https://github.com/MattDevy/pi-extensions>
- **Upstream package**: `pi-continuous-learning`
- **Upstream version**: `0.14.3`
- **Original upstream commit**: `2ae490f16d669ea101b0811a50cbc37a2514e9a5`
- **License**: MIT — Copyright (c) 2026 Matt Devy (preserved verbatim in `LICENSE`).

## Filtered-history baseline

This sibling repository (`/Users/minhduydev/workspace/pi-learning`) was created with
a **filtered Git history** that retains only the `pi-continuous-learning` package
path. History rewriting changes commit SHAs, so the local annotated tag
`upstream-0.14.3` resolves to a rewritten commit and does **not** match the original
upstream SHA above. The tag marks the exact imported upstream baseline:

- **Local tag**: `upstream-0.14.3` (annotated; must not be moved or deleted).
- **Filtering**: a package-path filter kept `pi-continuous-learning/**`. The
  original upstream SHA `2ae490f16d669ea101b0811a50cbc37a2514e9a5` is documented
  here as the provenance reference; it is not present in the rewritten history.

## Kept concepts (intentional continuity)

- Lifecycle states: `observation -> candidate -> approved -> active -> retired`.
- Human-gated approval bound to an exact content digest; explicit, separate
  activation.
- Append-only event log as the source of truth with a rebuildable index
  projection.
- Project-local operation; no global store.

## Intentional divergence

- **No compatibility shim**: upstream runtime modules were deleted and replaced.
- **Bounded automation instead of none**: auto-safe is on by default for
  Pi-trusted projects, but it is confined to the `pattern`/`discovery` kinds with
  `verified-command` evidence, refuses high-risk content, and produces the separate
  `auto-approved`/`auto-active` states rather than the human-gated ones. Untrusted
  projects are fully inert. No model call, timer, process spawn, tool registration,
  or `systemPrompt` mutation in any mode.
- **No unbounded automatic behavior**: no consolidation/dream/evolve, no fact-decay,
  no instinct tools, no DCP integration, no raw transcript capture.
- **Strict, fail-closed config**: config is parsed strictly and fails closed on
  unknown schema versions, unknown fields, or unsupported unsafe values
  (`allowGlobalScope`, `autonomousEdits`). A configuration that cannot be read
  disables automation instead of falling back to the on-by-default package
  defaults. One resolver serves both the runtime and the `/learn` command.
- **Trust model**: evidence carries `source`/`locator`/`digest`/`observedAt`/
  `trust` (and optional session/task/worktree ids). No float confidence is used
  as a trust gate.
- **Storage**: canonical project-local root `.pi/artifacts/learning/v1/` with
  `events.jsonl` (source of truth) and `index.json` (rebuildable projection),
  exclusive multi-process lock, `fsync`, atomic index rename, symlink/path-escape
  rejection. No home/global store.

## Sync policy

This is a one-way selective rewrite. To re-sync from upstream:

1. Diff `MattDevy/pi-extensions` at the documented upstream commit against the
   local `upstream-0.14.3` tag to identify **concept-level** changes only.
2. Port **concepts**, not modules. Upstream runtime code is not imported; every
   behavioral change must be re-implemented against this package's safe
   architecture and covered by focused tests.
3. Do not reintroduce automatic capture, injection, autonomous edits, global
   scope, or any removed code path.
4. Bump `schemaVersion` (and document it) when the on-disk event or record schema
   changes; never silently change `v1`.