@zihanw/pi-forge 0.4.1 → 0.5.0

package/docs/design/architecture-0.5.md

@@ -0,0 +1,211 @@
+# pi-forge 0.5.0 architecture plan (lean)
+
+[Documentation](../README.md) · [Roadmap](../development/roadmap.md) · [Architecture rules](../development/architecture-rules.md)
+
+Status: accepted lean 0.5.0 scope
+
+Date: 2026-08-18
+
+The long-term architecture goal is unchanged. The original six-phase target plan and Phase-0 evidence are archived in [0.5 full architecture proposal](archive/0.5-full-proposal/README.md). This page is the executable 0.5.0 scope; 0.5.x continues toward the full target.
+
+## Goal
+
+0.5.0 is a breaking cleanup release plus the minimum foundation for later work:
+
+- deterministic immutable prompt compilation;
+- prompt-stack schema v2;
+- minimal repository/codec persistence seam;
+- optional subagents behind a versioned host port;
+- an explicit public package surface.
+
+It is not a platformization release.
+
+## Accepted 0.5.0 decisions
+
+1. **SillyTavern is removed completely.** 0.4 is the last supported conversion path. Commands, importer, regex emulation, example, guide, and tests are deleted.
+2. **Mutable variables are removed.** Turn/session stores, `setvar`/`setturnvar`/`setsessionvar`/clear/get variable macros, `variables` slot, and `pi-forge-variable-state` entries are removed. Static values become immutable `parameters` in schema v2.
+3. **`forge-v1` replaces the macro implementation.** One parsed grammar with interpolation, a finite filter set, and `if`/`else` over documented environment predicates. No includes, loops, function calls, general expressions, or ambient access.
+4. **The trusted extension port is retained and redesigned in this release.** `registerMacro` and `registerSlot` survive with a pure contract. The contract is specified in [Extension port contract](#extension-port-contract-050).
+5. **Regex `display` and `both` are removed.** Valid effects become `outgoing` and `finalize`. `finalize` behavior is retained with explicit ownership in [Finalize regex ownership](#finalize-regex-ownership-050).
+6. **Subagents move to an optional `pi-forge-subagents` package.** The main package removes the hard dependency on `@zihanw/pi-subagent-runtime`. The main package keeps `@zihanw/pi-forge/subagent` as a versioned host port with data-only event-bus messages. The `/subagent` entry owns a minimal Forge DTO host contract — wire messages, recursive validators, transport, and client/host lifecycle — plus a Forge-owned canonical fingerprint helper that stays byte-compatible with the runtime's `sha256:v1` canonical JSON. The 0.4 execution contract (the Forge host product types layered over the runtime's portable contract: request, preflight, plan, response, context, tool negotiation, and their validators) moves to the optional package with names unchanged; the optional package imports the runtime's portable leaves directly.
+7. **The 0.5.0 host port has a minimal operation catalogue and mandatory lifecycle rules.** Operations are discovery, profile listing/snapshot, and prompt preparation. Correlation IDs, payload validation, timeouts, host generation, duplicate-host failure, disposal/`unavailable`, and listener cleanup are part of host port v1, not deferred.
+8. **`ForgeWorkspace` is the minimal resource-state owner, and all stack/profile persistence goes through minimal repositories and codecs in 0.5.0.** Repositories own scoped discovery and mutation; codecs own parse/normalize/validate/serialize. Expected-fingerprint writes and guaranteed atomic replacement are 0.5.x work.
+9. **Configuration ownership uses dedicated optional-package files.** Main package owns `webEditor.*` in `.pi/forge/config.json` and its global equivalent. The optional package owns `.pi/forge/subagents.json` and `~/.pi/forge/subagents.json`. Main pi-forge does not read, write, validate, or clean subagent configuration. Legacy `config.json.subagents` is read-only fallback material for the optional package, with warnings and no automatic migration.
+10. **Web editor delegation UI is removed from the main package in 0.5.0.** The optional package ships config-only for delegation. A small standalone optional-package editor page is the 0.5.x path; a main-editor contribution port is not designed now.
+11. **Pi session custom entries:** newly written stack/profile entries use a `schemaVersion` envelope. Unversioned 0.4 entries are decoded through legacy readers. `pi-forge-variable-state` is never restored or written; one bounded diagnostic is emitted per restoration.
+12. **Public surfaces are exactly three intentional entry points:** package root default factory, package root named extension API (`registerMacro`, `registerSlot`, and their contract types), and `@zihanw/pi-forge/subagent`. All other root re-exports and `src/*` aliases are removed. `check-package` enforces this allowlist.
+13. **Migration is a small utility plus release notes, not a framework.** A v1-to-v2 script converts mechanical `variables`/macro fields with explicit diagnostics; removed behavior is never silently approximated.
+
+## Extension port contract (0.5.0)
+
+The 0.5.0 extension contract is part of the breaking release. It is a trusted-extension port, not a security boundary.
+
+- `PromptEnvironment` is a deep-frozen, JSON-compatible snapshot with three path roots:
+  - `runtime.*` — documented built-in runtime facts;
+  - `parameters.*` — immutable stack parameters;
+  - `extensions.*` — registered extension values.
+- `registerMacro` registers a named, zero-argument pure value renderer:
+  - inputs: `{ env: PromptEnvironment; helpers: PromptRenderHelpers }`;
+  - declaration: `{ name, description?, source?, dependencies: string[] }`;
+  - returns a `string`; `throw` produces a compiler error diagnostic and no partial output;
+  - addressed in templates as `{{ extensions.<name> }}`.
+- `registerSlot` keeps option-schema validation and is addressed by `kind: "slot"`:
+  - inputs: `{ item, options, env, helpers }`;
+  - same declaration, return, and error semantics as macros.
+- Dependency declarations are authoritative for the analyzer. A renderer must only read declared paths; undeclared reads are contract violations, not enforced isolation.
+- Output limits are enforced by the compiler: 100,000 characters per compiled template and 16,384 characters per extension macro/slot value.
+- Registration identity is name-based and global within the Forge extension loader. Duplicate registration throws; unregistration returns a disposer. The workspace owns load/reload/dispose ordering and reuses the current trusted extension discovery directories.
+- Preview, runtime, and subagent preparation use the same analyzer output. No consumer may parse template syntax independently.
+
+## Finalize regex ownership (0.5.0)
+
+`finalize` is retained, but is explicitly outside deterministic prompt compilation:
+
+- **Owner:** the lifecycle/transcript adapter, not the compiler.
+- **Order:** after the provider returns a finalized assistant message, before that message is stored in the transcript.
+- **Constraints:** `stage: "compiled"`, `targets: ["messages"]`, and assistant roles only, as validated today.
+- **Preview:** preview and runtime prompt compilation never apply `finalize`. Preview reports an informational diagnostic that finalize rules are not represented.
+- **Restoration:** the original model output is not preserved. This remains a documented, user-enabled destructive transform carried over from 0.4.
+- **Tests:** 0.5.0 adds characterization coverage for finalize ordering and non-application during preview.
+
+## Minimal target state
+
+```mermaid
+flowchart LR
+    Adapters["Commands + lifecycle + web editor"] --> Workspace["ForgeWorkspace"]
+    Workspace --> Repos["Minimal repositories + codecs"]
+    Workspace --> Compiler["forge-v1 compiler"]
+    Compiler --> Extensions["Trusted extension port"]
+    Workspace -. "event-bus host port v1" .-> Optional["pi-forge-subagents"]
+    Optional --> Runtime["pi-subagent-runtime"]
+```
+
+The final layered target (core modules, full application services, complete host catalogue, fingerprint/atomic persistence) remains the archived full plan and is reached in 0.5.x.
+
+## Implementation lanes
+
+Only one lane is active at a time. Each lane ends with `npm run verify` green and committed.
+
+### Lane 0: documentation convergence
+
+Archive the full proposal, make this lean plan active, and simplify repository guidance and PR requirements.
+
+### Lane 1a: removals only
+
+- Remove SillyTavern code, tests, examples, and guides.
+- Remove mutable variable stores, variable session entries, variable macros, and the `variables` slot.
+- Remove regex `display`/`both` and make them validation errors.
+- Keep static `stack.variables` working through the existing compiler until schema v2 lands in Lane 1b.
+- Update only tests that cover removed behavior.
+
+### Lane 1b: compiler, schema v2, and extension contract
+
+- Implement `forge-v1` parse/analyze/render.
+- Introduce frozen `PromptEnvironment` and make preview/runtime/subagent preparation share one compiler entry.
+- Introduce schema v2 with immutable `parameters`.
+- Implement the [extension port contract](#extension-port-contract-050).
+- Retain `finalize` under the ownership rule above and add its characterization coverage here.
+- Add compiler/schema/extension conformance coverage.
+
+### Lane 1c: migration and documentation
+
+- Add the small v1-to-v2 migration script with explicit diagnostics.
+- Migrate examples and update English and Chinese user-facing compiler/schema/extension docs.
+- Update changelog and migration notes for the Lane 1 breaks.
+
+### Lane 1d: compiler/extension conformance
+
+- Make custom slot extensions symmetric with macros: pure `{ item, options, env, helpers }` render context, declared `dependencies`, and the same 16,384-character output limit.
+- Resolve declared extension dependencies when populating `env.extensions` for slot rendering.
+- Introduce a reusable prompt dependency analysis plan (direct dependencies, transitive extension closure, slot dependencies, diagnostics) shared by runtime compilation, preview, and subagent preparation.
+- Create one compilation context per provider-preparation cycle with a single runtime/timestamp snapshot, frozen base environment, and request-local extension cache shared between system and message compilation; this applies to the runtime lifecycle (`before_agent_start` + `context`), preview rendering, and subagent host preparation alike. Cache entries are keyed by name and frozen environment snapshot; `latestUserMessage` is the one captured field that can change between phases, and `setLatestUserMessage` invalidates the cache only when the value actually changes, so env-dependent macros observe the current value instead of a stale pre-phase snapshot. Tradeoff: when the value does change, the whole request-local cache is dropped, so a stateful/non-deterministic macro appearing in both phases may render different values per phase (system keeps the pre-invalidation value, messages get a fresh one); the two phases still share one explicit timestamp snapshot.
+- Keep dependency analysis eager, but resolve extension values lazily during rendering so unreachable branches do not execute extensions.
+- Support nested `{% if %}` blocks with a recursion-depth guard.
+- Fix parser conformance issues such as empty-string comparisons and strict undefined handling.
+- Clarify or document `maxChars` best-effort semantics and separate empty-system-prompt fallback from compile failure.
+- Add focused conformance tests for all of the above.
+
+### Lane 2a: minimal repositories and codecs
+
+- Extract stack/profile codecs as the single parse/normalize/validate/serialize source: `src/codecs/prompt-stack.ts` and `src/codecs/agent-profile.ts` own parse/normalize/validate/serialize, and the loaders (and migration tooling) delegate to them; repositories (`src/repositories/`) are the only read/write/delete path for domain resources — reads (directory enumeration + file reads through the codecs) and mutations (scope/containment/symlink-checked writes and deletes) both live there, and `loader.ts`/`agent-profile.ts` only delegate.
+- Extract scoped repositories as the only domain resource read/write/delete path, including scope and containment validation. Legacy stack migration is a documented byte-preserving exception: its raw IO lives in the repository (read/copy/delete for `.pi/prompt-stacks`), while canonicalization happens on every subsequent load through the codecs.
+- Remove direct domain-resource writes from web host, commands, and profile service.
+- Do not add expected-fingerprint conflicts or guaranteed atomic replacement yet; characterize current replacement behavior with tests.
+
+### Lane 2b: ForgeWorkspace and host port v1
+
+- Introduce `ForgeWorkspace` as the minimal snapshot owner over the Lane 2a repositories: one immutable scoped stack/profile snapshot plus active selection/provenance, owning host registration/generation/disposal.
+- Publish `@zihanw/pi-forge/subagent` host port v1 over the Pi event bus with mandatory lifecycle rules and the three minimal operations (discovery, profile listing/snapshot, and prompt preparation). The port is transport-neutral (`ForgeHostTransport`), uses plain validated data messages, and never crosses live contexts or internal registries.
+- Mandatory lifecycle semantics: clients subscribe before announcing/discovering and use bounded timeouts; duplicate live hosts fail with an explicit `host.duplicate` error; disposal sends `unavailable` and invalidates connections; all transient and persistent listeners are cleaned up. `request`/`reply` wire messages carry `hostId` + `generation`, so stale-generation and wrong-host requests are rejected server-side and mismatched replies are ignored client-side.
+- Host-owned preparation: the client sends only a profile selector, task, prompt-compilation access facts (`level`/`network`/`allowProcess`) and backend facts (model/thinking/tool catalog); the workspace resolves the profile + stack from its snapshot and compiles the prompt itself, returning an immutable preparation artifact (system prompt, messages, effective tools, diagnostics, and profile snapshot). No execution/runtime material (access workspace model, limits, `resultProjection`/`parent`/`remoteEgressConsent`, or a base prompt) crosses the boundary. Each operation has a recursive, exact-field, JSON-compatible validator (plain objects only, enums enforced) at the wire boundary.
+- `ForgeWorkspace` snapshots are genuinely immutable (deep-frozen clones), and the host port is wired into the real extension lifecycle (`pi.events` transport; reload on session start/tree/compact; dispose on session shutdown, before subagent teardown). The host can only be started after the first snapshot exists (`startHostPort` throws otherwise), so `host available` ⇒ `snapshotKnown`; `reload` honors project trust (untrusted workspaces expose global resources only). The base system prompt is host-owned and intentionally empty for delegated subagents — the prompt stack composes the system prompt, and the host rejects unknown request fields so no prompt-runtime material can be smuggled across the boundary.
+- Cover timeout, duplicate-host failure, generation/stale-request rejection, disposal, listener cleanup, operation validators, immutability, and a real-factory integration discovery->list->prepare->dispose flow in tests.
+
+### Lane 3: subagent extraction
+
+- Create `pi-forge-subagents` by moving current subagent commands, tools, config parsing/writing, and execution code.
+- Optional package depends only on documented host-port messages and owns the dedicated `subagents.json` files, with read-only legacy fallback.
+- Remove main-package delegation UI and all subagent configuration reads/writes.
+- Main package installs and passes verification without the subagent runtime.
+- Optional package passes packed-install smoke tests.
+
+### Lane 3.5: host-neutrality hardening
+
+Emergent lane recorded after the fact; executed in three stages.
+
+- Stage 1: make the prompt compiler host-neutral.
+- Stage 2: make `ForgeWorkspace` the single resource-state owner.
+- Stage 3: align subagent docs/config with the optional package and make the packed smoke portable. The optional package gains profile discovery, the `/forge-agent` command, legacy config fallback, and tool-description summary refresh.
+
+### Lane 4: public surface and release
+
+Lane 4a: Forge-native host contract (both packages).
+
+- The main package drops the `@zihanw/pi-subagent-runtime` dependency entirely. (An earlier draft of this lane kept the runtime as the `/subagent` contract library; that contradicted decision 6 and the release gates and is removed.) `/subagent` owns the minimal Forge DTO host contract described in decision 6.
+- Workspace prompt preparation becomes Forge-native: resolve profile and stack from the snapshot, compile through the shared compilation context, filter the client tool catalog through stack policy, and return the `prepare` DTO directly. The synthetic AgentRequest/preflight/prompt-runtime construction is removed.
+- The 0.4 execution contract modules move to the optional package per decision 6; contract tests move with the code.
+
+Lane 4b: main-package public-surface cut.
+
+- Root exports reduce to the default factory plus `registerMacro`/`registerSlot` and their contract types; `/subagent` exports the host contract only; `src/*` aliases are removed.
+- `check-package` flips from requiring legacy aliases to forbidding them and enforcing the three-entry allowlist; public-API tests assert exact export name sets; packed-install smoke assertions follow the trimmed surface.
+
+Lane 4c: optional-package packed smoke.
+
+- The optional package gains its own `check:packed`: pack both packages, install into a temporary consumer, load the extension, and run discover → listProfiles → prepare → dispose over a loopback `ForgeHostTransport` against a fixture workspace.
+
+Lane 4d: documentation and changelog.
+
+- Update English and Chinese user-facing docs for breaking changes: rewrite the public-API policy for the three surfaces, replace the subagent adapter contract reference with the host-port contract, complete the 0.5 migration guide (Lanes 2–4) in English and Chinese, and fix stale README references.
+- Write changelog entries for Lanes 3.5 and 4 and one-page migration notes.
+
+Lane 4e: release.
+
+- Run main-only and main-plus-optional packed-install verification (`check:packed` smoke), version both packages 0.5.0, publish main then optional, smoke the published artifacts, and tag.
+
+## Release gates
+
+- `npm run verify` passes.
+- All stack/profile persistence goes through minimal repositories and codecs.
+- Runtime and preview compile through one `forge-v1` entry point.
+- Host port v1 passes discovery, timeout, generation, duplicate-host, and disposal tests.
+- `finalize` ordering and preview exclusion are characterized.
+- Schema v2, extension contract, and migration notes are documented.
+- Main package has no subagent runtime dependency and passes packed smoke tests alone.
+- Optional package passes packed smoke tests through host port v1 and owns only its dedicated config files.
+- No non-allowlisted root exports or `src/*` aliases remain.
+- User-facing breaking changes are documented in English and Chinese.
+
+## Deferred to 0.5.x
+
+These items come from the archived full plan and are intentionally not part of 0.5.0:
+
+- expected-fingerprint conflict writes and guaranteed atomic file replacement;
+- physical `pi-forge-core` package and enforced module/package boundaries;
+- automatic dependency-direction checking;
+- full `PromptStackService` / `AgentProfileService` application facades;
+- complete host RPC operation catalogue, progress events, and richer lifecycle features beyond host port v1;
+- optional-package standalone delegation UI or a main-editor contribution port;
+- full public-surface classification register and consumer audit repeat;
+- rolling Pi compatibility matrix and scheduled latest-Pi probe;
+- sandbox, staged writes, new prompt features, richer imports, and orchestration.

package/docs/design/archive/0.5-full-proposal/0.5-consumer-audit.md

@@ -0,0 +1,62 @@
+# 0.5 public-consumer audit
+
+[Design index](README.md) · [0.5 migration inventory](0.5-inventory.md) · [0.5 decision drafts](0.5-phase0-decision-drafts.md)
+
+Status: completed Phase 0 evidence; public-surface decision pending
+
+Date: 2026-08-17
+
+## Scope and method
+
+This audit identifies known consumers of surfaces that Phase 6 may remove or
+replace. It covers the repository, published npm metadata, the Pi package
+directory, public web searches for exact import strings, and an unauthenticated
+GitHub code-search attempt. It cannot prove that no private or unindexed
+consumer exists.
+
+## Findings
+
+| Surface | Known consumer / evidence | Confidence | 0.5 implication |
+|---|---|---|---|
+| Default package entry | `pi.extensions` in the published manifest | High | Retain as main extension entry |
+| `@zihanw/pi-forge/subagent` | Public-API packaged-import test; reference documentation | High | Retain only as the deliberate versioned host port |
+| Root macro/slot registration | Custom-system-status example, user guide, and Pi package listing | High | Acknowledge a real documented integration path; publish a migration or replacement contract |
+| Root profile/resource helper exports | Repository tests and root barrel only | Medium | No named external consumer found; do not preserve by default |
+| `@zihanw/pi-forge/src/*` aliases | Compatibility documentation and package manifest | Medium | No named external consumer found; announce removal and retain no new alias |
+| Root documentation pointers | Package `files` allowlist, root `PUBLIC_API.md`, root `SUBAGENT_ADAPTER_CONTRACT.md` | High | Decide whether to retain as offline redirect files |
+| SillyTavern converter/command | Released docs, examples, and tests | High | User-facing migration obligation, but planned removal is explicit |
+
+The local repository contains no package-style import other than its own
+`@zihanw/pi-forge/subagent` public-surface test. It contains no downstream
+repository or fixture that imports a `src/*` alias.
+
+## Published-package observations
+
+- npm reported `@zihanw/pi-forge` 0.4.1 as `latest` on 2026-08-17. Its manifest
+  contains the root and `/subagent` exports, the three `src/*` compatibility
+  patterns, and `@zihanw/pi-subagent-runtime` as a hard dependency.
+- The same manifest identifies Pi SDK packages and `typebox` as wildcard peers.
+- The Pi package directory is discoverable and documents `registerMacro` and
+  `registerSlot` as reusable-package APIs. At crawl time it displayed stale
+  0.3.2 package metadata, despite npm reporting 0.4.1. It is useful evidence of
+  discoverability, not an authoritative release or consumer record.
+
+## Search results and limitations
+
+- Exact public-web searches for `@zihanw/pi-forge`,
+  `@zihanw/pi-forge/subagent`, and `@zihanw/pi-forge/src/` found the package
+  listing and this repository's published material, but no independent source
+  import.
+- Unauthenticated GitHub code search rejected the exact-import query with HTTP
+  401. A maintainer with appropriate access should repeat it, including private
+  organization repositories, before a release removes compatibility exports.
+- npm does not provide a reliable reverse-dependency list for this extension;
+  download counts cannot identify source/API consumers.
+
+## Required release follow-up
+
+Before Phase 6, repeat the search with maintainer GitHub credentials, inspect
+support/issues/discussions for named integrations, and add every discovered
+consumer to the public-surface decision register. The absence of a discovered
+consumer supports removal only under the 0.5 breaking-release policy; it is not
+a claim that no consumer exists.

package/docs/design/archive/0.5-full-proposal/0.5-inventory.md

@@ -0,0 +1,208 @@
+# 0.5.0 migration inventory
+
+[Design index](README.md) · [0.5 architecture plan](architecture-0.5.md) · [Architecture rules](../../../development/architecture-rules.md)
+
+Status: Phase 0 evidence; not an accepted architecture decision
+
+Date: 2026-08-17
+
+This inventory records the 0.4.1 surfaces that 0.5 must retain, migrate, remove,
+or deliberately replace. It is a characterization aid, not a promise to preserve
+every current behavior. The 0.5 plan remains authoritative, and a maintainer must
+accept any new boundary or product decision before implementation.
+
+## Snapshot and method
+
+The inventory is based on tracked source, tests, the package manifest, and
+documentation at commit `5b56096`. It lists in-repository consumers and
+documented integration surfaces. It cannot establish unknown downstream npm
+consumers; that check remains a Phase 6 release task.
+
+| Area | Current evidence | 0.5 disposition |
+|---|---|---|
+| Prompt stacks | Schema v1 files, project/global catalogs, legacy project read path, compiler, macros, slots, regex, tool/skill policy | Keep as v2 compiler/resource work; remove mutable variables; audit finalized regex; retire legacy storage compatibility on the documented path |
+| Agent profiles | Schema v1 files, project/global catalogs, model/thinking/stack preflight, apply, provenance, drift | Keep as a separate domain and service; introduce v2 only if storage changes |
+| Runtime state | One `PiForgeRuntimeState` owns resources, lifecycle values, presentation/debug state, and variables | Replace with workspace-owned resource snapshot plus separate adapter state slices |
+| Browser editor | Token-gated localhost HTTP server; host performs resource workflows and direct writes | Retain as an adapter; move resource mutation and validation into services/repositories |
+| Subagents | Main extension registers commands/tools and directly depends on `@zihanw/pi-subagent-runtime` | Extract as optional package behind a versioned public host port |
+| SillyTavern | Import command, converter, report, guide, example, tests | Remove completely; require conversion on 0.4 before upgrading |
+| Package surface | Root exports, `/subagent`, and `src/*` compatibility patterns | Replace with explicit 0.5 entries; retain only intentional public ports |
+
+## Public package and extension surfaces
+
+### Package manifest
+
+- Package: `@zihanw/pi-forge` 0.4.1; Pi entry: `dist/index.js`.
+- Public exports: package root, `@zihanw/pi-forge/subagent`, examples, and broad
+  compiled `@zihanw/pi-forge/src/*` compatibility aliases. Browser client paths
+  are explicitly blocked.
+- Pi SDK packages and `typebox` are optional wildcard peers. The repository's
+  development fixture is Pi 0.83.0; no minimum or tested Pi range is published.
+- `@zihanw/pi-subagent-runtime@0.1.0-beta.2` is currently a hard dependency.
+- `PUBLIC_API.md` and `SUBAGENT_ADAPTER_CONTRACT.md` are npm-published root
+  compatibility pointers to the authoritative reference documentation. Their
+  0.5 package-file and redirect status is not yet decided.
+
+### Root exports grouped by intent
+
+| Current surface | Evidence / consumer | 0.5 review action |
+|---|---|---|
+| Default Pi extension factory | `src/index.ts`; `pi.extensions` manifest | Keep as main package entry point |
+| Resource identity/catalog/loader helpers | Root barrel and tests | Decide whether each is a stable domain export or internal |
+| Macro/slot registration and Forge extension API | Root barrel; custom-system-status example and guide | Preserve only as an intentional trusted-extension port, compatible with immutable compilation |
+| Profile repository/resolution/application APIs | Root barrel and profile tests | Replace experimental APIs with deliberate service/domain exports if external consumers exist |
+| Subagent contract and host preparation helpers | Root compatibility re-exports and `/subagent` entry | Keep `/subagent`, but replace its current internal host-preparation surface with a versioned port |
+| `src/*` aliases | Documentation and package checks | Remove in Phase 6 after consumer audit and migration notice |
+
+The only in-repository package-style import is the public-API test of
+`@zihanw/pi-forge/subagent`. Documentation identifies trusted macro/slot
+extension authors as intended consumers. No external consumer audit is recorded.
+
+### Phase-0 public-surface decision register
+
+This is the required decision format for the final public-surface review. The
+listed dispositions are provisional until consumer audit and maintainer review;
+Phase 6 must execute this register rather than make API decisions while deleting
+exports.
+
+| 0.4 surface group | Candidate 0.5 disposition | Target entry point / migration | Known consumer | Decision status |
+|---|---|---|---|---|
+| Default extension factory | Stable | Package root default export | Pi package manifest | Provisional: retain |
+| Macro/slot and trusted Forge extension registration | Stable or experimental | Deliberate main-package extension port | Custom-system-status example; documented trusted extension authors | Pending compiler-extension contract |
+| Resource identity/catalog/loader helpers | Internal unless a named consumer requires a domain port | No `src/*` replacement by default | Root barrel and tests only | Pending consumer audit |
+| Profile repository/resolution/application helpers | Experimental or internal | Deliberate service/domain entry only if justified | Root barrel and tests only | Pending service boundary and consumer audit |
+| `/subagent` host contract | Versioned experimental host port | `@zihanw/pi-forge/subagent` | Public-API test; future optional extension | Pending host-discovery decision |
+| Root re-exports of subagent names | Remove or retain only as one-release migration shim | Direct consumers to `/subagent` | 0.4 compatibility policy | Pending consumer audit and migration decision |
+| `src/*` aliases | Remove | Intentional entries only | Compatibility documentation | Planned removal in Phase 6 |
+| `PUBLIC_API.md` and `SUBAGENT_ADAPTER_CONTRACT.md` | Retain as package pointers or replace with package-local index | Decide published-file policy with the final entries | `files` allowlist and current documentation | Pending Phase 6 public-doc decision |
+
+## Persisted resources and state
+
+### Resource files
+
+| Resource | Locations | Schema / current behavior | Migration concern |
+|---|---|---|---|
+| Prompt stack | Project `.pi/forge/prompt-stacks/*.json`; global `~/.pi/forge/prompt-stacks/*.json`; legacy project `.pi/prompt-stacks/*.json` read path | v1 `PromptStack`; scoped project-over-global resolution; loader normalizes and validates | Define v1→v2 codec, retained regex fields, `variables`→immutable `parameters`, conflict/backup behavior, and final legacy-path removal |
+| Agent profile | Project `.pi/forge/agent-profiles/*.json`; global `~/.pi/forge/agent-profiles/*.json` | v1 `pi-forge.agent-profile`; model, thinking level, relative scoped stack reference, optional auto-activation | Preserve IDs/scoped references where possible; decide whether v2 is needed and document any rewrite |
+| Main-package configuration | Project/global `.pi/forge/config.json` | `webEditor.port` | Main package owns the editor setting; keep it outside stack/profile repositories |
+| Subagent configuration | Currently project/global `.pi/forge/config.json`, `subagents.*` | Defaults, per-profile authorization, backend/timeout, unattended invocation and summary flag | Open: optional package must own parsing, validation, writes, and migration; decide whether it remains a namespaced shared file or moves to a dedicated file |
+| Trusted Forge extensions | Project/global `.pi/forge/extensions/*.{ts,js,mjs,cjs}` | Executable macro/slot registrations, loaded on trusted projects | Workspace owns registration lifecycle; compiler v2 must define the replacement extension contract |
+| Payload captures | User-selected path, commonly `.pi/forge/payloads/last.json` | Redacted provider payload, potentially sensitive | Presentation/debug artifact, not workspace resource state |
+
+### Pi session custom entries
+
+| Entry type | Stored data | Current restoration | 0.5 requirement |
+|---|---|---|---|
+| `pi-forge-prompt-stack-state` | `activeStackId` | Latest branch entry selects scoped active stack | Version/restoration and v1 selector migration policy |
+| `pi-forge-agent-profile-state` | Profile provenance or `null` | Latest branch entry drives drift status; does not reapply profile | Version/restoration policy and compatibility with profile schema changes |
+| `pi-forge-variable-state` | Mutable session variables | Latest branch entry restores variables | Remove and provide an explicit ignored/diagnostic migration path; do not write a replacement |
+
+These entry payloads have no explicit version today. This requires a state
+decision and migration notes under the architecture rules.
+
+## Runtime ownership and Pi coupling
+
+`PiForgeRuntimeState` currently holds stacks, profiles, active selection,
+profile provenance, compile inputs/variables, diagnostics, Forge-extension
+registration metadata, payload capture, and browser-facing state. Its users span
+the stack, profile, policy, web-editor, payload, lifecycle, and subagent paths.
+
+| Pi coupling | Current owner / use | 0.5 target |
+|---|---|---|
+| Lifecycle | Session, resource-discovery, tree/compact/shutdown, input/turn, compilation/context and message events | Pi adapter translates events to workspace/services and owns adapter-only transient state |
+| Compilation | `before_agent_start` and `context` provide live Pi context, clock, system options and messages | Normalize inputs once into immutable `PromptEnvironment`; preview and runtime share the compiler |
+| Tool policy | Pi active-tool APIs plus input/turn reassertion and tool-call guard | `ToolPolicyPort`; preserve baseline reconciliation with other extensions |
+| Profile application | Pi model/thinking setters plus active-stack mutation and rollback | Runtime-controller port with preflight and documented compensation semantics |
+| Extension registrations | Forge loader mutates macro/slot registries | Workspace-coordinated trusted registration lifecycle, without core importing Pi adapters |
+| Subagents | Main extension creates runtime/backends and reads shared state | Optional extension calls only the versioned Forge host capability |
+
+## Commands, tools, and HTTP adapter surface
+
+| Surface | Current operations | 0.5 disposition |
+|---|---|---|
+| `/preset` | List, status, use/disable, preview, validate, diagnostics, reload, UI, legacy migration, SillyTavern import | Keep ordinary stack operations as service calls; remove legacy migration command after documented migration and remove SillyTavern command |
+| `/profile` | List, use, save, status, preview, validate, reload, forget | Keep as thin profile-service adapter |
+| `/payload` and `/intercept` | Arm/display/save redacted next provider payload | Keep as separate debug/presentation slice; decide path-safety independently of domain resources |
+| `/forge-agent` | Backends, dry plan, approved run | Move with optional subagent integration |
+| `forge_subagent_profiles` and `forge_subagent` | Enabled-profile discovery and foreground delegation | Move with optional subagent integration |
+| Local editor HTTP API | Stack/profile list/get/validate/create/save/delete/apply/reload/activate; resources; payload; delegation config | Retain token-gated localhost adapter; map typed service results to HTTP and remove workflow/persistence from web host |
+
+The editor binds to `127.0.0.1`, uses a per-server random token, and accepts the
+token in the query/header. Browser source remains under `src/web-editor/client/`;
+generated embedded assets must not be hand edited.
+
+## Current resource mutation locations
+
+| Location | Current mutation | Phase 1 target |
+|---|---|---|
+| `web-host.ts` | Stack/profile/config reads and writes, deletes, creation, import routing | Adapter invokes repositories/services only |
+| `profile-service.ts` | Profile create/write/delete | Move filesystem behavior to profile repository and codec |
+| `preset-command.ts` | SillyTavern converted stack/report writes | Remove with SillyTavern surface |
+| `stack-migration.ts` | Legacy stack copy/delete | Retire after the documented pre-0.5 migration path |
+| `forge-config.ts` | Configuration writes | Separately owned configuration concern unless explicitly redesigned |
+| `payload-command.ts` | User-requested payload file write | Debug artifact, not a domain-resource repository |
+
+Current resource mutation has path-containment and symlink checks in several
+paths, but replacement writes are not uniformly atomic and stack mutations do
+not uniformly carry expected fingerprints. Phase 1 must characterize these
+behaviors before changing them.
+
+## Tooling and verification surface
+
+| Tooling | Current enforcement | 0.5 review action |
+|---|---|---|
+| `scripts/check-package.mjs` | Package tarball layout, wildcard Pi peers, `src/*` compatibility exports, blocked browser paths | Update with final explicit entry points and root compatibility-pointer policy in Phase 6 |
+| `scripts/check-dist.mjs` | Generated `dist/` matches authored source | Update only alongside intentional source/package layout changes |
+| `scripts/check-docs.mjs` | Local documentation-link validation | Keep links current as 0.5 guides, migration material, and redirects replace 0.4 documentation |
+| `scripts/build-web-client.mjs` | Generated embedded browser script/style synchronization | Preserve; regenerate only from authored `src/web-editor/client/` changes |
+| Public API and package tests | Root/subagent export compatibility and packed-entry behavior | Replace 0.4 compatibility assertions with the accepted public-surface register in Phase 6 |
+
+`package.json` scripts, the browser suite, build/type checks, and packed-install
+smoke tests are part of the release evidence. The final verification matrix must
+test the documented Pi range with and without the optional subagent package.
+
+## Documentation, examples, and characterization coverage
+
+### Released documentation requiring a 0.5 review
+
+- Prompt-stack schema, macro/slot, agent-profile, configuration, command,
+  debugging, delegation, web-editor, getting-started, public-API, and subagent
+  contract documentation.
+- English and Chinese user guides. Chinese internal architecture documentation
+  is not required by the plan, but user-facing breaking changes are.
+
+### Examples and tests requiring disposition
+
+| Item | 0.5 action |
+|---|---|
+| Default, image-reader, reviewer, and validation prompt-stack examples | Revalidate or migrate against schema v2 |
+| Custom system-status extension | Retain only if it conforms to the replacement template/slot extension port |
+| SillyTavern example, importer fixtures/tests, and guide | Remove after final 0.4 conversion path is documented |
+| Compiler, profile, catalog, policy, lifecycle, web-editor, and subagent tests | Preserve as characterization coverage until the responsible phase replaces them |
+| Browser editor tests | Keep through adapter migration; regenerate client assets when authored client code changes |
+
+## Phase-0 open work and exit evidence
+
+1. Record maintainer acceptance or amendment status for the proposed 0.5 plan.
+2. The [external-consumer audit](0.5-consumer-audit.md) is complete with an
+   explicit unauthenticated-search limitation. Repeat it with maintainer access
+   before Phase 6 removes exports or compatibility paths.
+3. The [template-language spike](template-language-spike.md) is complete.
+   Accept its grammar, environment, extension-port, schema, and migration
+   decisions before Phase 3.
+4. The [Pi host-discovery spike](host-discovery-spike.md) is complete.
+   Accept its event-bus host-port protocol, operation catalogue, versioning, and
+   lifecycle rules before Phase 5.
+5. Establish a supported Pi version range and packed-install test matrix.
+6. Decide Pi session custom-entry versioning and restoration semantics for
+   prompt-stack state, profile state, and removed variable state.
+7. Decide main-package versus optional-subagent ownership and storage migration
+   for `webEditor.*` and `subagents.*` configuration.
+8. Complete and accept the public-surface decision register before Phase 6.
+9. Turn repository/reload, profile-application, finalized-regex,
+   migration-artifact, and physical-package questions into accepted decisions
+   before their affected implementation phases.
+
+Phase 0 exits only when this removal/migration inventory and the resulting
+decisions are reviewed. This inventory alone authorizes no implementation
+boundary changes.