docs: supersede the legacy workflow engine

2026-09-04 10:47:04 -04:00
parent f1b525cec9
commit 12495473ee
17 changed files with 89 additions and 31 deletions
@@ -1,9 +1,12 @@
 ---
-status: accepted
+status: superseded
+superseded-by: 0006-skill-led-development-workflow-04SEP2026.md
 ---

 # Build workflow around persisted policy gates

+> Superseded by [ADR 0006](./0006-skill-led-development-workflow-04SEP2026.md). Retained as the legacy custom-engine decision.
+
 `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,10 +1,13 @@
 ---
-status: accepted
+status: superseded
 supersedes: 0001-workflow-architecture-24AUG2026.md
+superseded-by: 0006-skill-led-development-workflow-04SEP2026.md
 ---

 # Use drill-down overlays and bounded recovery

+> Superseded by [ADR 0006](./0006-skill-led-development-workflow-04SEP2026.md). Retained as legacy custom-engine UI and recovery evidence.
+
 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
@@ -1,3 +1,5 @@
 # Reuse standard agents through workflow role overlays

+> Superseded by [ADR 0006](./0006-skill-led-development-workflow-04SEP2026.md). Retained as the legacy custom-engine agent-selection decision.
+
 `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.
@@ -8,7 +8,7 @@ Publish packages to the `jb` owner endpoint of the Gitea npm registry. Repositor

 `extensions/shared` is the publishable `@jbcode/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. `@jbcode/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.
+`extensions/_workflows` is reference code, not a package or publishable extension. The package-boundary decision remains valid, but [ADR 0006](./0006-skill-led-development-workflow-04SEP2026.md) supersedes the proposed runtime merge: `@jbcode/pi-workflow` now remains private, unpublished, and unexposed as historical pilot evidence.

 The existing `config/pi-links.json` policy remains the authority for live-development exposure. Package boundaries and publication do not automatically enable extensions globally.

@@ -18,4 +18,4 @@ The existing `config/pi-links.json` policy remains the authority for live-develo
 - 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.
+- ADR 0006 removes a `workflow` extension release from the active plan; archival or removal follows the skill pilot.
@@ -22,4 +22,4 @@ Rename the private `pi-workflow` extension identity to `workflow`. Its workspace
 - 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.
+- The renamed `workflow` extension remains a private historical snapshot. [ADR 0006](./0006-skill-led-development-workflow-04SEP2026.md) supersedes its merge/release prerequisite with the skill pilot and a later retirement decision.
@@ -0,0 +1,38 @@
+---
+status: accepted
+supersedes:
+  - 0001-workflow-architecture-24AUG2026.md
+  - 0002-workflow-interaction-and-recovery-25AUG2026.md
+  - 0002-workflow-standard-agent-overlays-27AUG2026.md
+---
+
+# Replace the custom workflow engine with a skill-led workflow
+
+## Context
+
+The custom `workflow` extension encoded useful approval, isolation, verification, and reviewer-independence policy, but coupled that policy to a large state machine, child runtime, scheduler, persistence layer, and TUI. Recorded runs failed or stalled before implementation when exact planner output, child delivery, recovery state, or liveness mechanics diverged from the engine contract.
+
+Pi already provides the useful orchestration primitives: `ask_user`, task tools, direct subagents, artifact presentation, prototypes, browser/application validation, project commands, and Git worktrees. Repository Markdown and commits provide a simpler recovery boundary than a second workflow runtime.
+
+## Decision
+
+Use the model-invoked [`develop-workflow` skill](../../skills/develop/develop-workflow/SKILL.md) for feature work and other multi-step changes. Keep questions and obvious low-risk edits on lightweight paths. Add no replacement extension.
+
+The parent agent owns classification, requirements, the retained workflow record, task state, worktree, assignments, verification, commits, review, and local integration. Preserve categorical human gates for the exact implementation plan, non-trivial UI direction, and just-in-time risk. Require observable evidence rather than exact model-authored transition schemas.
+
+Keep one committed Markdown workflow record per active change. Update it atomically at meaningful checkpoints with optimistic SHA-256 concurrency and retain it after completion. Treat Git and the last committed valid record as authoritative recovery evidence.
+
+Use bounded subagent assignments with exclusive file ownership and before/after Git evidence. Exclude every mutator identity from independent standards and specification review. Require Git-capable read-only reviewer profiles to regenerate and confirm the pinned binary diff fingerprint. Reviewers report findings but never remediate them.
+
+Automate verified commits, rebase, fresh review, clean local fast-forward integration, metadata-only closure, and safe cleanup. Keep destructive actions, force operations, conflict-driven behavior changes, pushes, publishing, deployment, and production access behind explicit approval.
+
+Retain `extensions/workflow` and `extensions/_workflows` as private historical reference during the pilot. Keep them unexposed. Archive or remove them only in a separate change after three successful real-work pilots and explicit retirement approval.
+
+## Consequences
+
+- Workflow gates become procedural and testable, not technically enforced by a custom state machine.
+- Recovery depends on repository evidence and proven child liveness rather than leases or automatic replay.
+- The skill composes existing Pi capabilities and adds no runtime dependency.
+- A Git-capable reviewer profile declares no edit/write tools, while parent before/after Git checks remain necessary because shell access can mutate indirectly.
+- Existing package and imported-snapshot ADRs remain valid except for workflow-extension-specific prerequisites, which this decision supersedes.
+- The twelve scenario evaluations and three real-change pilot remain required before retiring the legacy implementation or closing the replacement TODO.
@@ -155,7 +155,7 @@ Slices in the same row may proceed in parallel after their listed dependencies a
   - one selected provider route;
   - no package registries, SSH, Docker, browser, microphone, deployment credentials, or broad localhost access.
 4. Separate extension source from extension state. Confirm that normal sessions cannot modify global instructions, installed extension code, authentication state, other Pi profiles, or sibling repositories.
