feat: package Pi extensions as Bun workspaces

2026-09-01 17:24:46 -04:00
parent 90f8090f61
commit 118b5bee06
214 changed files with 19566 additions and 5876 deletions
@@ -2,9 +2,9 @@
 status: accepted
 ---

-# Build pi-workflow around persisted policy gates
+# Build workflow around persisted policy gates

-`pi-workflow` will be a new extension rather than an activation or rename of `_workflows`. It will expose one command-style tool backed by atomic revisioned snapshots, Markdown Agent Profiles, deterministic eligibility followed by planner selection, a mandatory feature pipeline, and restricted feature or read-only analysis scripts. Every feature run receives a distinct exclusive worktree. Concurrency defaults to 8 under an immutable process-wide maximum of 32. Non-trivial UI work requires at least three structurally distinct prototypes and explicit user acceptance. Before implementation, the user chooses a fresh plan-seeded session, compaction of the current session that prefers `smart_compact` and falls back to normal Pi compaction when unavailable, or unchanged current context. Review uses a fresh session and excludes every Agent Profile that mutated the reviewed diff.
+`workflow` will be a new extension rather than an activation or rename of `_workflows`. It will expose one command-style tool backed by atomic revisioned snapshots, Markdown Agent Profiles, deterministic eligibility followed by planner selection, a mandatory feature pipeline, and restricted feature or read-only analysis scripts. Every feature run receives a distinct exclusive worktree. Concurrency defaults to 8 under an immutable process-wide maximum of 32. Non-trivial UI work requires at least three structurally distinct prototypes and explicit user acceptance. Before implementation, the user chooses a fresh plan-seeded session, compaction of the current session that prefers `smart_compact` and falls back to normal Pi compaction when unavailable, or unchanged current context. Review uses a fresh session and excludes every Agent Profile that mutated the reviewed diff.

 This keeps the caller interface small while making approval, prototype, recovery, and reviewer-independence rules enforceable in one workflow engine. We rejected unrestricted custom graphs because they could bypass policy, a general registry architecture because it adds speculative extension points, and event-sourced persistence because revisioned snapshots already provide the required recovery and audit data with less machinery.

@@ -1,3 +0,0 @@
-# Reuse standard agents through workflow role overlays
-
-`pi-workflow` will reuse standard `pi-interactive-subagents` definitions instead of duplicating their prompts and model settings in workflow-only agents. Explicit configuration maps standard agent names to workflow roles, while `pi-workflow` retains ownership, tool-intersection, Gate, verification, and reviewer-independence policy. The default maps `scout` to Discovery and `worker` to Implementation; bundled profiles remain fallbacks for roles without a standard mapping. This keeps one source of truth for agent identity without allowing arbitrary prompt prose or agent names to imply mutability or workflow authority.
@@ -1,11 +1,11 @@
 ---
 status: accepted
-supersedes: 0001-pi-workflow-architecture-24AUG2026.md
+supersedes: 0001-workflow-architecture-24AUG2026.md
 ---

 # Use drill-down overlays and bounded recovery

-This decision supersedes the dashboard, dirty-source, execution-timeout, and startup-ownership assumptions in [ADR 0001](./0001-pi-workflow-architecture-24AUG2026.md). The persisted gated pipeline, worktree isolation, and independent-review decisions from ADR 0001 remain accepted.
+This decision supersedes the dashboard, dirty-source, execution-timeout, and startup-ownership assumptions in [ADR 0001](./0001-workflow-architecture-24AUG2026.md). The persisted gated pipeline, worktree isolation, and independent-review decisions from ADR 0001 remain accepted.

 ## Context

@@ -39,7 +39,7 @@ Static prototypes compared a centered compact modal, a near-full-screen workspac
 - Dead ownership can recover without manual state surgery. A running process or Assignment cannot be displaced based only on an old heartbeat.
 - Users may proceed from a dirty source checkout without copying local changes into the worktree. Persisted evidence records what was knowingly omitted.
 - Git, host-command cleanup, and child execution now have bounded failure paths rather than indefinite waits.
- Direction C has automated renderer and orchestration coverage. Its completed manual application validation is recorded below. The static frames in `docs/pi-workflow/dashboard-mocks.md` remain labeled prototype evidence, not production screenshots.
+- Direction C has automated renderer and orchestration coverage. Its completed manual application validation is recorded below. The static frames in `docs/workflow/dashboard-mocks.md` remain labeled prototype evidence, not production screenshots.

 ## Manual application validation

