@zihanw/pi-forge 0.4.1 → 0.5.0

package/docs/design/archive/0.5-full-proposal/0.5-phase0-decision-drafts.md

@@ -0,0 +1,237 @@
+# 0.5.0 Phase-0 decision drafts
+
+[Design index](README.md) · [Architecture decision template](../../decision-template.md) · [Migration inventory](0.5-inventory.md)
+
+Status: proposed drafts; requires maintainer acceptance
+
+Date: 2026-08-17
+
+This document packages the remaining Phase-0 choices for review. It does not
+authorize code, schema, package, or persistence changes. Each accepted section
+may become a focused architecture decision or an amendment to the 0.5 plan.
+
+## D1: Pi compatibility and release matrix
+
+### Candidate decision
+
+Support Pi 0.83.0 as the initial documented minimum, because it is the checked
+development fixture and supplies the extension/event APIs used by pi-forge.
+Treat compatibility as a rolling list of explicitly tested Pi versions, not a
+semver range inferred from wildcard peers. Test 0.83.0 and npm `latest` (0.84.2
+when this draft was written) for every 0.5 release candidate, including packed
+main-only and main-plus-optional-subagent installs. Keep Pi packages as wildcard
+optional peers so Pi supplies one coherent SDK instance.
+
+### Alternatives
+
+- Claim every Pi version through a semver range: reject, because wildcard peers
+  and Pi's frequent 0.x releases do not prove behavioral compatibility.
+- Pin Pi dependencies inside pi-forge: reject, because it risks duplicate Pi
+  runtimes and conflicts with Pi package loading.
+
+### Acceptance evidence
+
+Document exact tested versions, Node version, packed-install commands, and
+main-only/optional-package results in release notes. Run a scheduled latest-Pi
+probe that reports compatibility but does not silently widen the supported list.
+
+## D2: Pi session custom-entry versioning
+
+### Candidate decision
+
+Keep the existing prompt-stack and profile custom entry types, but make every
+newly written payload an envelope with `schemaVersion: 1`. Read unversioned 0.4
+entries through explicit legacy decoders only; do not rewrite historical Pi JSONL
+entries. Ignore unknown versions and malformed entries with a bounded diagnostic.
+
+The latest valid entry in the active branch remains authoritative. Restoring a
+selector or provenance must never apply a profile or mutate Pi runtime state.
+`pi-forge-variable-state` is never restored or written in 0.5; its presence
+produces one migration diagnostic per restoration, not a variable store.
+
+### Alternatives
+
+- Rename all custom entry types: reject unless a real collision requires it;
+  existing type names are useful migration anchors.
+- Continue unversioned free-form payloads: reject; it violates the state rules.
+- Automatically append replacement entries while restoring: reject; opening a
+  historical session must not mutate it.
+
+### Acceptance evidence
+
+Characterization tests cover legacy/current/unknown/malformed entries, branch
+selection, compaction/tree navigation, missing resources, and no variable-state
+resurrection.
+
+## D3: configuration ownership after subagent extraction
+
+### Candidate decision
+
+The main package owns `webEditor.*` in `.pi/forge/config.json` and its global
+equivalent. The optional package owns all subagent configuration, parsing,
+validation, mutation, and diagnostics in dedicated
+`.pi/forge/subagents.json` and `~/.pi/forge/subagents.json` files. Main pi-forge
+does not read, write, validate, or surface subagent policy when the optional
+package is absent.
+
+The optional package may read the 0.4 `config.json.subagents` section only in a
+one-time migration mode. It writes no automatic migration, preserves the legacy
+section, and reports conflicts rather than merging silently.
+
+### Alternatives
+
+- Keep a shared `config.json` namespaced section: lower migration cost, but
+  creates shared-file coordination and leaves main-package ownership ambiguous.
+- Preserve main-package parsing of `subagents.*`: reject; it contradicts the
+  optional package boundary.
+
+### Acceptance evidence
+
+Test absent optional package, untrusted project, project/global precedence,
+legacy-config migration, conflict reporting, and deletion/config cleanup.
+
+## D4: resource repositories and workspace snapshots
+
+### Candidate decision
+
+Repositories own all stack/profile discovery and mutation. A codec is the only
+source of parse, normalize, validate, serialize, and content fingerprint logic.
+Every write/delete receives an expected fingerprint when replacing an existing
+resource; mismatch returns a typed conflict without writing.
+
+`ForgeWorkspace` serializes reloads and publishes an immutable complete
+snapshot with a monotonic revision. There is no filesystem watcher in 0.5:
+explicit reload and existing lifecycle-driven reload are the only refresh paths.
+Invalid/missing resources appear as diagnostics in the published snapshot, while
+resolution and activation fail closed. A selected active resource that becomes
+invalid or disappears is not active until a later complete reload resolves it.
+
+Filesystem repositories use temp-file-plus-rename replacement where supported,
+validate containment before every mutation, and clean failed temporary files.
+
+### Alternatives
+
+- Keep synchronous adapter writes: reject; it preserves duplicate persistence
+  workflows and bypasses consistent conflict handling.
+- Publish each catalog independently: reject; profiles could resolve against a
+  different stack generation.
+- Add file watching during the refactor: defer; it is a new state/lifecycle
+  feature outside 0.5 scope.
+
+### Acceptance evidence
+
+Test external edit conflicts, atomic-write failures, reload serialization,
+mixed valid/invalid catalogs, scoped shadowing, active deletion, and consumers
+never observing half a stack/profile graph.
+
+## D5: profile-application transaction semantics
+
+### Candidate decision
+
+`AgentProfileService` resolves and validates model, authentication, thinking,
+stack, and tool policy before any Pi mutation. It delegates mutations to a
+runtime-controller port in this order: model, thinking level, active stack/tool
+policy. It records provenance only after all three succeed.
+
+On failure, the service compensates in reverse order using the captured prior
+state and reports every failed compensation. This is a best-effort transaction,
+not an atomic Pi-host transaction; an unset prior model that Pi cannot restore
+is an explicit residual failure. Adapters render the typed result but do not
+attempt their own rollback.
+
+### Alternatives
+
+- Call Pi setters directly from commands/web handlers: reject; it duplicates
+  transaction behavior.
+- Describe this as atomic: reject; Pi setters have externally visible effects
+  and no common rollback primitive.
+
+### Acceptance evidence
+
+Integration tests cover each failure point, unexpected thinking-level clamp,
+missing stack after preflight, rollback failure, provenance write timing, and
+browser/command equivalence.
+
+## D6: regex and v1-to-v2 migration
+
+### Candidate decision
+
+Retain deterministic outgoing `history` and `compiled` regex transforms in v2,
+after schema characterization. Remove `display`/`both` as unsupported 0.4
+configuration and remove destructive `finalize` transforms: they alter stored
+assistant transcript after streaming and sit outside deterministic compilation.
+
+Provide one explicit v1-to-v2 migration utility with dry-run default, per-file
+diagnostics, no overwrite unless requested, backup/copy before replacement, and
+no source deletion. It mechanically converts only documented safe fields and
+emits error-level diagnostics for mutable variables, custom macros/slots,
+removed regex effects, and unsupported template constructs. Users run the final
+0.4 storage migration before the v2 utility; 0.5 does not retain the legacy
+storage migration command.
+
+### Alternatives
+
+- Retain `finalize`: requires a separate persistent-transcript ownership and
+  previewability decision; defer rather than retain incidentally.
+- Silently drop unsupported fields: reject; migration must make behavior loss
+  visible.
+- Keep both legacy storage and v2 migration commands indefinitely: reject;
+  conflicts with the breaking-cleanup policy.
+
+### Acceptance evidence
+
+Fixture coverage proves dry runs do not write, conflicts/backups are explicit,
+repeated runs are idempotent, and every removed field is reported. The final
+0.4→0.5 user guide documents exact ordering and recovery.
+
+## D7: physical package topology
+
+### Candidate decision
+
+Do not publish `pi-forge-core` in 0.5. Establish its boundaries as enforced
+internal modules first. Publish only `@zihanw/pi-forge` and the optional
+`pi-forge-subagents` package in Phase 5. The optional package uses documented
+`@zihanw/pi-forge/subagent` host-port messages and Pi wildcard peers; it has no
+dependency on core internals, web-editor modules, or a private copy of runtime
+state. Extract core as a third package only after 0.5 if a named consumer proves
+that package boundary necessary.
+
+### Alternatives
+
+- Introduce a workspace and three published packages immediately: reject; it
+  adds package/version/build complexity before interfaces are characterized.
+- Let optional subagents import internal core modules: reject; it defeats the
+  host-port boundary.
+
+### Acceptance evidence
+
+Packed installs prove main pi-forge works with no subagent runtime/package, and
+the optional package works only through the versioned host protocol.
+
+## D8: final public surface
+
+### Candidate decision
+
+Use the public-surface register in the migration inventory as the Phase-6
+allowlist. The root default extension remains stable. `/subagent` is the sole
+versioned experimental host port. `src/*` aliases and root subagent re-exports
+are removed. Resource/catalog/loader/profile helpers become internal unless the
+consumer audit names a consumer and an intentional domain/service entry is
+accepted. Macro/slot registration remains provisional pending the immutable
+template/slot-port decision. Retain the two root documentation pointer files as
+offline redirects in the 0.5 package unless the package documentation layout
+otherwise provides a stable equivalent.
+
+### Acceptance evidence
+
+Update package exports, `files`, package checks, public-API tests, reference
+docs, changelog, and migration guide in one Phase-6 change. Test rejection of
+all removed subpaths from a packed install.
+
+## Maintainer choices required
+
+1. Accept, amend, or reject the host-RPC and `forge-v1` template spike
+   candidates.
+2. Choose D3 dedicated subagent files versus a namespaced shared config file.
+3. Choose D6 removal versus separately designed retention of `finalize` regex.
+4. Accept/amend D1, D2, D4, D5, D7, and D8 before their affected phases.

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