-5. Materialize the normal in-process extension allowlist as a generated, isolated Pi `settings.json` under the selected personal/work state root. Its package/extension entries come only from `config/pi-package-lock.json` and the trusted repository map. Disable `pi-ask` arbitrary notification commands, `/update`, `workflow`, background shell jobs, and any privileged direct spawn path until a controlled subprocess policy exists.
+5. Materialize the normal in-process extension allowlist as a generated, isolated Pi `settings.json` under the selected personal/work state root. Its package/extension entries come only from `config/pi-package-lock.json` and the trusted repository map. Disable `pi-ask` arbitrary notification commands, `/update`, the legacy `workflow` extension, background shell jobs, and any privileged direct spawn path until a controlled subprocess policy exists. The `develop-workflow` skill adds no executable or permission boundary; it composes only tools already available to the parent session.
 6. Import the unmanaged `~/.pi/agent/extensions/lm-studio.ts` implementation into a repository-managed extension at `extensions/lm-studio/index.ts`, lock its source revision, and change its fixed base URL contract to `http://127.0.0.1:1234/v1`. Maintenance moves the old extension to the quarantined state store and removes its active settings entry. A duplicate-provider test fails if the old source, another `lm-studio` registration, or `localhost` base URL remains loadable.
 7. Define and own stable profile fragments for `provider-lm-studio`, `provider-openai`, `provider-anthropic`, and `provider-morph`, granting only one route at launch. Prove nono 0.74's `tcp_connect_ports` behavior with real loopback fixtures listening on ports 1234 and 1235: the selected provider must connect to 1234 while 1235 and every other loopback port fail. Do not use hostname-only `allow_domain` as evidence of port restriction. If the fixture cannot prove exact enforcement, `provider-lm-studio` remains unavailable until a separately reviewed mediated relay is designed.

@@ -165,7 +165,7 @@ Slices in the same row may proceed in parallel after their listed dependencies a
 - The selected provider works while non-selected provider hosts, raw key environment names, and credentials are absent from the environment and process table.
 - Reads outside the exact Pi state, declared active-worktree access, and per-launch temporary paths fail; writes to a read-only active worktree fail; another session's temporary directory is inaccessible.
 - LM Studio, when selected, reaches only `127.0.0.1:1234`.
- `/update`, `workflow`, arbitrary notification commands, and unbrokered background shell jobs are unavailable.
+- `/update`, the legacy `workflow` extension, arbitrary notification commands, and unbrokered background shell jobs are unavailable; skill-led development cannot widen the parent session's policy.
 - The repository-managed LM Studio provider uses only the exact `127.0.0.1:1234` base URL, the old unmanaged source is quarantined, duplicate registration fails, and a real two-port fixture proves all other loopback ports are denied.
 - All base and provider profiles pass strict validation and resolved-policy review.

@@ -381,32 +381,34 @@ A failed pilot returns to the owning slice. Do not compensate by broadening the

 ## Slice 6B1: Child-agent and background-task isolation