@@ -0,0 +1,3 @@
+# Reuse standard agents through workflow role overlays
+
+`workflow` will reuse standard `pi-interactive-subagents` definitions instead of duplicating their prompts and model settings in workflow-only agents. Explicit configuration maps standard agent names to workflow roles, while `workflow` retains ownership, tool-intersection, Gate, verification, and reviewer-independence policy. The default maps `scout` to Discovery and `worker` to Implementation; bundled profiles remain fallbacks for roles without a standard mapping. This keeps one source of truth for agent identity without allowing arbitrary prompt prose or agent names to imply mutability or workflow authority.
@@ -0,0 +1,21 @@
+# Package Pi extensions as a Bun workspace catalog
+
+## Decision
+
+Keep extension sources under `extensions/*` and make each maintained extension directory a Bun workspace with its own package manifest. Use the `@_jb/pi-*` namespace, a root Bun catalog for external dependency versions, and `workspace:^` for repository-owned libraries. The repository root is private and is no longer itself a Pi package.
+
+Publish packages to the `jb` owner endpoint of the Gitea npm registry. Repository configuration maps `@_jb` to `https://git.jb.codes/api/packages/jb/npm/`; credentials remain in the user environment or user-level npm configuration and are never committed.
+
+`extensions/shared` is the publishable `@_jb/pi-shared` library. Extensions that import it declare a normal runtime dependency so Pi's production package installation receives the required code.
+
+`extensions/_workflows` is reference code, not a package or publishable extension. `@_jb/pi-workflow` remains a private workspace until the required reference runtime is merged under `extensions/workflow`; this prevents publishing two workflow packages or publishing an incomplete package.
+
+The existing `config/pi-links.json` policy remains the authority for live-development exposure. Package boundaries and publication do not automatically enable extensions globally.
+
+## Consequences
+
+- Bun owns dependency installation and `bun.lock`; `package-lock.json` is removed.
+- Catalog and workspace protocols require `bun publish` or `bun pm pack` before npm publication so concrete versions are written into package metadata.
+- Shared libraries must be published before extensions that depend on the same new version.
+- Pi packages continue shipping TypeScript source because Pi loads extension entrypoints directly.
+- The `workflow` merge is an explicit blocker for its first release.
@@ -0,0 +1,25 @@
+# Import external Pi packages as reviewed main-branch snapshots
+
+## Decision
+
+Import the tracked files from the `main` branch of these repositories into Bun workspaces:
+
+| Source | Imported commit | Workspace | Package |
+| --- | --- | --- | --- |
+| `jb/pi-interactive-subagents` | `a3cd328edef59ad491d4f35f9fbadf8ec80cadc4` | `extensions/interactive-subagents` | `@_jb/pi-interactive-subagents` |
+| `jb/pi-native-hooks` | `73fa3299bf30fd6da5abfc74a0ee7a36e0a07f0a` | `extensions/native-hooks` | `@_jb/pi-native-hooks` |
+| `jb/pi-todo-herdr` | `d9e1ffec51e25238e0baec48ce1303893f13849f` | `extensions/todo-herdr` | `@_jb/pi-todo-herdr` |
+
+Carry snapshots rather than submodules, subtrees, or unrelated Git histories. The monorepo owns package manifests, dependency normalization, compatibility changes, tests, and releases after import. Preserve source attribution in each package.
+
+Record source URLs, branches, and commits in `config/imported-packages.json`. `bun run imports:check` compares those commits with current remote `main` heads. The staging command in `scripts/import-package-snapshots.mjs` clones fresh snapshots outside the repository for explicit review; it never overwrites the maintained workspaces.
+
+Rename the private `pi-workflow` extension identity to `workflow`. Its workspace is `extensions/workflow`, its tool and user-facing runtime identifiers use `workflow`, and its configuration/state paths use the same name. The npm package remains `@_jb/pi-workflow` under the repository's `@_jb/pi-<name>` convention.
+
+## Consequences
+
+- The three imported extensions share the Bun lockfile and catalog with the rest of the monorepo.
+- Published packages use the scoped Gitea registry instead of Pi-managed Git sources.
+- Upstream movement is detected but never merged automatically; imported changes require reconciliation with monorepo-specific manifests and APIs.
+- Only `main` is tracked. Source tags, branches, and historical commits are not copied.
+- The renamed `workflow` extension remains private until its `_workflows` dependencies are merged and isolated packaging succeeds.