@zihanw/pi-forge 0.4.1 → 0.5.1

package/docs/design/0.5.1-plan.md

@@ -0,0 +1,237 @@
+# pi-forge 0.5.1 — Combined Release Plan
+
+Status: active. Target release: 0.5.1 (first feature release after 0.5.0).
+Owner of truth: this document. Supersedes/folds in:
+- `docs/design/context-diff-plan.md` (context diff, now Lane 2)
+- The subagent UI-contribution discussion from the 0.5.x review thread (now Lane 1)
+
+Theme: **observability + subagent usability**. 0.5.0 was the architecture-split
+release; 0.5.1 ships per-turn prompt observability and makes the optional
+subagent package configurable without hand-editing JSON.
+
+## Lane ordering (deliberate)
+
+**Lane 1 ships first.** Its tab-registry refactor turns the web editor's tab
+system data-driven, which Lane 2's Preview dock builds on. Both lanes touch the
+client build pipeline and the tab area — do not run them in parallel in the
+same working tree.
+
+---
+
+## Lane 1 — UI contribution framework + subagent config UI
+
+### Goal
+
+Let the optional `@zihanw/pi-forge-subagents` package own its configuration UI
+(schema, validation, defaults, file writes) while the rendered settings tab
+appears inside the pi-forge web editor when — and only when — the subagent
+package is installed.
+
+Non-goal: arbitrary JS/component injection into the forge web UI. The event bus
+carries JSON only; that rule does not bend for UI.
+
+### Architecture (schema-driven contribution, "plan A")
+
+```
+┌─ pi-forge-subagents ─────────────┐         ┌─ pi-forge ─────────────────┐
+│ UI contribution provider:        │  bus    │ web host discovers provider │
+│  · getContribution() → { tabId,  │ ◄────── │ at startup (capability      │
+│    title, icon, schema, values } │  JSON   │ negotiation)                │
+│  · writeValues(patch) → validate │ ──────► │ generic schema-form tab     │
+│    + write subagents.json        │         │ (self-contained Vue comp.)  │
+└──────────────────────────────────┘         │ PUT /api/contrib/<id> proxy │
+                                             └─────────────────────────────┘
+```
+
+- **Contribution protocol**: new versioned port, separate version counter from
+  the v1 host port. All payloads are plain recursively-validated JSON (schema +
+  values), same discipline as `host-port.ts`.
+- **Forge side** is fully generic: it knows nothing about subagents. No
+  provider discovered → no contributed tab, zero cost.
+- **Config ownership stays put**: `subagents.json` (project/global + legacy
+  fallback) remains owned and written by the subagent package. Forge's web
+  server only proxies the bus call.
+
+### Forge-side changes (~1.5–2d)
+
+1. Tab registry: replace the hardcoded `"policy" | "regex" | "stack"` union in
+   `vue-tab-host.ts` with a data-driven registry (string tab ids, dynamic
+   buttons in `App.vue`).
+2. Generic schema-form renderer: self-contained Vue component, bridged via the
+   vue-host mechanism. Restricted field types for v1: boolean, number, enum,
+   string, plus a record/table shape for per-profile entries. **Do NOT add
+   imperative code to `legacy-editor.ts`.**
+3. Web server: `PUT /api/contrib/<tabId>` route proxying `writeValues` over the
+   bus; contribution descriptors fetched at page load through `/api/contrib`.
+4. Contribution discovery: web host acts as client toward the provider port;
+   tolerate provider disappear/reappear across sessions.
+
+### Subagents-side changes (~1d)
+
+1. Provider endpoint implementing the contribution protocol.
+2. `ForgeSubagentSettings` → schema mapping (backend, timeoutMs,
+   approval flag, summary-in-description flag, per-profile
+   enabled/backend/timeout table).
+3. Server-side re-validation on write, reusing existing validators
+   (`isValidSubagentTimeoutMs` et al.). Never trust the web client.
+4. TUI companion: `/forge-agent config` subcommand for the same settings
+   (internal to the package, no cross-repo coordination).
+
+### Known v1 limitation
+
+Pure schema cannot express "dropdown fed by live forge data" (e.g. a profileId
+picker backed by `listProfiles`). v1: plain text input + validation errors.
+v2 candidate: a "remote data source" field type. Do not gold-plate v1.
+
+### Lane 1B — subagent call-time UX (subagents package only)
+
+Two usability extras that live entirely in `@zihanw/pi-forge-subagents`; no
+forge-side coupling, safe to build in parallel with the forge contribution
+framework.
+
+**1. Call-time model override** (~0.5d)
+
+Main agent may pick the execution model per `forge_subagent` call; default
+remains the profile's model. Feasibility already verified: the wire carries
+model facts (`ForgeBackendFacts.model`, `ForgePrepareResponse.model`), and the
+pi-subagent-runtime subprocess backend already spawns with `--model` — only
+the tool surface lacks the knob.
+
+- Add optional `model` parameter (`provider/id` string, parsed + validated) to
+  `ForgeSubagentParameters`.
+- Resolution order: `model` param > profile default.
+- Same policy as the `backend` param: override allowed for interactively
+  approved runs; unattended invocation is pinned to the profile/configured
+  model.
+- Approval summary's existing `Model:` line shows the effective model for free.
+- Update tool description accordingly.
+
+**2. Restore rich TUI rendering for subagent runs** (~0.5–1d)
+
+The 0.4 tool shipped `renderCall`/`renderResult` (pi-tui Container/Markdown,
+collapsed/expanded states, live progress, usage stats); the 0.5 split dropped
+them, falling back to the default tool display. Streaming infrastructure is
+still intact (`onUpdate` progress pushes, `details.progress` ring buffer at
+`MAX_PROGRESS_ITEMS`).
+
+- Port the 0.4.1 renderers from git history (`v0.4.1:src/subagent-tool.ts`)
+  into `forge-subagent.ts`, adapted to the current details shape and including
+  the approval receipt.
+- `@earendil-works/pi-tui` is already an optional peer dependency.
+- Reference the historical render tests where recoverable.
+
+---
+
+## Lane 2 — Context diff (folded from context-diff-plan.md)
+
+### Goal
+
+Per-turn observability for prompt changes so users can optimize KV-cache reuse:
+
+- Mark which blocks of the prompt changed after each turn.
+- Show token delta (added/removed/modified) vs the previous turn.
+- Mark where the KV-cache prefix survives ("cache boundary").
+
+Secondary goal: merge with live preview — while editing a stack,
+debounce-compile and diff against the previous compile, so edits show their
+prompt/token impact immediately.
+
+### Existing building blocks
+
+- `src/payload-capture.ts` — real provider request payload (secret-redacted),
+  with deliberately rough `approxTokens` (chars/4).
+- Pi's authoritative assistant `message_end` usage — input, output, cache read,
+  and cache write token buckets correlated FIFO with captured provider requests.
+- `src/preview.ts` — edit-time compile output split into sections (system +
+  per-message), each with chars/approxTokens.
+- Legacy editor already polls payload state every 2s.
+
+### Two data sources
+
+| Scenario | Source | Question answered |
+|---|---|---|
+| Edit time (live preview merge point) | debounced compile vs previous compile | "what does this edit change, how many tokens" |
+| Run time (request structure) | diff of consecutive real payloads | "where would the reusable serialized prefix end, and what changed" |
+| Run time (provider truth) | correlated assistant usage | "how many prompt tokens and cache reads/writes did the provider report" |
+
+### Core engine: `src/context-diff.ts` (host-neutral pure functions)
+
+```
+TurnSnapshot  { turnId, capturedAt, stackId, blocks: Block[] }
+Block         { key, role, text, chars, approxTokens, hash }
+TurnDiff      { blocks: DiffBlock[], prefixTokens, prefixRatio, deltaTokens, summary }
+DiffBlock     { status: same|added|removed|modified, before?, after?, tokenDelta }
+```
+
+Cache-boundary algorithm: KV-cache hits depend on the longest common prefix of
+the serialized request. Walk the block arrays in order while hashes match; at
+the first mismatch, trim a char-level common prefix inside that block and
+convert to tokens. Render a boundary marker: "cache valid up to ~18,204 tokens
+(63% of prompt)". No Myers diff needed — prefix + block classification
+suffices.
+
+Honesty note: diff token figures remain chars/4 estimates and are always labeled
+as such. Provider prompt/cache usage is displayed separately. Cache hit rate is
+`cacheRead / (input + cacheRead + cacheWrite)` only after cache activity has
+been observed for that provider/model; an all-zero normalized cache bucket is
+otherwise reported as unavailable because it cannot distinguish a true miss
+from a provider that did not report cache detail.
+
+### UI
+
+Promote the Preview modal into a dockable right-side panel with three tabs:
+
+- **Compiled** — current preview content, auto-refresh with 500ms debounce
+  while editing (this is the live preview).
+- **Draft diff** and **Run diff** — git-style unified/split line views with
+  old/new line numbers, inline changed spans, and selectable changes-only,
+  three-line, or full context. Run metadata keeps estimated reusable prefix
+  separate from actual provider usage and cache-hit rate.
+
+Run-time mode: payload poll captures a new payload → rolling history (last 20
+turns) → auto-compute diff.
+Edit mode: diff current edited compile vs the active on-disk version.
+
+Implementation constraint: self-contained Vue component bridged via the
+vue-host mechanism, riding Lane 1's data-driven dock/tab registry. Do NOT add
+more imperative code to `legacy-editor.ts`. Do NOT refactor the legacy editor
+in the same lane.
+
+### Phases / estimate
+
+| Phase | Content | Effort |
+|---|---|---|
+| 0 | Design freeze + golden fixtures (turn payload sets) | 0.5d |
+| 1 | `context-diff.ts` engine + unit tests (prefix/add/remove/modify/token rollups) | 1d |
+| 2 | Server endpoint + rolling snapshot state on the web host | 0.5d |
+| 3 | Web UI: preview dock + Diff view (self-contained Vue, bridged, on Lane 1's registry) | 1.5d |
+| 4 | Browser tests + docs + changelog | 0.5–1d |
+
+Lane 2 total ~4–5 working days. Descope option (~3d): run-time diff only,
+live preview reduced to plain auto-refresh without edit-time diffing.
+
+---
+
+## Combined estimate
+
+| Lane | Content | Effort |
+|---|---|---|
+| 1 | UI contribution framework (forge) + provider & config UI (subagents) | ~2.5–3d |
+| 1B | Call-time model override + rich TUI restore (subagents only) | ~1–1.5d |
+| 2 | Context diff engine + dock UI | ~4–5d |
+
+~8.5–9.5 working days total, ~2 calendar weeks with review. Both lanes require
+coordinated releases: forge 0.5.1 must understand the contribution protocol
+before (or simultaneously with) subagents 0.5.1 advertising it — the
+capability negotiation makes order-independent rollout safe. Lane 1B lives
+entirely in subagents 0.5.1 and ships with it; the promo should present both
+packages together.
+
+## Release narrative
+
+0.5.1 headlines "observability + subagent UX". The promo video leads with the
+context diff money shot (edit one system-prompt line, watch the cache-boundary
+marker jump). Promo pipeline follows the AIGC/VIDEO_PRODUCTION ep02 reference:
+`PLAN.md` → script draft → `narration.json` → roughcut → review; terminology
+rule: plain words first, formal term named once ("KV cache" on first mention,
+then "prefix cache / cache reuse region").

package/docs/design/README.md

@@ -1,8 +1,26 @@
-# Design archive
+# Architecture and design
 
 [Documentation](../README.md)
 
-These documents preserve decisions, reviews, spikes, and implementation history. They are not the authoritative description of current user behavior; use the [guides](../README.md#guides) and [reference](../README.md#reference) for that.
+The active plan defines the executable forward-looking work. Archived documents preserve the long-term target, decisions, reviews, spikes, and implementation history; they are not the authoritative description of current user behavior. Use the [guides](../README.md#guides) and [reference](../README.md#reference) for released behavior.
+
+## Active 0.5.0 plan
+
+- [Lean 0.5.0 architecture plan](architecture-0.5.md) — executable breaking-cleanup scope, accepted decisions, implementation lanes, and release gates.
+- [Architecture and development rules](../development/architecture-rules.md) — dependency direction and ownership rules for the full target.
+- [Architecture decision template](decision-template.md) — structure for future boundary/product decisions.
+
+## Archived 0.5 full proposal
+
+The original six-phase target remains the long-term goal and is preserved here:
+
+- [Full proposal index](archive/0.5-full-proposal/README.md)
+- [Full 0.5 architecture plan](archive/0.5-full-proposal/architecture-0.5.md)
+- [Migration inventory](archive/0.5-full-proposal/0.5-inventory.md)
+- [Public-consumer audit](archive/0.5-full-proposal/0.5-consumer-audit.md)
+- [Phase-0 decision drafts](archive/0.5-full-proposal/0.5-phase0-decision-drafts.md)
+- [Template-language spike](archive/0.5-full-proposal/template-language-spike.md)
+- [Pi host-discovery spike](archive/0.5-full-proposal/host-discovery-spike.md)
 
 ## Subagent design history
 
@@ -14,4 +32,4 @@ These documents preserve decisions, reviews, spikes, and implementation history.
 
 - [0.4 roadmap and implementation log](roadmap-0.4-archive.md)
 
-The current exported semantics are in the [subagent adapter contract](../reference/subagent-adapter.md); forward-looking work is in the [roadmap](../development/roadmap.md).
+The 0.5 host boundary is in the [subagent host port contract](../reference/subagent-host-port.md); accepted work ordering is in the [roadmap](../development/roadmap.md).

package/docs/design/architecture-0.5.md

@@ -0,0 +1,222 @@
+# 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.
+
+## Accepted 0.5.1 amendment: generic settings contributions
+
+Dogfooding invalidated decisions 10 and 12 as forward-looking constraints, while preserving their 0.5.0 historical outcome. The accepted 0.5.1 amendment is:
+
+1. `@zihanw/pi-forge/ui-contribution` is a fourth intentional, experimental entry point. It is a generic, versioned, data-only event-bus port; main pi-forge owns the renderer and HTTP proxy but has no subagent-specific schema or persistence logic.
+2. Optional packages may contribute restricted schema-driven Settings pages. Schemas and values are recursively validated JSON data; provider handlers may be asynchronous and receive generation-bound cancellation before side effects.
+3. `pi-forge-subagents` remains the sole owner of both `subagents.json` files. It obtains profile choices only through `/subagent`, contributes plain settings descriptors through `/ui-contribution`, and performs all subagent validation and persistence itself.
+4. This amendment does not authorize a general plugin UI/component runtime, arbitrary browser code, a second resource registry, or main-package reads/writes of optional-package configuration.
+
+## 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"]
+    WebEditor["Generic Settings renderer"] -. "UI contribution port v1" .-> Optional
+    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.
+- UI contribution port passes schema validation, async generation cancellation, provider churn, and packed optional-consumer tests.
+- 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 and arbitrary contributed UI components;
+- 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.