-**Goal:** isolate spawned Pi, Claude, Codex, bounded background jobs, Herdr panes, and tmux panes without enabling repository toolchain execution or `workflow`.
+**Goal:** isolate spawned Pi, Claude, Codex, bounded background jobs, Herdr panes, and tmux panes without enabling repository toolchain execution or the legacy `workflow` extension.

 **Owner surfaces:** `profiles/nono/{child-pi,child-claude,child-codex,background-jobs}.json`, new spawn-wrapper sources under `scripts/nono/child-agents/`, isolated child-state configuration, and `tests/nono/capabilities/child-agents/`. Coordinate with extension owners but avoid editing Slice 6A's socket fragments or shared extension files concurrently.

 **Work:**

-1. Inventory every spawn path in active subagent, `pi-ask`, update, and background-task extensions. Classify each in-process operation as safe UI/state access, disabled behavior, or a brokered subprocess. Keep `workflow` absent from generated settings.
+1. Inventory every spawn path in active subagent, `pi-ask`, update, and background-task extensions. Classify each in-process operation as safe UI/state access, disabled behavior, or a brokered subprocess. Keep the legacy `workflow` extension absent from generated settings.
 2. Route child Pi, Claude, and Codex through command policies with isolated child state and the immutable provider selected by Slice 3.
 3. Broker only named background jobs and notification commands that do not invoke repository toolchains; keep arbitrary commands, package updates, and direct privileged spawn paths disabled.
 4. Define caller relationships and prohibit privileged-command escalation through child commands.
 5. Verify Herdr and tmux targets launch under equivalent or narrower generated policies before enabling command delivery.
 6. Add containment tests for nested children, background completion, cancellation, inherited environment, provider override denial, notification commands, package-update denial, and artifact paths.

-**Acceptance criteria:** child commands receive no broader filesystem, network, credential, socket, environment, or provider access than declared; nested child tests prove containment; unsandboxed Herdr/tmux targets are rejected; bounded extension behavior remains functional without `workflow` or toolchain execution.
+**Acceptance criteria:** child commands receive no broader filesystem, network, credential, socket, environment, or provider access than declared; nested child tests prove containment; unsandboxed Herdr/tmux targets are rejected; bounded extension behavior remains functional without the legacy `workflow` extension or toolchain execution.

 **Dependencies:** pilot acceptance. May run in parallel with Slices 5A, 5B, and 6A.

-## Slice 6B2: `workflow` and toolchain integration
+## Slice 6B2: Skill-led development toolchain evidence

-**Goal:** enable `workflow` only after every toolchain command it can invoke has a completed command policy.
+> [ADR 0006](adr/0006-skill-led-development-workflow-04SEP2026.md) supersedes the planned `workflow` extension profile, spawn wrapper, generated-settings entry, and capability suite. Do not create those surfaces.

-**Owner surfaces:** `profiles/nono/workflow.json`, workflow spawn-wrapper sources under `scripts/nono/child-agents/workflow/`, the generated extension allowlist entry, and `tests/nono/capabilities/workflow/`.
+**Goal:** prove that `develop-workflow` uses only the parent session's approved Git, package-manager, verification, and child-agent command policies.

-**Work:** route `workflow` executable resolution and every npm/pnpm/Bun/Python/Rust/Go/Maven/Gradle task through the completed Slice 5 policies. Include lifecycle/run scripts, nested package executables, verification commands, and cancellation. Any unmodeled executable or repository without the required toolchain fragment fails before workflow execution.
+**Owner surfaces:** evidence under the existing Slice 5 and Slice 6B1 suites. The skill itself owns no nono profile, executable, wrapper, extension entry, or permission grant.

-**Acceptance criteria:** adversarial workflow tasks cannot bypass toolchain policies, select another provider, invoke high-risk commands, read sibling repositories, or access raw credentials; repositories lacking a required toolchain capability do not load `workflow`.
+**Work:** exercise representative skill-led assignments through the already completed toolchain and child-agent policies. Verify that model-selected commands cannot bypass executable allowlists, lifecycle/run-script containment, provider binding, repository boundaries, or cancellation. An unmodeled executable or repository without the required fragment fails exactly as it does for direct parent tool use.
+
+**Acceptance criteria:** skill-led tasks cannot broaden parent or child policy, select another provider, invoke high-risk commands, read sibling repositories, or access raw credentials. The legacy `workflow` extension remains absent from generated settings.

 **Dependencies:** Slices 5A, all applicable 5B language fragments, and Slice 6B1. It does not run in parallel with the toolchain policy it consumes.