@@ -0,0 +1,12 @@
+# 0.5.0 full architecture proposal (archive)
+
+Status: archived 2026-08-18 as the long-term target.
+
+The active, executable 0.5.0 scope is now the [lean 0.5.0 architecture plan](../../architecture-0.5.md). The documents here were the original Phase-0 proposal and evidence base. They remain authoritative for the long-term target architecture, not for current 0.5.0 lane sequencing.
+
+- [Full 0.5 architecture plan](architecture-0.5.md) — original six-phase target and release gates.
+- [Migration inventory](0.5-inventory.md) — 0.4 surface characterization.
+- [Public-consumer audit](0.5-consumer-audit.md) — known external consumer evidence.
+- [Phase-0 decision drafts](0.5-phase0-decision-drafts.md) — original open decisions D1-D8.
+- [Template-language spike](template-language-spike.md) — evidence behind `forge-v1`.
+- [Pi host-discovery spike](host-discovery-spike.md) — evidence behind the event-bus host port.

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

@@ -0,0 +1,423 @@
+# pi-forge 0.5.0 architecture plan
+
+[Documentation](../../../README.md) · [Development rules](../../../development/architecture-rules.md) · [Roadmap](../../../development/roadmap.md)
+
+Status: proposed
+
+Date: 2026-08-17
+
+0.5 is a deliberately breaking stabilization release. Its purpose is to make the extension understandable and evolvable before adding more features. Compatibility is preserved only where it has a demonstrated consumer and does not compromise the target boundaries.
+
+## Problem statement
+
+The 0.4 implementation is well tested, but feature throughput has outpaced architectural consolidation. Prompt stacks, profiles, web editing, mutable variables, imports, payload debugging, and subagents share state and orchestration paths. Several adapters perform application or persistence work directly, and internal file-shaped exports constrain reorganization.
+
+The problem is not primarily file size. It is unclear ownership and too many ways to load, validate, mutate, compile, or present the same resources.
+
+## Release goals
+
+0.5 will:
+
+- establish a one-directional architecture with explicit domain, application, port, infrastructure, and adapter layers;
+- make a `ForgeWorkspace` the owner of coherent prompt-stack/profile resource state;
+- unify stack/profile persistence behind scoped repositories and codecs while keeping their domain models separate;
+- make prompt compilation deterministic over a normalized immutable environment;
+- remove mutable turn/session variables and render-time variable mutation;
+- replace the macro implementation only through an explicit template-engine contract, preserving a legacy reader only when migration requires it;
+- extract optional subagent integration from the main extension through a versioned host port;
+- remove or sharply reduce SillyTavern-specific functionality;
+- replace wildcard internal exports with intentional package entry points;
+- simplify commands and the web editor into adapters over shared application services.
+
+## Non-goals
+
+0.5 will not add orchestration, background agents, pipelines, retries, queues, new regex modes, richer imports, or new editor product surfaces. Sandbox and staged-write work remains deferred until the package and host boundaries are stable.
+
+The refactor does not merge profiles, stacks, and compilation into one domain object. They share infrastructure and an application facade, but retain distinct responsibilities.
+
+## Accepted architectural decisions
+
+### Breaking cleanup is preferred to indefinite compatibility
+
+0.5 may change JSON schema, public TypeScript APIs, commands, package exports, and internal storage coordination. Every user-visible break must have an explicit migration note; not every 0.4 feature requires a compatibility implementation.
+
+### Mutable variables are removed
+
+The following 0.4 behavior is removed from the 0.5 core design:
+
+- turn and session variable stores;
+- `setvar`, `setturnvar`, `setsessionvar`, and clear-variable macros;
+- variable persistence in Pi session entries;
+- the `variables` slot;
+- render-time mutation through custom macro/slot contexts.
+
+Templates receive an immutable context containing built-in runtime values. Static reusable values are retained as an immutable `parameters` object in stack schema v2; the v1 `stack.variables` string/JSON inconsistency is resolved by the v2 codec.
+
+### SillyTavern is not a core architecture driver
+
+The current fidelity-oriented importer, regex translation, report surface, command, guide, and dedicated example are removed from the core 0.5 scope.
+
+Decision: **complete removal**. 0.4 is documented as the last supported conversion path. A richer converter can later live in a separate package without shaping the prompt compiler.
+
+### Subagents become optional integration
+
+The main extension retains profile/stack resolution and prompt preparation. A separate `pi-forge-subagents` extension owns delegation configuration, tools, commands, approval/progress UI, execution adaptation, and its dependency on `@zihanw/pi-subagent-runtime`.
+
+The extraction must use a versioned Forge host port. It may not import internal runtime state, duplicate the active resource workspace, or make ordinary stack/profile usage depend on a subagent package.
+
+Confirmed decisions:
+
+- `@zihanw/pi-forge/subagent` remains a main-package entry point, but is cleaned into a versioned host port / host-neutral contract rather than re-exporting internal host preparation modules.
+- The main package removes the hard dependency on `@zihanw/pi-subagent-runtime`; that dependency moves to `pi-forge-subagents` or becomes an optional peer dependency.
+- The optional package may depend on the main package only through documented public ports.
+
+### Schemas and public APIs restart deliberately
+
+Prompt-stack schema v2 describes the cleaned compiler and template model. Agent-profile v2 is introduced only if its stored shape must change. The package no longer exports implementation modules through `src/*`; public surfaces are explicit entry points with documented stability.
+
+## Confirmed 0.5.0 planning decisions
+
+The following decisions were confirmed while this plan was in proposed status. Items still open are marked explicitly.
+
+### Architecture direction
+
+- A1: Target diagrams use port dependencies: `PromptStackService` / `AgentProfileService` depend on repository/host ports; `StackRepo` / `ProfileRepo` implement those ports.
+- A2: Add an automatic dependency-direction check (`check:architecture`) during Phase 1/2.
+- A3: When `src/*` exports are removed, update `scripts/check-package.mjs`, `docs/reference/public-api.md`, and public-API tests in the same change.
+- A4: The release is referred to consistently as 0.5.0.
+
+### Component ownership
+
+- B1: `@zihanw/pi-forge/subagent` remains in the main package as a versioned host port / host-neutral contract, but its internal implementation surface is cleaned.
+- B2: Remove the main package hard dependency on `@zihanw/pi-subagent-runtime`.
+- B3: Forge extension loading/unloading and registry coordination are owned by `ForgeWorkspace`.
+- B4: Tool-policy synchronization is defined as a port (`ToolPolicyPort`), called by `PromptStackService`; Pi adapter implements it.
+- B5: Debug/payload/browser presentation state is a separate state slice, not part of the `ForgeWorkspace` resource snapshot.
+
+### Schema and feature decisions
+
+- B6: SillyTavern is removed completely from 0.5.0 core; 0.4 is the last supported conversion path.
+- B7: Template language is still open; it will be decided after a spike.
+- B8: Static reusable values are retained as immutable `parameters` in stack schema v2; the v1 `variables` codec inconsistency is fixed in v2.
+- B9: Cross-extension host discovery will be decided after a focused spike; no final mechanism is assumed yet.
+
+### Process decisions
+
+- C1: Phase 0 produces an explicit inventory deliverable (for example `docs/design/0.5-inventory.md` or a comparable checklist).
+- C2: Chinese documentation is updated for user-facing breaking changes; internal architecture documentation is not required to be fully synchronized.
+- C3: No formal owner field is used; maintainer and agents together drive and review decisions.
+
+## Current 0.4 architecture
+
+```mermaid
+flowchart TB
+    Pi["Pi host"] --> Entry["index.ts composition root"]
+    Entry --> Lifecycle["Lifecycle"]
+    Entry --> StackRuntime["Stack runtime"]
+    Entry --> ProfileRuntime["Profile runtime"]
+    Entry --> PolicyRuntime["Policy runtime"]
+    Entry --> WebRuntime["Web-editor runtime"]
+    Entry --> SubRuntime["Subagent runtime"]
+
+    State[("Shared PiForgeRuntimeState")]
+    Lifecycle --> State
+    StackRuntime --> State
+    ProfileRuntime --> State
+    PolicyRuntime --> State
+    WebRuntime --> State
+    SubRuntime --> State
+
+    StackRuntime --> StackLoader["Stack loader + validation"]
+    ProfileRuntime --> ProfileLoader["Profile loader + resolution"]
+    ProfileRuntime --> StackRuntime
+    StackRuntime --> ProfileRuntime
+
+    Lifecycle --> Compiler["Compiler"]
+    Compiler --> Macros["Stateful macros + variables"]
+    Compiler --> Slots["Slot registry"]
+    Compiler --> Regex["Regex transforms"]
+
+    WebRuntime --> WebHost["Web host"]
+    WebHost --> DirectIO["Direct stack filesystem mutations"]
+    WebHost --> ProfileService["Profile service"]
+    WebHost --> SubRuntime
+
+    SubRuntime --> SubHost["Forge host preparation"]
+    SubHost --> Compiler
+    SubRuntime --> ExternalRuntime["pi-subagent-runtime"]
+```
+
+The high-risk connections are shared state ownership, circular stack/profile coordination, direct persistence in adapters, and optional subagent concerns reaching the core editor and composition root.
+
+## Target package and component architecture
+
+```mermaid
+flowchart TB
+    subgraph Main["@zihanw/pi-forge"]
+        PiAdapters["Pi lifecycle + command adapters"]
+        WebAdapters["HTTP + browser adapters"]
+        Workspace["ForgeWorkspace"]
+        StackService["PromptStackService"]
+        ProfileService["AgentProfileService"]
+        PiPorts["Pi runtime/environment adapters"]
+
+        PiAdapters --> Workspace
+        WebAdapters --> Workspace
+        Workspace --> StackService
+        Workspace --> ProfileService
+        ProfileService --> StackService
+    end
+
+    subgraph Core["@zihanw/pi-forge-core"]
+        ResourceCore["Scoped resources + catalogs"]
+        StackDomain["Prompt-stack schema + codec"]
+        ProfileDomain["Agent-profile schema + codec"]
+        Compiler["PromptCompiler"]
+        Templates["TemplateEngine registry"]
+        Diagnostics["Common diagnostics"]
+        Ports["Repository + host ports"]
+
+        Compiler --> StackDomain
+        Compiler --> Templates
+        StackDomain --> ResourceCore
+        ProfileDomain --> ResourceCore
+    end
+
+    subgraph Infra["Main extension infrastructure"]
+        StackRepo["PromptStackRepository"]
+        ProfileRepo["AgentProfileRepository"]
+        AtomicFiles["Atomic scoped file store"]
+
+        StackRepo --> AtomicFiles
+        ProfileRepo --> AtomicFiles
+    end
+
+    StackService --> StackDomain
+    StackService --> Compiler
+    StackService --> Ports
+    ProfileService --> ProfileDomain
+    ProfileService --> Ports
+    PiPorts --> Ports
+    StackRepo -.->|implements| Ports
+    ProfileRepo -.->|implements| Ports
+
+    subgraph Optional["pi-forge-subagents"]
+        SubAdapters["Commands + tools + approval UI"]
+        SubHost["ForgeHostPort client"]
+        SubRuntime["pi-subagent-runtime"]
+
+        SubAdapters --> SubHost
+        SubAdapters --> SubRuntime
+    end
+
+    Workspace -. "versioned host capability" .-> SubHost
+```
+
+`pi-forge-core` is host-neutral: it does not import the Pi extension API, HTTP, browser, TUI, or subagent runtime. If physical package extraction would delay boundary work, the same structure may land first as enforced internal modules and become a package before the subagent split.
+
+## Target responsibilities
+
+### ForgeWorkspace
+
+- Own one immutable workspace snapshot containing scoped stack/profile catalogs and active selection/provenance references.
+- Own Forge extension loading/unloading and registry coordination; coordinate resource reload and snapshot publication without circular runtime callbacks.
+- Expose application services and resource-change subscriptions to adapters.
+- Keep payload debugging and browser presentation state outside the resource snapshot.
+
+### PromptStackService
+
+- List, resolve, validate, create, update, fork, delete, activate, preview, and compile stacks.
+- Own auto-activation selection and active-stack state transitions.
+- Coordinate tool-policy changes through a `ToolPolicyPort` rather than calling UI, Pi API, or persistence code directly.
+
+### AgentProfileService
+
+- List, resolve, validate, create, update, delete, preflight, apply, and report provenance/drift.
+- Apply model, thinking, and stack transactionally through a runtime-controller port.
+- Resolve stack references through the workspace catalog, not through a separate loader.
+
+### Repositories and codecs
+
+- Repositories implement scoped discovery and safe mutation.
+- Codecs are the only schema parsing, normalization, validation, serialization, and fingerprint source.
+- Updates/deletes carry expected fingerprints to prevent overwriting unseen external changes.
+- Filesystem writes use atomic replacement where the platform permits it.
+
+### PromptCompiler and TemplateEngine
+
+- Consume a normalized immutable `PromptEnvironment`, not a live Pi context.
+- Return system prompt, prepared messages, sources, diagnostics, template dependencies, and an explicit variable/parameter receipt if parameters are retained.
+- Keep history placement, structured runtime slots, tool/skill selection, and outgoing deterministic transforms as separate compiler stages.
+- Use an engine contract with parse, analyze, and render operations. A restricted Jinja-like engine is a candidate, not yet an accepted dependency.
+
+### Adapters
+
+- Parse external input and render typed service results.
+- Contain no resource persistence or duplicated schema validation.
+- Browser view models and HTTP status mapping remain outside application/domain state.
+
+## Proposed source layout
+
+The exact filenames may evolve, but ownership should converge on:
+
+```text
+packages/
+  core/
+    src/resources/
+    src/prompt-stacks/
+    src/profiles/
+    src/compiler/
+    src/templates/
+    src/ports/
+  pi-forge/
+    src/application/
+    src/infrastructure/
+    src/adapters/pi/
+    src/adapters/commands/
+    src/adapters/web/
+  pi-forge-subagents/
+    src/host/
+    src/runtime/
+    src/adapters/commands/
+    src/adapters/tools/
+```
+
+Moving to a workspace is an implementation choice, not permission to move files before their interfaces and ownership are characterized.
+
+## Feature disposition
+
+| 0.4 capability | 0.5 disposition |
+|---|---|
+| Ordered prompt blocks and runtime slots | Keep and move into the v2 compiler |
+| Scoped global/project resources | Keep behind common repositories/catalogs |
+| Tool policy and model-visible skill filtering | Keep stack-owned |
+| One-shot profiles, transactional apply, provenance, drift | Keep in `AgentProfileService` |
+| Web stack/profile editor | Keep as adapters over services; simplify during migration |
+| Prompt preview and redacted payload debugging | Keep; isolate debugging state |
+| Turn/session variables and mutation macros | Remove |
+| Static stack variables | Keep as immutable `parameters` in schema v2; fix the v1 string/JSON codec inconsistency |
+| Current custom macro API | Break and replace with the template/slot extension contract |
+| SillyTavern fidelity importer and regex emulation | Remove completely; 0.4 is the last supported conversion path |
+| Regex history/compiled transforms | Keep initially; no new modes during 0.5 |
+| Destructive finalized-transcript regex | Audit separately before schema v2 is frozen |
+| Foreground subagent integration | Move to optional `pi-forge-subagents`; `@zihanw/pi-forge/subagent` remains as a versioned host port/contract |
+| `src/*` package exports | Remove; update `check-package.mjs`, public API docs/tests in the same change |
+| Legacy prompt-stack storage migration command | Remove after documenting the required pre-0.5 migration path |
+
+## Implementation phases
+
+### Phase 0: freeze and characterize
+
+- Announce the 0.5 feature freeze in repository guidance and roadmap.
+- Produce an explicit inventory deliverable covering public exports, persisted entries, commands, schemas, examples, and real internal consumers.
+- Add characterization tests around any behavior that will move before changing ownership.
+- Run the template-language spike and cross-extension host-discovery spike; record their findings before the affected phases start.
+- Decide the remaining implementation gates listed under open decisions.
+
+Exit: the removal/migration inventory is reviewed, and no unplanned feature work is in flight.
+
+### Phase 1: resource core and repositories
+
+- Introduce common diagnostic and loaded-resource envelopes.
+- Extract stack/profile codecs.
+- Implement repository ports and guarded filesystem repositories.
+- Add the automatic dependency-direction check (`check:architecture`) so adapter/domain boundaries are enforced from this phase onward.
+- Move all stack mutations out of `web-host.ts` and import commands.
+
+Exit: every domain resource mutation uses a repository and has consistent stale-write/path-safety behavior.
+
+### Phase 2: application services and workspace
+
+- Consolidate stack operations into `PromptStackService`.
+- Consolidate profile operations into `AgentProfileService`.
+- Introduce `ForgeWorkspace` and publish coherent reload snapshots.
+- Split debug/browser state away from resource state into a separate state slice.
+- Replace circular stack/profile runtime wiring with workspace-owned services and ports.
+
+Exit: commands, lifecycle, and web host use services; `PiForgeRuntimeState` is removed or reduced to adapter-owned state with no domain ownership.
+
+### Phase 3: compiler and schema v2
+
+- Define normalized `PromptEnvironment`, compiler result, and template-engine contracts.
+- Remove mutable variables and session variable persistence.
+- Select and implement the v2 template syntax.
+- Make template dependency analysis authoritative.
+- Decide the retained regex surface and freeze prompt-stack schema v2.
+
+Exit: compilation is deterministic over immutable inputs, previews and runtime use the same entry point, and v1-to-v2 migration behavior is documented and tested.
+
+### Phase 4: adapter cleanup
+
+- Reduce Pi lifecycle modules to event adaptation.
+- Reduce commands and HTTP handlers to parsing/result rendering.
+- Split web view-model construction from application workflows.
+- Remove SillyTavern surfaces from commands, web editor, docs, examples, and tests; update Chinese user docs for user-facing breaking changes.
+
+Exit: dependency checks show adapters pointing inward with no direct resource persistence.
+
+### Phase 5: subagent extraction and packages
+
+- Validate cross-extension capability discovery with a focused spike.
+- Publish the versioned Forge host port and clean `@zihanw/pi-forge/subagent` into that stable surface.
+- Remove the main package hard dependency on `@zihanw/pi-subagent-runtime`.
+- Move subagent configuration, commands, tools, UI, and runtime adaptation into `pi-forge-subagents`.
+- Ensure main pi-forge installs and runs without subagent dependencies.
+- Remove subagent UI/configuration from the core web editor unless an explicit contribution port is accepted.
+
+Exit: ordinary stacks/profiles have no dependency on the optional package, and the optional extension consumes only documented public ports.
+
+### Phase 6: public surface and release
+
+- Replace root re-export sprawl with explicit package entry points.
+- Remove `src/*` aliases and 0.4 compatibility barrels; update `check-package.mjs`, public API docs, and public API tests in the same change.
+- Complete migration guide, changelog, package checks, and documentation rewrite; use 0.5.0 naming consistently.
+- Run packed-install tests against supported Pi versions with and without `pi-forge-subagents`.
+
+Exit: all release gates below pass.
+
+## Open implementation-gate decisions
+
+These are the remaining decisions that must be resolved before their affected implementation phases begin:
+
+1. **Template language (spike completed; decision pending):** the Phase-0 [template-language spike](template-language-spike.md) rejects a broad Jinja-like engine and recommends a closed `forge-v1` AST grammar. Accept the exact grammar, environment schema, filter/condition set, extension-port disposition, schema representation, and migration behavior before Phase 3.
+2. **Static parameters (decided):** retain a JSON-compatible immutable `parameters` object in stack schema v2; do not remove static reusable values.
+3. **SillyTavern migration (decided):** complete removal; 0.4 is the last supported conversion path. No converter is retained in 0.5.0 core.
+4. **Cross-extension host discovery (spike completed; decision pending):** the Phase-0 [Pi host-discovery spike](host-discovery-spike.md) validated Pi's shared in-process event bus across both extension load orders. It recommends a versioned, session-scoped event-bus RPC port with explicit duplicate-host detection and disposal; accept the protocol, operation catalogue, and package versioning before Phase 5.
+5. **Pi session custom-entry versioning (open):** define explicit version, restoration, branch-navigation, malformed-entry, and migration semantics for prompt-stack selection and profile provenance entries. Define how removed variable entries are handled without recreating mutable state. Resolve before Phase 2/3 changes session restoration.
+6. **Configuration ownership after subagent extraction (open):** `webEditor.*` remains owned by the main package. Decide whether `subagents.*`, which must be owned and written only by `pi-forge-subagents`, remains a namespaced section of `.pi/forge/config.json` or moves to dedicated optional-package configuration files; include migration and behavior when the optional package is absent. Resolve before Phase 4/5 changes configuration adapters.
+7. **Final public-surface classification (open):** before Phase 6, use the Phase-0 inventory to classify every root and subpath surface as stable, experimental, internal, or removed; record named consumers, target entry points, and migration notices. Phase 6 must implement this accepted register rather than decide exports during removal.
+8. **Pi compatibility policy (open):** define the minimum supported Pi version and rolling tested-version release matrix separately from wildcard host peers. Include packed main-only and main-plus-optional-package tests, plus a release-time npm `latest` probe. Resolve before Phase 1 establishes the supported CI matrix.
+
+## Migration policy
+
+- Provide a v1-to-v2 stack migration command or standalone script for mechanically convertible fields.
+- Mutable variable behavior that cannot be preserved becomes an explicit migration diagnostic, not a silent approximation.
+- Recommend running the final 0.4 release to convert legacy `.pi/prompt-stacks` storage before upgrading if 0.5 removes that migration command.
+- Agent profiles retain IDs and scoped stack references where possible; migration rewrites only schema fields that actually change.
+- SillyTavern users must convert with 0.4 before upgrading; 0.5.0 core does not retain a converter.
+- No compatibility shim is accepted without a named consumer, test, warning/removal version, and owner.
+
+## Release gates
+
+0.5 is ready only when:
+
+- dependency direction is checked automatically;
+- all resource persistence is repository-owned;
+- workspace reload and profile application have transactional/integration coverage;
+- runtime and preview compilation share one compiler entry point;
+- mutable variables and their persisted entries are removed or explicitly migrated;
+- schema v2 and public entry points are documented without `src/*` exports;
+- main pi-forge passes verification without installing the subagent extension/runtime;
+- the optional subagent package passes host-version, preparation, approval, cancellation, and packed-install tests;
+- current and target architecture diagrams match the implementation;
+- English user documentation is updated and Chinese user-facing documentation is updated for breaking changes (internal architecture docs are not required to be fully synchronized);
+- `npm run verify` and packed-install smoke tests pass on the documented Pi compatibility range.
+
+## Deferred until after 0.5
+
+- New prompt composition features.
+- New import formats or high-fidelity external-preset emulation.
+- Sandbox and staged subagent writes.
+- Background/resumable agents, chains, queues, or orchestration.
+- New web-editor surfaces unrelated to the migration.
+- Additional regex or transcript-rewriting behavior.