add persisted pi workflow extension

docs/adr/0001-pi-workflow-architecture-24AUG2026.md

@@ -0,0 +1,19 @@
+---
+status: accepted
+---
+
+# Build pi-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.
+
+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.
+
+## Consequences
+
+- Child agents inherit the existing nono sandbox; the restricted script process remains defense in depth for model-authored JavaScript.
+- Project Agent Profiles and project configuration are loaded only for trusted projects.
+- Potentially mutating interrupted Assignments require explicit recovery and are never replayed automatically.
+- A versioned `plan.md` is the implementation handoff source for fresh-session and compacted-context transitions. Durable Gate-bound intents and callbacks keep implementation blocked until session replacement or compaction completes; normal Pi compaction is permitted only after the host confirms `smart_compact` is inactive, while an actual execution failure remains visible.
+- Fresh-session replacement rotates the run lease to the new active parent session inside `withSession`; historical parent sessions may inspect but cannot mutate the run.
+- The extension creates one exclusive worktree per feature run on `feature/<feature-name>`, where the validated feature name describes the feature without a numeric or run-ID suffix. Any existing branch rejects a new start and, when persisted state maps it to a Workflow Run, directs the caller to continue through `inspect` or `decide`; otherwise it directs the caller to choose another descriptive name. The extension does not merge, commit, reset, or remove the worktree automatically in the first version.
+- `_workflows` remains inactive until migration or removal is approved separately.