@@ -479,14 +481,14 @@ To keep parallel work mergeable:
 | Base filesystem | Active registered worktree has exactly its mapped read-only or read/write access; exact mutable Pi state and the per-launch temporary directory are writable | A read-only worktree cannot be written; broad `/tmp`, runtime parents, other sessions, sibling or unregistered worktrees, global instructions, extension source, other Pi state, `~/.ssh`, and `~/.config/gh` are inaccessible or read-only as designed |
 | Temporary lifecycle | Normal exit and cancellation remove the private runtime directory; approved active use remains within its aggregate bound | Cleanup preserves a held lease, matching PID/start time, populated cgroup, live unit, or inconclusive identity; proven crash leftovers expire, unsafe paths survive for review, and an active session cannot exhaust `/run` |
 | Worktree lifecycle | Broker creates, registers, resolves, and safely removes an external clean worktree | Broad worktree-root access, age-only deletion, dirty/untracked/unpushed removal, active-worktree removal, and linked-worktree confidentiality claims fail |
-| Environment/extensions | Reviewed extensions and selected mediated provider credential work | Raw credential variables, old LM Studio source, duplicate providers, `/update`, `workflow` before 6B2, arbitrary notification commands, and unbrokered shell jobs are absent |
+| Environment/extensions | Reviewed extensions and selected mediated provider credential work | Raw credential variables, old LM Studio source, duplicate providers, `/update`, the legacy `workflow` extension, arbitrary notification commands, and unbrokered shell jobs are absent |
 | Provider | Trusted default or one pre-boundary approved flag selects the route; LM Studio reaches port 1234 | Ambiguous/post-boundary/child overrides, non-selected providers, LM Studio port 1235, and broad localhost fail |
 | Git/SSH | Fetch/push uses the correct provisioned agent and immutable wrapper | Direct SSH, stale/substituted agent, bypass config, alternate binary, same-port host, wrong agent, wrong host, and wrong port fail |
 | GitHub CLI | Active-repository operation succeeds through proxy | Real token exposure, cross-repository API, and unapproved endpoints fail |
-| Package manager/workflow | Restore/build/test uses exact cache and hosts; 6B2 routes workflow tasks through completed policies | Lifecycle/run-script escape, unrelated cache, publish token, privileged command, and unapproved registry fail |
+| Package manager/skill-led tasks | Restore/build/test uses exact cache and hosts; 6B2 proves `develop-workflow` cannot exceed completed parent policies | Lifecycle/run-script escape, unrelated cache, publish token, privileged command, and unapproved registry fail |
 | Orca/Herdr | Authenticated current endpoint and verified socket peer succeed on launch and cache hit | Stale/replaced/wrong-service endpoint and unrelated socket/port fail |
 | Dictation | Voice request succeeds with `--voice` | Socket, audio stack, model data, and GPU remain absent by default |
-| Child agents | Declared bounded child workflow completes | Child cannot broaden filesystem, network, credentials, sockets, environment, or provider |
+| Child agents | Declared bounded child task completes | Child cannot broaden filesystem, network, credentials, sockets, environment, or provider |
 | High-risk modes | Explicit host-authorized workflow succeeds and records policy digest | Missing confirmation, conflicting flags, sandbox invocation, or another mode's capability fails |
 | Generator/evidence | Strict validation, dynamic revalidation, deterministic cache hit, and trusted evidence summary succeed | Unknown or malformed inputs, stale digests/endpoints, tampered cache/evidence producer, and unsafe runtime/cache paths stop before launch |

@@ -20,9 +20,9 @@ Captured for Slice 0 on 27AUG2026 with nono 0.74.0. This record contains no cred
 | `pi-orca-local` | Symlink to `profiles/nono/pi-orca-local.json` | Approved drift imported, narrowed to read-only trusted-file access, and relinked on 27AUG2026. |
 | `pi-harness-tools` | Symlink to `profiles/nono/pi-harness-tools.json` | Approved drift imported, narrowed to read-only trusted-file access, and relinked on 27AUG2026. |

