@gotgenes/pi-subagents 13.2.1 → 13.2.2

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [13.2.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.2.1...pi-subagents-v13.2.2) (2026-06-01)
+
+
+### Documentation
+
+* use ADR-NNNN with links docs-wide ([c6b6431](https://github.com/gotgenes/pi-packages/commit/c6b6431c004f324931f23be46cf2e47e8fdac919))
+
 ## [13.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.2.0...pi-subagents-v13.2.1) (2026-05-30)
 
 

package/README.md

@@ -494,7 +494,7 @@ Each has a corresponding upstream PR:
    Upstream PR: [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
 4. **Child-execution lifecycle events** (`src/lifecycle/child-lifecycle.ts`) — the child-session execution lifecycle is published as ordered events on `pi.events` (`subagents:child:spawning`, `session-created`, `completed`, `disposed`).
    `session-created` fires synchronously before `bindExtensions()` so consumers (e.g. `@gotgenes/pi-permission-system`) can register the child session before binding proceeds.
-   This inverts the former outbound `permission-bridge` pattern (ADR 0002 / [#261]) — the core publishes, consumers subscribe.
+   This inverts the former outbound `permission-bridge` pattern ([ADR-0002] / [#261]) — the core publishes, consumers subscribe.
    No upstream equivalent — this feature is specific to the `@gotgenes` fork.
 
 The upstream `vitest` suite plus tests added for each patch all pass on every commit.
@@ -502,3 +502,5 @@ The upstream `vitest` suite plus tests added for each patch all pass on every co
 ## License
 
 MIT — [tintinweb](https://github.com/tintinweb) (upstream) and [Chris Lasher](https://github.com/gotgenes) (fork)
+
+[ADR-0002]: docs/decisions/0002-extensions-on-a-minimal-core.md

package/dist/public.d.ts

@@ -1,19 +1,5 @@
 import { ThinkingLevel } from '@earendil-works/pi-ai';
 
-/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
-/**
- * Lifetime usage components, accumulated via `message_end` events. Survives
- * compaction (which replaces session.state.messages and would reset any
- * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
- * the cumulative cached prefix re-read on that one call — summing across
- * turns counts the prefix N times. See issue #38.
- */
-type LifetimeUsage = {
-    input: number;
-    output: number;
-    cacheWrite: number;
-};
-
 /**
  * types.ts — Type definitions for the subagent system.
  */
@@ -29,27 +15,19 @@ interface AgentInvocation {
     runInBackground?: boolean;
 }
 
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
 /**
- * agent.ts — Agent class with encapsulated status-transition logic and per-agent behavior.
- *
- * Status transitions (status, result, error, startedAt, completedAt) are owned
- * by the class and exposed via transition methods. External code reads these
- * fields through public properties but cannot write them directly.
- *
- * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
- * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
- *
- * Behavior (abort, steer buffering) lives on the agent rather than on
- * AgentManager — each agent manages its own lifecycle concerns.
- *
- * The child's working directory is supplied by a registered WorkspaceProvider
- * (the workspace seam); with no provider the child runs in the parent cwd.
- *
- * Phase-specific collaborators (subagentSession, notification) are attached
- * after construction as lifecycle information becomes available.
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
  */
-
-type AgentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+type LifetimeUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+};
 
 /**
  * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
@@ -73,7 +51,7 @@ interface WorkspacePrepareContext {
 }
 /** Outcome the core reports to a workspace when the run ends. */
 interface WorkspaceDisposeOutcome {
-    status: AgentStatus;
+    status: SubagentStatus;
     description: string;
 }
 /** What dispose may hand back for the core to fold into the child result. */
@@ -92,6 +70,28 @@ interface WorkspaceProvider {
     prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
 }
 
+/**
+ * subagent.ts — Subagent class with encapsulated status-transition logic and per-subagent behavior.
+ *
+ * Status transitions (status, result, error, startedAt, completedAt) are owned
+ * by the class and exposed via transition methods. External code reads these
+ * fields through public properties but cannot write them directly.
+ *
+ * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
+ * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
+ *
+ * Behavior (abort, steer buffering) lives on the subagent rather than on
+ * SubagentManager — each subagent manages its own lifecycle concerns.
+ *
+ * The child's working directory is supplied by a registered WorkspaceProvider
+ * (the workspace seam); with no provider the child runs in the parent cwd.
+ *
+ * Phase-specific collaborators (subagentSession, notification) are attached
+ * after construction as lifecycle information becomes available.
+ */
+
+type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
 /**
  * service.ts — Public API surface for cross-extension access to subagents.
  *
@@ -103,7 +103,6 @@ interface WorkspaceProvider {
  *   svc?.spawn("Explore", "Check for stale TODOs");
  */
 
-type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
 /** Serializable snapshot of an agent's state — no live session objects. */
 interface SubagentRecord {
     id: string;

package/docs/architecture/architecture.md

@@ -51,11 +51,11 @@ flowchart TB
 
     subgraph lifecycle["Lifecycle domain"]
         direction TB
-        AgentManager["AgentManager<br/>(spawn, abort, collection)"]
+        SubagentManager["SubagentManager<br/>(spawn, abort, collection)"]
         ConcurrencyQueue["ConcurrencyQueue<br/>(scheduling, drain)"]
         CreateSubagentSession["createSubagentSession<br/>(assembly factory)"]
         SubagentSession["SubagentSession<br/>(turn loop, steer, dispose)"]
-        Agent["Agent<br/>(status, behavior: abort/steer/run lifecycle)"]
+        Subagent["Subagent<br/>(status, behavior: abort/steer/run lifecycle)"]
         ParentSnapshot["ParentSnapshot<br/>(frozen parent state)"]
         Workspace["workspace<br/>(provider seam: child cwd + teardown)"]
     end
@@ -85,9 +85,9 @@ flowchart TB
         Menu["agent-menu<br/>(slash command)"]
     end
 
-    AgentTool --> AgentManager
-    AgentManager --> Agent
-    Agent --> CreateSubagentSession & SubagentSession
+    AgentTool --> SubagentManager
+    SubagentManager --> Subagent
+    Subagent --> CreateSubagentSession & SubagentSession
     CreateSubagentSession --> SubagentSession
     CreateSubagentSession --> SessionConfig
     SessionConfig --> AgentTypeRegistry
@@ -95,18 +95,18 @@ flowchart TB
     AgentTypeRegistry --> DefaultAgents & CustomAgents
     RecordObserver -.->|subscribes| SubagentSession
     UIObserver -.->|subscribes| SubagentSession
-    Widget -.->|polls| AgentManager
+    Widget -.->|polls| SubagentManager
 ```
 
 ### Key domain types
 
 ```mermaid
 classDiagram
-    class Agent {
+    class Subagent {
         +id: string
         +type: SubagentType
         +description: string
-        +status: AgentStatus
+        +status: SubagentStatus
         +result?: string
         +error?: string
         +toolUses: number
@@ -123,7 +123,7 @@ classDiagram
         +run()
         +resume(prompt, signal)
         +abort(): boolean
-        +steer(message): Promise<boolean>
+        +steer(message): Promise~boolean~
         +isSessionReady(): boolean
         +getConversation(): string | undefined
         +getContextPercent(): number | null
@@ -137,12 +137,12 @@ classDiagram
         +releaseListeners()
     }
 
-    class AgentManager {
+    class SubagentManager {
         +spawn(snapshot, type, prompt, config)
         +spawnAndWait(snapshot, type, prompt, config)
         +resume(id, prompt, signal)
-        +getRecord(id): Agent
-        +listAgents(): Agent[]
+        +getRecord(id): Subagent
+        +listAgents(): Subagent[]
         +abort(id)
     }
 
@@ -171,10 +171,10 @@ classDiagram
         +hasRunning(): boolean
     }
 
-    AgentManager --> Agent : creates/manages
-    AgentManager --> ParentSnapshot : receives at spawn
-    SubagentsService --> AgentManager : wraps via adapter
-    AgentManager --> AgentTypeRegistry : resolves types
+    SubagentManager --> Subagent : creates/manages
+    SubagentManager --> ParentSnapshot : receives at spawn
+    SubagentsService --> SubagentManager : wraps via adapter
+    SubagentManager --> AgentTypeRegistry : resolves types
 ```
 
 ## Agent lifecycle
@@ -216,8 +216,8 @@ sequenceDiagram
     participant LLM as Parent LLM
     participant Tool as subagent tool
     participant Spawn as spawn-config
-    participant Mgr as AgentManager
-    participant Ag as Agent
+    participant Mgr as SubagentManager
+    participant Ag as Subagent
     participant Factory as createSubagentSession
     participant Asm as assembleSessionConfig
     participant Sub as SubagentSession
@@ -238,8 +238,8 @@ sequenceDiagram
     Sub->>Child: prompt + drive turn loop
     Child-->>Sub: result text
     Sub-->>Ag: TurnLoopResult
-    Ag-->>Mgr: update Agent
-    Mgr-->>Tool: Agent
+    Ag-->>Mgr: update Subagent
+    Mgr-->>Tool: Subagent
     Tool-->>LLM: formatted result
     Note over Mgr: disposeSession() fires `disposed` at cleanup (resume-detectable)
 ```
@@ -277,11 +277,11 @@ src/
 │   └── session-dir.ts              session directory derivation
 │
 ├── lifecycle/                      agent execution and state tracking
-│   ├── agent-manager.ts            collection manager + observer wiring
+│   ├── subagent-manager.ts         collection manager + observer wiring
 │   ├── create-subagent-session.ts  assembly factory: session creation, binding, tool filtering
 │   ├── subagent-session.ts         born-complete child session: turn loop, steer, dispose
 │   ├── turn-limits.ts              normalizeMaxTurns (turn-count policy)
-│   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, workspace)
+│   ├── subagent.ts                 owns full execution lifecycle (run, abort, steer, workspace)
 │   ├── concurrency-queue.ts        background agent scheduling with configurable concurrency limit
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── child-lifecycle.ts          child-execution lifecycle event publisher
@@ -296,7 +296,7 @@ src/
 │
 ├── service/                        cross-extension API boundary
 │   ├── service.ts                  SubagentsService interface + Symbol.for() accessors
-│   └── service-adapter.ts          SubagentsServiceAdapter class wrapping AgentManager
+│   └── service-adapter.ts          SubagentsServiceAdapter class wrapping SubagentManager
 │
 ├── tools/                          LLM-facing tool implementations
 │   ├── agent-tool.ts               subagent tool definition, validation, dispatch
@@ -334,7 +334,7 @@ Record statistics (tool uses, token usage, compaction counts) are updated by `re
 UI streaming (active tools, response text, turn counts) is handled by `ui/ui-observer.ts`, which subscribes to the same session events independently.
 Neither observer wraps or forwards the other — both subscribe directly to the session.
 
-The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes to session events via `Agent.subscribeToUpdates()` and reads messages via `Agent.messages` — no direct `AgentSession` reference (#277).
+The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes to session events via `Subagent.subscribeToUpdates()` and reads messages via `Subagent.messages` — no direct `AgentSession` reference (#277).
 
 ## Cross-extension architecture
 
@@ -343,7 +343,7 @@ flowchart TD
     subgraph core["@gotgenes/pi-subagents"]
         direction TB
         exports["SubagentsService API<br/>publish / getSubagentsService<br/>SubagentRecord, SubagentStatus"]
-        engine["Tools: subagent, get_subagent_result,<br/>steer_subagent<br/>AgentManager, createSubagentSession, SubagentSession"]
+        engine["Tools: subagent, get_subagent_result,<br/>steer_subagent<br/>SubagentManager, createSubagentSession, SubagentSession"]
         ui_int["Internal UI: widget, viewer,<br/>/agents menu"]
     end
 
@@ -358,14 +358,14 @@ They declare this package as an optional peer dependency and use dynamic import
 ### What the core owns
 
 - The three tools: `subagent` (née `Agent`), `get_subagent_result`, `steer_subagent`.
-- `AgentManager` — spawn, abort, resume, collection management, observer wiring.
+- `SubagentManager` — spawn, abort, resume, collection management, observer wiring.
 - `ConcurrencyQueue` — background agent scheduling with configurable concurrency limit.
 - `createSubagentSession` — assembly factory: session creation and extension binding; returns a born-complete `SubagentSession`.
 - `SubagentSession` — the born-complete child session: drives the turn loop (`runTurnLoop`/`resumeTurnLoop`), steers, and disposes (firing `disposed` at true session disposal, so resume executions are registry-detected).
 - `child-lifecycle` — publishes the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) on `pi.events`.
   Reactive consumers subscribe: `@gotgenes/pi-permission-system` registers each child session on `session-created` and unregisters it on `disposed`.
-  This replaced the former outbound `permission-bridge` (#261, ADR 0002) — the core no longer looks up a named consumer.
-- `workspace` — the single generative seam (#262, ADR 0002): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
+  This replaced the former outbound `permission-bridge` (#261, [ADR-0002]) — the core no longer looks up a named consumer.
+- `workspace` — the single generative seam (#262, [ADR-0002]): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
   With no provider, children run in the parent cwd (default unchanged); the git worktree strategy lives behind this seam in `@gotgenes/pi-subagents-worktrees` (#263, the seam's first consumer).
 - `session-config` — pure configuration assembler (called by `createSubagentSession`).
 - `SubagentRuntime` — session-scoped state bag with methods.
@@ -373,7 +373,7 @@ They declare this package as an optional peer dependency and use dynamic import
 - `record-observer` — session-event observer that updates record statistics without callback threading.
 - Agent type registry — default agents, custom `.md` file loading.
 - Prompt assembly, context extraction, skills, environment.
-- Worktree isolation — evicted to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (#263, ADR 0002); `git` no longer appears in the core.
+- Worktree isolation — evicted to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (#263, [ADR-0002]); `git` no longer appears in the core.
 - Token usage tracking.
 - Session directory derivation and persisted `SessionManager` for subagent transcripts.
 - Settings persistence.
@@ -478,7 +478,7 @@ Extensions attach through exactly two surfaces, distinguished by the direction o
    Reactive concerns live here: permission detection, telemetry, UI, notifications.
    Adding a reactive concern never modifies the core.
 2. **Provider seams (generative) — rationed.**
-   The rare concern that must *inject* a value the core consumes synchronously registers a provider the core consults.
+   The rare concern that must _inject_ a value the core consumes synchronously registers a provider the core consults.
    Today there is exactly one: the **workspace provider** (returns the child's working directory plus bracketed setup/teardown).
    A provider seam is the only place the core is "open," so the list is kept as small as possible.
 
@@ -487,7 +487,7 @@ The discriminator when deciding how a concern attaches:
 - It only needs to **know** what happened → subscribe to a lifecycle event (observational, unlimited).
 - It must **return a value the core consumes** → register a provider (generative, rationed).
 
-The governing rule — **no vacant hooks**: the architecture must *admit* a seam without *shipping* it until a concrete consumer exists.
+The governing rule — **no vacant hooks**: the architecture must _admit_ a seam without _shipping_ it until a concrete consumer exists.
 A provider seam with no consumer is a speculative abstraction that taxes every reader and that `fallow` flags as dead.
 Latent extensibility is the deliverable; a vacant hook is not.
 
@@ -509,11 +509,11 @@ Latent extensibility is the deliverable; a vacant hook is not.
 - **Tool policy** (`disallowed_tools`) — access control belongs in pi-permission-system's `permission:` frontmatter.
 - **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
 - **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) — environment policy, not core.
-  Git worktrees are one *strategy* for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
+  Git worktrees are one _strategy_ for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
   Evicted to `@gotgenes/pi-subagents-worktrees` (#263), the first consumer of the workspace provider seam.
 - **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — removed in #264.
   Deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
-  Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
+  Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a _latent_ (un-built) provider seam, added only if a real consumer needs it.
 
 ### Composition model
 
@@ -563,7 +563,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `AgentToolDeps`               | 8                                                            | agent-tool                                        | ✓ done    |
 | `AgentMenuDeps`               | 8                                                            | agent-menu                                        | ✓ done    |
 | `ConversationViewerOptions`   | 8                                                            | conversation-viewer                               | Low       |
-| `AgentInit`                   | 8                                                            | agent                                             | Low       |
+| `SubagentInit`                | 8                                                            | subagent                                          | Low       |
 
 ### Complexity hotspots
 
@@ -595,19 +595,19 @@ One 11-line internal clone group remains within `agent-config-editor.ts` (lines
 
 ### Session encapsulation debt (Law of Demeter) — resolved by [#277] ✔️
 
-All consumer reach-throughs to the raw SDK `AgentSession` via `Agent.session` have been eliminated.
-`Agent.session` is removed; `SubagentSession.session` is marked `@internal` (lifecycle use only).
+All consumer reach-throughs to the raw SDK `AgentSession` via `Subagent.session` have been eliminated.
+`Subagent.session` is removed; `SubagentSession.session` is marked `@internal` (lifecycle use only).
 The intent-revealing replacements added by [#277]:
 
-| Reach-through                            | Sites                                                                              | Replacement                                      |
-| ---------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------ |
-| Steer buffer-or-deliver (was duplicated) | `service-adapter.ts`, `steer-tool.ts`                                              | `Agent.steer(message)`                           |
-| Conversation viewing                     | `get-result-tool.ts`, `agent-menu.ts`, `conversation-viewer.ts`                    | `Agent.getConversation()` / `Agent.messages`     |
-| Session-readiness guard                  | `agent-tool.ts`, `agent-manager.ts`                                                | `Agent.isSessionReady()`                         |
-| Context-window stats                     | `steer-tool.ts`, `get-result-tool.ts`, `notification.ts`, `conversation-viewer.ts` | `Agent.getContextPercent()`                      |
-| Live updates (subscription)              | `conversation-viewer.ts`                                                           | `Agent.subscribeToUpdates(fn)`                   |
-| Observer callback session param          | `background-spawner.ts`, `foreground-runner.ts`                                    | `agent.subagentSession` (narrowed callback)      |
-| Session disposal                         | `agent-manager.ts`                                                                 | `SubagentSession.dispose()` — resolved by [#265] |
+| Reach-through                            | Sites                                                                              | Replacement                                        |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Steer buffer-or-deliver (was duplicated) | `service-adapter.ts`, `steer-tool.ts`                                              | `Subagent.steer(message)`                          |
+| Conversation viewing                     | `get-result-tool.ts`, `agent-menu.ts`, `conversation-viewer.ts`                    | `Subagent.getConversation()` / `Subagent.messages` |
+| Session-readiness guard                  | `agent-tool.ts`, `subagent-manager.ts`                                             | `Subagent.isSessionReady()`                        |
+| Context-window stats                     | `steer-tool.ts`, `get-result-tool.ts`, `notification.ts`, `conversation-viewer.ts` | `Subagent.getContextPercent()`                     |
+| Live updates (subscription)              | `conversation-viewer.ts`                                                           | `Subagent.subscribeToUpdates(fn)`                  |
+| Observer callback session param          | `background-spawner.ts`, `foreground-runner.ts`                                    | `subagent.subagentSession` (narrowed callback)     |
+| Session disposal                         | `subagent-manager.ts`                                                              | `SubagentSession.dispose()` — resolved by [#265]   |
 
 ### Proposed bag decompositions
 
@@ -757,10 +757,10 @@ See [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution
 
 ## Phase 16 (complete)
 
-Phase 16 inverted the core's outbound dependencies: worktree isolation joined permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
+Phase 16 inverted the core's outbound dependencies: worktree isolation joined permissions as an _extension_ on a minimal core, leaving pi-subagents a pure child-session orchestrator.
 The core now attaches extensions through exactly two surfaces — observational lifecycle events (unlimited) and rationed generative provider seams (today only the workspace provider) — and has zero knowledge of its consumers.
-The "runner" concept is gone: `createSubagentSession()` returns a born-complete `SubagentSession` that owns turn driving, steering, and disposal, and `Agent.run()` is coordination, not assembly.
-The decision and the full reasoning chain are recorded in [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md); the two-surface extension model is described under [Target architecture](#target-architecture).
+The "runner" concept is gone: `createSubagentSession()` returns a born-complete `SubagentSession` that owns turn driving, steering, and disposal, and `Subagent.run()` is coordination, not assembly.
+The decision and the full reasoning chain are recorded in [ADR-0002]; the two-surface extension model is described under [Target architecture](#target-architecture).
 All five steps are closed: [#261], [#262], [#263], [#264], [#265].
 The earlier "agent collaborator architecture" framing (#256 superseded, #257 parked, #258 and #259 closed not-planned) was abandoned; its structural win was reached cleanly via the workspace seam.
 See [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md) for details.
@@ -816,7 +816,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 14             | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                                 |
 | Phase 15             | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                                 |
 | Phase 16             | #261, #262, #263, #264, #265                               | Lifecycle events (retire permission-bridge), WorkspaceProvider seam, extract worktrees package, remove isolated, born-complete execution / dissolve runner |
-| Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above (ADR 0002)                                                                      |
+| Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above ([ADR-0002])                                                                    |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -861,3 +861,4 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#264]: https://github.com/gotgenes/pi-packages/issues/264
 [#265]: https://github.com/gotgenes/pi-packages/issues/265
 [#277]: https://github.com/gotgenes/pi-packages/issues/277
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/architecture/history/phase-16-invert-dependencies.md

@@ -3,7 +3,7 @@
 ## Summary
 
 Phase 16 reclaimed its original intent — invert the core's outbound dependencies — and extended it: worktree isolation joined permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
-The decision and the full reasoning chain are recorded in [ADR 0002](../../decisions/0002-extensions-on-a-minimal-core.md); the two-surface extension model is described under [Target architecture](../architecture.md#target-architecture).
+The decision and the full reasoning chain are recorded in [ADR-0002]; the two-surface extension model is described under [Target architecture](../architecture.md#target-architecture).
 
 All five steps are closed: [#261], [#262], [#263], [#264], [#265].
 
@@ -141,3 +141,4 @@ Composition test: install neither extension, only permissions, only workspaces,
 [#263]: https://github.com/gotgenes/pi-packages/issues/263
 [#264]: https://github.com/gotgenes/pi-packages/issues/264
 [#265]: https://github.com/gotgenes/pi-packages/issues/265
+[ADR-0002]: ../../decisions/0002-extensions-on-a-minimal-core.md

package/docs/decisions/0003-publish-bundled-type-declarations.md

@@ -27,7 +27,7 @@ A `tsc --traceResolution` of a sibling consuming the package surfaced two compou
 The public entry's type closure is deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) reaches `AgentStatus` in the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
 A shallow alias-free entry is therefore not achievable without a substantial source restructure.
 
-This collides with the ship-source model (ADR 0002): every package ships raw `.ts` executed directly by Pi, with no build step.
+This collides with the ship-source model ([ADR-0002]): every package ships raw `.ts` executed directly by Pi, with no build step.
 
 ## Decision
 
@@ -67,3 +67,5 @@ It is deliberately narrow: it produces type declarations only and changes nothin
 - The `types` condition points at a build-time artifact; an in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
   This is acceptable because no in-repo package imports the surface yet; #263 consumes the built artifact from the published tarball.
 - Sequencing: #270 must be published (its release-please PR merged) before #263 edits `pi-subagents` core, so #263's changes do not batch into the same `pi-subagents` release.
+
+[ADR-0002]: ./0002-extensions-on-a-minimal-core.md

package/docs/plans/0051-update-adr-0001-hard-fork.md

@@ -3,14 +3,14 @@ issue: 51
 issue_title: "docs: update ADR 0001 to reflect hard-fork decision"
 ---
 
-# Update ADR 0001 to reflect hard-fork decision
+# Update ADR-0001 to reflect hard-fork decision
 
 ## Problem Statement
 
-ADR 0001 (`docs/decisions/0001-deferred-patches.md`) was written when the fork was a thin-patch layer over `tintinweb/pi-subagents`.
+[ADR-0001] was written when the fork was a thin-patch layer over `tintinweb/pi-subagents`.
 The new architecture document (`docs/architecture/architecture.md`) commits to a hard fork with material scope reduction — scheduling removal, a `SubagentsAPI` boundary, `index.ts` decomposition, and more.
 
-Several claims in ADR 0001 are now outdated:
+Several claims in [ADR-0001] are now outdated:
 
 1. The status is "accepted" but the decision has been superseded by the architecture doc.
 2. The Upstream PRs section states "the fork's divergence reduces to package naming and tooling," which is no longer true.
@@ -18,7 +18,7 @@ Several claims in ADR 0001 are now outdated:
 
 ## Goals
 
-- Add a supersession note to ADR 0001 pointing to `docs/architecture/architecture.md`.
+- Add a supersession note to [ADR-0001] pointing to `docs/architecture/architecture.md`.
 - Update the "Upstream PRs are open" subsection so the "divergence reduces to…" claim reflects reality.
 - Update the Consequences → Operational section to note intentional divergence per the architecture document.
 - Preserve all existing rationale — no information is removed.
@@ -31,7 +31,7 @@ Several claims in ADR 0001 are now outdated:
 
 ## Background
 
-ADR 0001 has YAML frontmatter (`status: accepted`, `date: 2026-05-11`) and follows a standard ADR structure: Status, Context, Decision, Consequences.
+[ADR-0001] has YAML frontmatter (`status: accepted`, `date: 2026-05-11`) and follows a standard ADR structure: Status, Context, Decision, Consequences.
 
 The architecture document (`docs/architecture/architecture.md`) describes a six-phase plan that materially diverges from upstream: scheduling removal, ad-hoc RPC replacement, group-join and output-file removal, a typed `SubagentsAPI` boundary, and `index.ts` decomposition.
 
@@ -60,7 +60,7 @@ No tests are affected — this is a docs-only change.
 
 ## TDD Order
 
-1. Update ADR 0001 with all four edits described above.
+1. Update [ADR-0001] with all four edits described above.
    Commit: `docs: update ADR 0001 to reflect hard-fork decision (#51)`
 
 ## Risks and Mitigations
@@ -73,3 +73,5 @@ No tests are affected — this is a docs-only change.
 ## Open Questions
 
 None — the issue's acceptance criteria are unambiguous.
+
+[ADR-0001]: ../decisions/0001-deferred-patches.md

package/docs/plans/0257-extract-child-session-factory.md

@@ -6,7 +6,7 @@ issue_title: "Extract ChildSessionFactory from runner"
 # Extract ChildSessionFactory from runner
 
 > Superseded — issue #257 was closed `not_planned`.
-> Planning this extraction exposed that worktree isolation does not belong in the core; see [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md) and the reclaimed Phase 16 roadmap in [`docs/architecture/architecture.md`](../architecture/architecture.md).
+> Planning this extraction exposed that worktree isolation does not belong in the core; see [ADR-0002] and the reclaimed Phase 16 roadmap in [`docs/architecture/architecture.md`](../architecture/architecture.md).
 > The structural goal is recovered by #265.
 > This plan is retained for historical context only.
 
@@ -281,3 +281,5 @@ After all steps: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fa
   Deferred to Step 4, when the runner dissolves and the natural home for these creation contracts is the factory module.
 - Whether `ConcreteAgentRunner.createFactory()` lands in Step 3 (when `AgentManager` consumes it) exactly as the issue describes.
   Deferred to Step 3 per the Design Overview rationale.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md