-The imported `pi-orca-local` drift is limited to exact read-only access for `$HOME/.pi/agent/AGENTS.md`. Its saved grant for `$HOME/.pi/agent/extensions/workflow/index.ts` was not imported because the user removed that extension and deferred its replacement to a future skill. The imported `pi-harness-tools` drift is limited to exact read-only access for `$HOME/.pi/agent/extensions/pi-todo-herdr/index.ts` and `$HOME/.config/herdr/herdr.sock`. Its inherited `pi-local` policy already contains the Herdr Unix-socket grant. The active files used read/write `allow_file` saved grants; the repository deliberately narrows them to `read_file` because normal sessions do not need to modify trusted instructions or extension code. No other active saved grant was imported.
+The imported `pi-orca-local` drift is limited to exact read-only access for `$HOME/.pi/agent/AGENTS.md`. Its saved grant for `$HOME/.pi/agent/extensions/workflow/index.ts` was not imported because the user removed that extension; [ADR 0006](adr/0006-skill-led-development-workflow-04SEP2026.md) replaces it with the `develop-workflow` skill, which needs no extension-source grant. The imported `pi-harness-tools` drift is limited to exact read-only access for `$HOME/.pi/agent/extensions/pi-todo-herdr/index.ts` and `$HOME/.config/herdr/herdr.sock`. Its inherited `pi-local` policy already contains the Herdr Unix-socket grant. The active files used read/write `allow_file` saved grants; the repository deliberately narrows them to `read_file` because normal sessions do not need to modify trusted instructions or extension code. No other active saved grant was imported.

-The `workflow` extension was unlinked from active Pi state by the user during this slice. It is also absent from normal `config/pi-links.json` exposure so reconciliation will not recreate it. The future replacement is tracked in `docs/todos.md`.
+The legacy `workflow` extension was unlinked from active Pi state by the user during this slice. It remains absent from normal `config/pi-links.json` exposure so reconciliation will not recreate it. The `develop-workflow` skill replacement and its remaining pilot are tracked in `docs/todos.md`.

 ## Draft disposition

@@ -42,7 +42,7 @@ bun publish

 Publish `@jbcode/pi-shared` before a new version of any extension that depends on it. Gitea rejects republishing an existing name/version, so bump the changed package version first.

-`extensions/workflow` is intentionally private until the `_workflows` reference dependencies are merged into that package. `extensions/_workflows` must not be published.
+`extensions/workflow` and `extensions/_workflows` are private historical evidence and must not be published. [ADR 0006](adr/0006-skill-led-development-workflow-04SEP2026.md) supersedes the proposed runtime merge; new development uses the `develop-workflow` skill.

 ## Install with Pi

@@ -1,3 +1,5 @@
 # TODO

+> This item applies only to the private legacy workflow runtime retained during the [`develop-workflow` pilot](adr/0006-skill-led-development-workflow-04SEP2026.md). Mark it obsolete when that runtime is retired unless `GitStateProbe` is intentionally retained.
+
 - [ ] Make workflow verification tolerate inaccessible sibling Git worktrees. `GitStateProbe.captureRepository()` currently enumerates every path from `git worktree list --porcelain` and fails the verification command before execution when any unrelated worktree cannot be inspected. Preserve detection of cross-worktree mutations without making unrelated worktrees a hard verification dependency. Add focused coverage for an inaccessible registered sibling worktree.
@@ -8,9 +8,9 @@ During the Orca polling fix on 02SEP2026, Bash tool calls configured with `cwd`

 Publishing `@jbcode/pi-interactive-subagents@3.7.4` exposed a Pi package-manager failure when `~/.pi` resolves through `/home/jb/data/.home-dotdirs/.pi`. Pi 0.84.4 invoked npm 12.0.2 with `--prefix /home/jb/.pi/agent/npm` from the repository cwd. npm rewrote the lockfile root as `file:../../../data/.home-dotdirs/.pi/agent/npm`, recursively duplicated that path until the lock contained 12,576 entries and 18 MB of data, and then failed with `ENOENT` during reification. Canonicalizing the npm root, regenerating both lockfiles from that directory, and installing once restored the 124-entry lock and all configured packages. Update Pi's npm package execution to use the canonical install root as its cwd, add a symlinked-agent-directory regression test, and ensure interrupted installs terminate their package-manager children before another reconciliation begins.

-## Merge `_workflows` reference runtime into `workflow`
+## Archive the legacy workflow runtime after the skill pilot

-`extensions/_workflows` was retained only as a reference while `extensions/workflow` was developed, but `workflow` still imports its runner, model, prompt, and serialization modules. Move the required code under `extensions/workflow`, remove obsolete model-authored workflow surfaces, update tests and documentation, and then delete the reference directory. Until that work is complete, `@jbcode/pi-workflow` must remain a private Bun workspace and `extensions/_workflows` must remain excluded from workspaces and publication. Acceptance requires `bun pm pack` for `workflow` to contain every runtime import without reaching outside the package root, followed by an isolated Pi package smoke test.
+[ADR 0006](adr/0006-skill-led-development-workflow-04SEP2026.md) supersedes the planned merge of `extensions/_workflows` into `extensions/workflow`. Keep both as private, unpublished, unexposed historical evidence while the `develop-workflow` skill completes scenario evaluation and three real-change pilots. After explicit retirement approval, archive or remove both implementations and their tests in a separate cleanup change; do not merge or release the legacy runtime first.

 ## Make `pi-links` checks work from linked worktrees

@@ -22,7 +22,7 @@ Slice 1 found two Nono 0.74 limitations while building behavioral policy proofs.

 ## Replace `workflow` with a skill-based orchestrator

-The strict `workflow` extension repeatedly failed before implementation because planner output and persisted state-machine constraints were too brittle for adaptive subagent orchestration. In a separate session, design a repository-managed skill where the main Pi agent owns the plan, task tree, isolated worktree, explicit user approval gates, verification, and independent review while launching standard `scout` and `worker` subagents directly. Preserve file-ownership boundaries, no inferred approvals, review independence, and resumable repository evidence, but prefer native Pi primitives over a custom orchestration engine. Evaluate a small committed state manifest for crash recovery before retiring or archiving the extension. Use the abandoned `.worktrees/workflow-plan-seed` implementation only as reference; do not integrate it by default.
+The strict `workflow` extension repeatedly failed before implementation because planner output and persisted state-machine constraints were too brittle for adaptive subagent orchestration. Implement the repository-managed `develop-workflow` skill under [ADR 0006](adr/0006-skill-led-development-workflow-04SEP2026.md), where the parent owns the plan, task tree, isolated worktree, explicit approval gates, verification, and independent review while launching bounded subagents directly. Preserve file ownership, reviewer independence, and resumable repository evidence while preferring native Pi primitives. Keep this TODO open until all twelve fresh-session scenarios and three real-change pilots pass; only then request retirement approval.

 ## Support finished-session resume for Claude CLI subagents

@@ -1,5 +1,7 @@
 # workflow

+> **Historical reference, superseded for new development:** This document describes the legacy `workflow` extension and custom engine. New feature work uses the model-invoked [`develop-workflow` skill](../../skills/develop/develop-workflow/SKILL.md) under [ADR 0006](../adr/0006-skill-led-development-workflow-04SEP2026.md). Retain this document only as pilot history.
+
 `workflow` plans and implements feature work through persisted human Gates, isolated Git worktrees, focused verification, and independent review.

 ## Start a feature
@@ -1,6 +1,8 @@
 # workflow popup prototypes

-**Status:** Direction C accepted
+> **Historical reference, superseded for new development:** These mocks describe the legacy `workflow` extension and custom TUI. New feature work uses the model-invoked [`develop-workflow` skill](../../skills/develop/develop-workflow/SKILL.md) under [ADR 0006](../adr/0006-skill-led-development-workflow-04SEP2026.md). Retain them as prototype evidence.
+
+**Status:** Historical direction C evidence

 These static terminal frames compare popup directions for `/workflow`. They are prototype evidence, not production screenshots or manual validation of the implemented extension. All variants use Pi theme tokens, keyboard-visible focus, one border at most, and no animation.

@@ -1,6 +1,8 @@
 # workflow Design

-**Status:** Accepted  
+> **Historical reference, superseded for new development:** This design describes the legacy `workflow` extension and custom engine. New feature work uses the model-invoked [`develop-workflow` skill](../../skills/develop/develop-workflow/SKILL.md) under [ADR 0006](../adr/0006-skill-led-development-workflow-04SEP2026.md). Retain this document only as pilot history.
+
+**Status:** Superseded
 **Date:** 24AUG2026

 ## Purpose
@@ -1,6 +1,8 @@
 # workflow usability update plan

-Status: manual recovery plan after managed Workflow Runs `512d6c31`, `51b0c1cb`, and `ecb11e1e` failed or were interrupted before implementation.
+> **Historical reference, superseded for new development:** This plan describes legacy `workflow` extension recovery and TUI work. New feature work uses the model-invoked [`develop-workflow` skill](../../skills/develop/develop-workflow/SKILL.md) under [ADR 0006](../adr/0006-skill-led-development-workflow-04SEP2026.md). Retain it only as failure and pilot evidence.
+
+Status: historical manual recovery plan after managed Workflow Runs `512d6c31`, `51b0c1cb`, and `ecb11e1e` failed or were interrupted before implementation.

 ## Locked decisions