@jmfederico/pi-web 1.202608.2 → 1.202609.1

package/dist/pi-packages/relays/skills/relay/SKILL.md

@@ -1,123 +1,94 @@
 ---
 name: relay
-description: "How the Relay method works: executing a plan as a chain of independent sessions that each do one slice and hand off to the next via spawn_session. Load this skill only when you already know you are in a relay: a prompt states you are working under the Relay framework (or relay/chain), points you at a relay charter/status/log, or the user invokes this skill directly. Do not load it for generic multi-step plans or ordinary spawn_session use."
+description: "Foundational, tool-agnostic Relay method for carrying long work across a chain of independent agent contexts, one bounded leg at a time. Use when a user asks what Relay is, invokes Relay directly, designs a Relay workflow or operational profile, or refers to an active Relay chain or packet. Do not load for generic multi-step plans, ordinary delegation, or unrelated session spawning."
 ---
 
 # Relay
 
-Relay is a way to execute a long or complex plan as a chain of independent sessions. Each session runs **one leg** — a single well-sized slice of the work — then hands the work off to a fresh session that runs the next leg. The chain continues until the goal is reached.
+Relay is a way to carry a long or complex effort across a chain of independent agent contexts. Each runner completes one bounded **leg**, makes progress durable, and hands the work to one fresh successor. The chain continues until the finish line is reached or human intervention is needed.
 
-There is no coordinator and no referee. Each runner is the coordinator for their own leg: smart enough to do the work, adapt to what they discover, and hand off cleanly. Trust is distributed to every agent, not held by a god-agent above them.
+The method follows the [Relay Principle](https://relayprinciple.ai/): do not recreate human management structures around agents by default. There is no standing coordinator, referee, role hierarchy, or “god-agent” supervising the chain. Each runner owns its leg, adapts the route within agreed bounds, and trusts the next runner to do the same.
 
-Relay works because it does not try to recreate human management structures. The point is fewer boundaries, less hierarchy, and more fluid execution. The thing that makes that safe is **context containment**: every leg starts with a fresh, small context, and the accumulated knowledge lives in compact documents on disk rather than in any one session's memory.
+Relay is safe because it combines distributed trust with **context containment**. A fresh runner receives compact durable state instead of inheriting an ever-growing conversation or defensively reconstructing the full history.
 
-## The hard constraint that shapes everything
+## Core model
 
-`spawn_session` is fire-and-forget. When you spawn the next leg, **you do not see its output and you cannot correct it.** The only thing that travels down the chain is what you wrote to disk. A human may be watching, but they intervene through the Relay's durable state and intervention signal, not by relaying messages between sessions.
+- **Relay:** the complete chain and its stable destination.
+- **Runner:** the agent context responsible for one leg. It coordinates its own slice; it does not supervise later runners.
+- **Leg:** one context-contained, coherent unit of progress. Leg boundaries protect context quality, not organizational ownership.
+- **Packet:** durable state shared across otherwise independent contexts.
+- **Baton:** the packet's compact current-state view: where the Relay is now, what comes next, and the targeted context needed by the next runner.
+- **Handoff:** the final operational act that starts or designates at most one successor after current work is durable. A user-facing summary may follow, but no further work, durable-state mutation, tool use, or downstream steering.
+- **Intervention:** a visible stop when the destination cannot be pursued responsibly within the current agreement.
+- **Operational profile:** the tool- and workflow-specific policy that binds these concepts to a concrete environment.
 
-Two consequences follow, and they govern the whole method:
+## Invariants
 
-- **Make your work durable before you hand off.** Update the status, append the log, and preserve artifacts in the way the charter defines before spawning the next leg. Anything not on disk is lost.
-- **If you hand off, do it exactly once, at the end.** Do not spawn early, do not spawn several runners "to parallelize," and never spawn while you still have work in flight. One leg, at most one handoff.
+A workflow keeps the spirit of Relay when these properties hold:
 
-## The relay packet
+1. **Stable destination, adaptive route.** The finish line and material bounds remain authoritative while runners adapt sequencing and implementation. Changing the destination requires the agreement authority defined by the Relay.
+2. **One bounded leg per context.** A runner does not keep accumulating unrelated work or execute several nominal legs in one context.
+3. **Durability before handoff.** Decisions, artifacts, current state, and blockers needed downstream are preserved outside transient conversation before a successor begins.
+4. **At most one successor.** A runner either hands off once at the end or stops. It does not fan out the chain or hand off while its own work remains in flight.
+5. **Fresh-context trust.** The successor is allowed to own its leg. If a runner feels it must watch and correct downstream work, the slice, packet, or intervention policy is not ready.
+6. **Bounded orientation.** A successor starts from the stable agreement and baton, then reads only targeted supporting context. Full-history reconstruction is exceptional, not routine.
+7. **Visible stopping.** Completion, blockers, and intervention are recorded clearly. Spawning a confused successor is worse than stopping cleanly.
+8. **No silent goal drift.** Current-state updates cannot redefine what the Relay is trying to achieve.
 
-A relay is carried by a small packet of documents. By default, its root is `.pi-web/relays/<name>/`. A user or dispatching instruction may choose another root. Record the actual root in the charter and use it consistently.
+## Durable state by role
 
-Every relay has these three core files.
+Relay needs durable state with three distinct authorities. An implementation may use files, records, messages, or another medium; the roles matter more than their names.
 
-**Authority follows role, not recency.** The charter is authoritative for where the relay is going and the bounds within which it runs; status is authoritative for where it is now and what comes next; the log is history. A later status update does not override the charter. This split lets every runner adapt the route without silently moving the destination.
+### Stable agreement
 
-**Charter** (`charter.md`) — the stable agreement, written when the relay is planned. It must contain, at minimum:
+Defines identity, goal and observable finish line, scope edges, explicit non-goals, and material assumptions or human decisions. It changes rarely. Clarification is normal; moving the finish line or an edge is an agreement change, not routine adaptation.
 
-- **Relay identity.** The relay name and root path, so runners know exactly which relay they are on.
-- **Goal / finish line.** A concrete, achievable end state with enough stable boundaries to decide whether it has been reached. The charter must state the finish line. It may define supporting requirements by reference only when it explicitly designates the referenced artifact as part of the stable agreement; neither `status.md` nor `log.md` may be the sole source of what “done” means. Without a finish line the relay runs forever — this is non-negotiable.
-- **Sizing.** How much is *one leg*? This is project- and plan-specific; the charter defines it (a task, a slice, a time/scope budget — whatever fits). The skill does not decide this for you.
-- **Task selection policy.** How a runner chooses the next task when `status.md` does not name one explicitly.
-- **Handover.** How a runner hands off: what the spawn prompt should say and what the next runner must read. A normal handoff starts with a natural header containing the relay name and next leg identifier, then points at `charter.md` and `status.md`, not the full log.
-- **Intervention signal.** When and how a runner must stop and get the human, and how that is made visible. The charter defines relay-specific triggers and signaling. A runner who would need to change the agreed finish line without explicit human direction must always stop and raise that signal.
-- **Reading discipline.** The files a runner should read to orient, and any files that should not be read defensively.
+Keep this destination-focused. Do not turn it into an implementation plan, technical design, quality checklist, risk inventory, or copy of project instructions. Those details anchor later runners to route assumptions and blur what requires human agreement.
 
-The charter *can* be edited. Clarifications and maintenance are fine, but changing the goal, finish line, or a supporting artifact that the charter designates as part of them changes the relay's agreement; it is not ordinary leg-level adaptation. Runners adapt the route, not the destination. Make such a change only with explicit human agreement, record it in `log.md`, and update the charter before continuing. If you believe the change is needed and do not already have that agreement, stop and raise the intervention signal. Frequent charter edits are still a smell that the design is unsettled.
+### Current baton
 
-**Status** (`status.md`) — the compact baton/current state. This is the file every runner reads after the charter, and every runner updates before handoff or stop. Keep it short enough that a fresh runner can load it cheaply.
+Defines present position, the last completed and next leg identifiers, current or next task, targeted context pointers, blockers, and required progress updates. It stays compact. It carries position, not destination.
 
-The baton carries position, not destination. `status.md` is authoritative for current state and next-leg selection only. It may describe a leg task or point to relevant context, but it must fit the charter's finish line and must not redefine, narrow, or extend it. Information needed to judge whether the relay itself is complete needs a stable home in the charter or a supporting artifact the charter designates; status points there rather than becoming its replacement.
+### History
 
-It should answer:
+Preserves concise append-only evidence of completed legs, decisions, artifacts, agreement changes, and stops. It supports targeted lookup and auditability; it is not the default orientation surface.
 
-- **Current position.** Where the relay is now.
-- **Current or next task.** The next leg if known; otherwise enough information to apply the charter's task selection policy.
-- **Leg tracking.** The last completed leg and the next leg to run. Keep this explicit so runners do not have to infer whether “current leg” means the leg just finished or the leg being handed off, and so the handoff prompt can identify the next leg accurately.
-- **Relevant context.** Only the files, sections, commands, artifacts, or specific log entries needed for the next leg.
-- **Progress documentation.** Where and how this runner must make progress durable: update `status.md`, append `log.md`, update artifacts, or follow another workflow named by the charter.
-- **Blockers / intervention state.** Current risks, open decisions, or active reasons to stop.
+Separating these roles prevents recency from becoming authority. A newer baton cannot silently override the stable agreement, and a large history does not become mandatory context.
 
-Leg identifiers distinguish handoffs; they do not predict a fixed route or total number of legs.
+## Operational profiles
 
-Think of `status.md` as the thing passed from runner to runner. If it grows into a history dump, compress it back into current state plus pointers. If finish-line-defining content has crept into status without a stable home, restore it to the charter or a charter-designated artifact before compressing it away. If an older relay lacks leg tracking, repair it when you update status; prefer the leg identifier from the prompt or status, and do not read `log.md` end-to-end just to reconstruct prior identifiers.
+This base skill is intentionally non-operational and tool agnostic. It does not choose:
 
-**Log** (`log.md`) — append-only history. Each leg appends a concise entry recording what it did, decisions made and why, durable artifacts changed, status updates made, and blockers. The log preserves auditability, including agreed changes to the charter, but it is **not** orientation memory and does not replace the charter as the current agreement.
+- how a successor context is created;
+- where or in what format durable state lives;
+- how large a leg should be or how tasks are selected;
+- whether work uses source control, worktrees, commits, tests, reviews, or delivery gates;
+- how intervention reaches a human; or
+- what project-specific quality standard applies.
 
-Do not read `log.md` end-to-end by default. Read targeted log entries only when `status.md` points to them, when the charter requires a specific lookup, or when there is an inconsistency you must resolve before continuing.
+An operational profile supplies those bindings and decides where to keep its identity and any operational record. Each handoff makes the active profile visible to the fresh runner. A profile may be strongly opinionated without putting its mechanics into the destination agreement or turning its choices into the definition of Relay.
 
-Optional files such as `plan.md`, `backlog.md`, specifications, or artifact notes are fine, but runners should read them only when the charter/status points to the relevant part. If the charter designates one as part of the finish line, changing that part follows the same agreement rule as changing the charter itself.
+Projects can layer any operational profile that fits their environment while preserving the invariants above.
 
-## Context containment rule
+## Context containment
 
-A runner normally reads:
+A fresh runner normally needs only:
 
-1. `charter.md`
-2. `status.md`
-3. Only the specific files or log entries referenced for the current leg
+1. the stable agreement;
+2. the current baton; and
+3. the specific supporting material those surfaces identify for the leg.
 
-Do not defensively rebuild the relay's full history. Do not read the full log, the full backlog, or a large artifact tree just because they exist. The relay stays scalable because each runner pays only for the context needed now.
+A baton that routinely requires full-history or whole-artifact-tree reconstruction violates bounded orientation. A state gap that can be resolved only through broad archaeology or guessing about the destination is an intervention condition, not ordinary continuation.
 
-If `status.md` is insufficient, fix the baton rather than compensating by reading everything. Here, fixing means restoring an accurate account of current state, tasks, and pointers within the charter's bounds; it does not mean reconstructing or revising the finish line in status. Use targeted inspection to clarify the current state, update `status.md` so the next runner has a clean start, and continue only if the task is still clear. If resolving the gap would require broad archaeology or judgment about past intent or what “done” should mean, stop and raise the intervention signal.
+## Failure smells
 
-## Running one leg
+- **Coordinator creep:** a persistent supervisor plans, watches, or approves every leg.
+- **Role bureaucracy:** fixed agent roles or layer ownership replace fluid, outcome-driven slices without a real constraint requiring them.
+- **No stable finish line:** mutable current state is the only definition of done.
+- **Baton authority creep:** status quietly narrows or expands the agreement.
+- **Context leakage:** every runner reloads the full history or inherits an unbounded conversation.
+- **Eager or parallel handoff:** successors begin before the current leg is durable, or one runner fans out the chain.
+- **Oversized legs:** a runner continues beyond a coherent context-contained checkpoint.
+- **Silent stall:** work stops without durable blocker or intervention state.
 
-This is the loop you run when you are dispatched into a relay.
-
-1. **Orient from the packet.** Read `charter.md` and `status.md`. Confirm from the charter the relay identity/root, finish line, sizing, task-selection policy, handoff protocol, intervention signal, and reading discipline. Confirm from status the current position, last completed leg, next leg to run, current/next task, and blockers. If you are not sure whether a Relay is active, the dispatch prompt or packet must establish it; loading this skill alone does not.
-2. **Choose the leg.** Prefer the explicit current/next task in `status.md`, provided it serves the charter's finish line and fits its sizing. If none is named, apply the charter's task selection policy. If that still requires context, inspect only the referenced plan/backlog/artifact sections. Do not adopt a task merely because status is newer. If the next task is still ambiguous, falls outside the charter's bounds, or would require moving the finish line, stop and involve the human.
-3. **Re-anchor to the charter.** Does the chosen leg still serve the finish line, and does reality still permit it? Adapting how to get there is your job. If reality indicates that what “done” means should change, stop and raise the intervention signal rather than quietly redefining it.
-4. **Run one leg.** Do exactly one well-sized slice, per the charter's sizing. Resist doing "just a bit more" — extra scope bloats context and breaks the containment that makes Relay work.
-5. **Document progress.** Make all work durable. Update `status.md` with the new current state, last completed leg, next leg to run (if any), next task or task-selection pointer, relevant context for the next runner, and blockers. Append a concise `log.md` entry with what you did, why, decisions made, artifacts changed, and whether you are handing off or stopping.
-6. **Decide: hand off, or stop.**
-   - **Hand off** if there is a clear next leg and you are on track. Use `spawn_session` once, with a prompt whose first line is a natural task header containing the relay name and next leg identifier (for example, `Relay "<name>" leg <identifier> begins now.`), followed by the Relay method and pointers to `charter.md` and `status.md` (so this skill loads and they can orient cheaply). Then you are done. Handoff is deliberately fire-and-forget: `spawn_session` starts an independent session you will not see and cannot steer — do not reach for a tracked subsession to keep an eye on it. Letting go is the point. The next runner is trusted to run their own leg, and the relay packet is the only thread between you; if you feel the need to watch downstream work, that usually means the leg wasn't sized or handed off cleanly, or an intervention signal should have fired.
-   - **Stop — do not spawn —** if the goal is reached, or you are blocked, or the charter's intervention signal fires. Update `status.md`, append a clear note in `log.md`, and raise the intervention signal so the watching human sees exactly what happened and what they need to decide. A stalled relay that stopped cleanly with a clear blocker is a success; a relay that spawned a confused next runner is a failure.
-
-A good handoff prompt is short and explicit. The example below uses the default packet root; substitute the root recorded in the charter when it differs. Put the relay identity and leg identifier at the very beginning so the handoff is immediately distinguishable:
-
-```text
-Relay "<name>" leg <identifier> begins now.
-
-You are the next runner in this Relay method chain.
-
-Read:
-- .pi-web/relays/<name>/charter.md
-- .pi-web/relays/<name>/status.md
-
-Do not read log.md end-to-end. Use it only for targeted lookup if status.md or charter.md points you there.
-
-Run one leg according to the charter. Before handing off, update status.md, append log.md, make work durable, then either spawn the next leg once or stop with a clear intervention note.
-```
-
-## Planning a relay
-
-When the user asks to set up a relay, your job is to produce the relay packet: `charter.md`, `status.md`, and `log.md`. The charter must have the required slots filled: relay identity, goal, sizing, task selection policy, handover, intervention signal, and reading discipline. Before dispatch, preserve the agreed finish line and the stable boundaries needed to judge it in the charter or in supporting material the charter explicitly designates. Do not make the initial status or planning conversation the only place those requirements exist. The initial status must give the first runner a compact baton: current position, leg tracking (for a numeric scheme, usually last completed leg 0 and next leg to run 1 for a new relay), first task or task selection pointer, relevant context, documentation expectations, and known blockers. The log may start empty or with a short seed entry explaining that the relay was created.
-
-Unless the user or dispatching instructions provide these choices or a rule for deriving them, draw them out from the user rather than inventing them: ask what the finish line is, how much should be one leg, how runners pick tasks, how runners hand off, what they should read, and when they must stop and get the human. Sizing, task selection, and the intervention signal especially are not for the generic method to decide — propose options if it helps, but do not quietly settle them yourself.
-
-Do **not** invent what a "good" plan, leg size, or cadence looks like when no policy is supplied — those choices are deeply project-, plan-, and human-specific. Explicit user, project, or dispatch instructions may provide defaults; follow them rather than replacing them with the skill's preferences. Your value in planning is making sure the relay is *runnable*: the finish line exists, sizing is stated, task selection is stated, handover is stated, reading discipline is stated, and the intervention signal is stated. Once the packet is agreed, you can dispatch the first leg with `spawn_session`.
-
-## Smells to watch for
-
-- **No stable finish line** → infinite or self-redefining relay. Refuse to run when “done” exists only in mutable state.
-- **Goal drift / baton authority creep** → a leg or `status.md` quietly restates, narrows, or extends what the relay is for. Re-anchor to the charter; changing the destination requires human agreement.
-- **Charter churn** → stable policy changes every leg. The design isn't settled; involve the human.
-- **Status bloat** → `status.md` turns into a history dump. Compress it to current state plus targeted pointers.
-- **Defensive reading** → reading the full log/backlog/artifact tree to feel safe. Use the packet and targeted lookups; stop if the baton is not enough.
-- **Eager spawning** → spawning early, spawning several runners, or spawning before work is durable. One leg, at most one handoff, at the end.
-- **Silent stall** → getting stuck and stopping with no note, or spawning anyway. Always update status, log the blocker, and surface it.
+Operational details may vary widely. These failures matter because they undermine the principle, not because a particular tool or file convention was violated.

package/dist/pi-packages/relays/skills/relay-runner/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: relay-runner
+description: "Opinionated full-lifecycle software-delivery profile for Relay chains in Git repositories. Load when preparing or running every leg of a Relay created by /relay or /relay-worktree, whenever a preparation or handoff prompt names relay-runner, or when an active Relay operations record declares this profile. Governs scope, adaptive leg sizing, checkpoints, verification, commits, review/remediation, delivery, and handoff. Do not load for generic Relay questions or Relays that declare another operational profile."
+---
+
+# Relay runner
+
+Use this skill as the opinionated software-delivery profile layered on the project-neutral `relay` method. It assumes a Git repository and optimizes for small, durable, independently reviewable progress from initial dispatch through delivery.
+
+This profile binds the base `relay` method's tool-agnostic principle, durable-state roles, context containment, and invariants to Pi's session tools and an opinionated Git/software-delivery workflow. Dispatch and handoff prompts are responsible for selecting both skills before a runner begins; skill bodies do not bootstrap other skills.
+
+## Profile contract
+
+For a Relay using this profile:
+
+- Have the preparation prompt select `relay-runner` before drafting the packet. Record it immediately in draft `operations.md` and retain it as required for every active leg, including implementation, review, remediation, and delivery.
+- Name both `relay` and `relay-runner` in every handoff prompt. Fresh sessions cannot inherit a prior runner's loaded skills.
+- Keep every Relay handoff on the current runner's model by omitting the `model` argument, unless instructed to use a specific model or to choose an appropriate one. Record any Relay-wide model instruction in `operations.md` so it remains available to later runners.
+- Treat the charter as destination and scope edges, `operations.md` as this profile's repository and execution bindings, `status.md` as current position and next work, and repository instructions as the quality and implementation authority.
+- Follow canonical repository policy when it conflicts with a profile default. Record a material operational adaptation in `operations.md`, not the charter. Stop for human intervention when reconciling the conflict would change the finish line or an edge, weaken a protected invariant, or require a product or business decision.
+
+This profile is intentionally strong. A project that wants another way of working should use the base `relay` skill with a different profile rather than quietly diluting this one leg by leg.
+
+## Pi execution and packet
+
+`spawn_session` is fire-and-forget: the current runner does not receive the successor's output and cannot steer it. The packet is the only thread across the chain. Complete all work and durable-state updates before handoff, then call `spawn_session` at most once as the leg's final operational action. After it returns, provide only a user-facing handoff summary; do not use more tools, mutate state, perform more Relay work, or try to steer the successor. Do not use a tracked subsession for the Relay handoff; tracked subsessions are allowed only as bounded helpers inside a leg when this profile explicitly permits them.
+
+Default the packet root to `.pi-web/relays/<name>/` unless the preparer selects another location. During preflight, create a reviewable draft packet in the checkout where the preparation session is running and mark it not dispatched. For fresh-worktree mode, move the complete packet into the target worktree before handoff and remove the stale drafting copy. Use the base method's three durable-state files plus one profile-owned operational record:
+
+- **`charter.md` — goal and edges.** Record Relay identity, the plain-language goal and observable finish line, minimum outcome acceptance, in-scope boundaries, explicit non-goals, material assumptions or human decisions. Keep it free of implementation plans, technical route definitions, quality bars, verification commands, review heuristics, and copied project guidance. Include a technical contract only when the user made that contract part of the desired outcome or a necessary scope edge. Changing the goal or an edge requires explicit human agreement, a charter update, and a log entry.
+- **`operations.md` — runner bindings.** Record the packet and profile identity, canonical project instruction pointers, working location and Git facts, verification commands, packet isolation, commit and checkpoint policy, review budget and delivery mechanism, intervention signal, and any explicit profile adaptation. These are operating facts and policies, not product scope; maintain them without rewriting the charter.
+- **`status.md` — compact baton.** Record current position, last completed leg, next leg identifier, current or next task, targeted context pointers, progress-documentation expectations, blockers, and active transition or review-decision pointers. Status selects the route; it cannot redefine the charter. Compress history out of it.
+- **`log.md` — append-only history.** Append one concise entry per leg covering work and decisions, durable artifacts, verification, packet updates, and handoff or stop. Read only targeted entries referenced by charter, operations, or status; never read it end-to-end defensively.
+
+Do not add `plan.md`, a roadmap, or generic planning/design documents to the packet. The only optional packet files in this profile are a targeted `transition.md` while a transitional checkpoint is active and a targeted `review-decisions.md` while unresolved whole-work findings require continuity. Status must link each active optional file; when that need ends, record its conclusion in the log and remove both the pointer and optional file. Put any task- or project-specific durable artifact in its canonical project or delivery location and link it through a targeted status pointer instead of expanding the packet format. If status is insufficient, repair it with targeted inspection. Intervene rather than reconstructing broad history or guessing what “done” means.
+
+Authority follows role, not recency: charter owns destination and edges, operations owns this profile's execution bindings, status owns current position and next work, and log preserves history. Canonical repository instructions own project quality and implementation policy. None of the operational surfaces can override the charter.
+
+## Goal and scope
+
+Under this profile, Relay completion means the chartered outcome has been reached and every completion gate required by `operations.md`—including whole-work review, approval, and delivery—has completed. Keep those operating gates in `operations.md` rather than adding them to the charter.
+
+Translate source material into a plain-language, observable finish line without adding outcomes. Understanding intent does not authorize extra behavior. Treat the current repository as the baseline and include only:
+
+- work explicitly requested;
+- work necessary to reach the finish line; and
+- directly coupled work needed to prevent this Relay's changes from causing regressions.
+
+Record only the minimum observable outcome acceptance and scope edges needed to recognize completion: what is in, what is explicitly out, any directly affected behavior the goal must preserve, and material assumptions or decisions. Prefer product language. Do not add technical definitions, quality criteria, speculative failure cases, or implementation constraints merely to make the charter look complete; project instructions govern quality directly. Leave optional cleanup, hardening, refactoring, and features outside the Relay unless the user approves them.
+
+## Adaptive legs without an upfront plan
+
+Relay intentionally does not predict the chain. Before dispatch, establish the destination and edges and select only the first bounded leg. Do not create work packages, an exhaustive stage sequence, a file/layer map, or a promised leg count. Future runners choose the next slice from current reality and the finish line.
+
+Expected files, subsystems, dependencies, architecture, and sequencing are route assumptions. Keep only what the current or next leg needs in status or a targeted temporary artifact; do not turn route assumptions into stable agreement.
+
+A leg is one context-contained, reviewable slice that advances the finish line. Development legs implement and verify by default: optimize for the smallest useful behaviour, not the smallest independently testable artifact. A functional checkpoint makes an observable charter outcome available and verifies it through the relevant application boundary. A tested but unused module is a prerequisite, not a functional outcome. Setup, required verification, review and delivery remain legitimate lifecycle legs.
+
+Slice by supported cases across the necessary layers. When a journey is too large, choose a narrower case or a safe partial capability with explicit limitations, keeping the full charter outstanding. Keep directly coupled implementation, checks, contracts, generated outputs, documentation and integration together.
+
+Before substantial work, state the leg's:
+
+- observable outcome and application boundary;
+- bounded change surface and coupled verification;
+- remaining connection to usable behaviour, if any; and
+- checkpoint type: functional, necessary prerequisite or profile-authorized transitional.
+
+An unconnected prerequisite must name the behaviour it enables and why a connected slice cannot reasonably fit. Its successor prioritizes that connection. Before adding another prerequisite-only leg, reassess the slice and simplify the route; continue only when a concrete dependency still prevents connection.
+
+Routine reading, design, sizing and test investigation belong inside implementation. A research-only leg requires a specific unanswered question blocking responsible implementation: record the blocked behaviour, why available evidence is insufficient and the result needed to proceed. Answer that question and hand off to implementation; intervene if it remains unresolved. Size or complexity alone calls for a smaller implementation slice.
+
+Choose the simplest design satisfying the charter, canonical project rules and concrete risks introduced by the change. Justify additional safeguards against those obligations; keep speculative recovery systems and future-use abstractions outside the slice. Preserve safety when narrowing behaviour.
+
+Persist only conclusions useful to the next runner. Keep leg history in the packet log and project documentation focused on current behaviour and contracts.
+
+If a leg grows beyond its context-contained slice, stop broadening before context exhaustion. Finish or revert to a coherent functional or justified prerequisite checkpoint, or use an already authorized transition. Record the next bounded slice. Do not promise a fixed total leg count.
+
+When status does not name the next task, choose the smallest coherent slice that advances the critical path or unblocks an agreed outcome. Do not invent cleanup or speculative follow-up merely to fill a leg.
+
+### Bounded transitional checkpoints
+
+Use a transitional checkpoint only when a functional split would make the leg unreasonably large or require disposable compatibility work, and repository policy permits it. Before making the repository non-functioning, record a breakage budget containing:
+
+- expected affected surfaces and failure classes;
+- the last known functional commit;
+- a recovery action if handoff fails;
+- a named restoration milestone; and
+- safety constraints.
+
+Keep the active summary in `status.md`. Put larger details in `transition.md`, link it from status, and preserve the pointer until restoration.
+
+A transitional leg may leave only failures inside that declared budget. The incomplete state must intentionally advance an agreed outcome, complete a coherent transformation step, and receive every focused check meaningful for that step. Every following leg while the transition is active must continue or restore it; do not start unrelated work. Never authorize a transition that creates an unsafe security, authorization, data-integrity, or irreversible external-effect state.
+
+Treat a failure outside the budget as unexpected; resolve it or intervene rather than relabeling it after the fact. Make the checkpoint durable under the operations record's commit policy and record exact verification, recovery, and next work before handoff. If the Relay must stop before restoration, execute the recovery action unless `operations.md` explicitly permits the isolated state to remain safely available for human recovery. Do not start whole-work review or delivery until the repository is functional and final verification requirements can pass.
+
+## Support preflight and dispatch an approved Relay
+
+### Discover only what the packet needs
+
+Read `AGENTS.md` and other canonical agent or contributor instructions, then follow only the references needed to establish:
+
+- applicable project skills or quality standards every runner must use;
+- focused and full verification commands, including manual checks when automation is absent;
+- integration base ref and immutable base commit;
+- review range and allowable pre-existing working-tree state;
+- commit conventions;
+- fresh-worktree bootstrap requirements, if applicable;
+- review and delivery mechanism, plus an achievable fallback when remote or review tooling is unavailable; and
+- packet isolation from delivery commits and the reviewed diff.
+
+Point `operations.md` at canonical instructions instead of copying them into the packet, especially the charter. Persist only operating facts that need clarification or reinforcement. Prefer documented commands over broad repository exploration and stop discovery once the packet is runnable. If the repository has no canonical quality guidance, record that fact; do not invent a project-wide quality bar for the charter or reviewer.
+
+If the base, existing-change ownership, target checkout, destructive-data choice, or delivery mechanism is materially ambiguous, ask rather than guess.
+
+### Prepare the working location
+
+During preflight, inspect and propose the working mode, base, and location. Draft packet documents may be created and revised immediately for human review. Creating a branch or worktree is also preparation rather than dispatch, but avoid unnecessary setup before the target is understood. Apply the selected mode:
+
+- **In-place mode:** work in the invoked checkout and branch. Record checkout path, branch, integration base ref and commit, initial HEAD, pre-existing state, and exact review diff in `operations.md`. Keep unrelated existing changes out of Relay commits.
+- **Fresh-worktree mode:** create a new branch and worktree from the recorded base unless the task names another target. Follow the repository's existing worktree placement; otherwise use a clear sibling location. Draft the packet in the preparation session's checkout until the target exists, then move it intact into the worktree before dispatch and set every handoff's `cwd` to that worktree. Record the dispatching checkout's state as well as worktree path, branch, and initial HEAD in `operations.md`.
+- **Explicit existing location:** when the task names an existing checkout or worktree, use it and record the same operating facts as in-place mode.
+
+In fresh-worktree mode, make leg 1 setup-only when bootstrap is required: perform the recorded bootstrap, confirm success and allowable working-tree state, then hand off without inspecting or implementing the task. If no bootstrap is needed, dispatch the first substantive leg.
+
+Treat the Relay packet as operational state, not delivery work. Use `.pi-web/relays/<name>/` in the drafting checkout during preparation and in the selected target checkout before dispatch. Keep it outside delivery commits and the reviewed diff through an existing ignore rule, a local Git exclusion, or another non-delivery location.
+
+### Write goal and operations separately
+
+Keep `charter.md` short and destination-focused. Record:
+
+- Relay identity;
+- the interpreted goal and observable finish line in plain language;
+- minimum outcome acceptance;
+- in-scope edges, explicit non-goals, directly affected behavior that must remain unchanged, and material assumptions or human decisions.
+
+Do **not** put a quality bar, technical design, expected files or subsystems, verification matrix, edge-case inventory, failure taxonomy, review checklist, or copied project standards in the charter. Reviewers apply the repository's current canonical skills and documentation directly, so the charter does not need to predict or paraphrase them.
+
+Write the profile's mechanics to `operations.md` instead:
+
+- packet identity and `relay-runner` as the profile required in every leg and handoff;
+- implementation-first leg sizing and outcome-led task selection under this profile, with route assumptions provisional and no fixed leg count;
+- pointers to canonical repository instructions and applicable project skills;
+- checkpoint and transition policy;
+- packet root, working location, branch, immutable base commit, initial HEAD, pre-existing state, packet isolation, and exact review range;
+- focused and full verification commands;
+- commit policy: every leg that changes delivery files commits all and only its changes, including intended new files, before handoff, while packet updates remain isolated;
+- the two-attempt normal whole-work review/remediation policy, exceptional third-attempt contingency, and review-decision continuity;
+- delivery mechanism; and
+- intervention signal and triggers supplied by this profile, the user, or repository.
+
+### Require shared understanding and approval
+
+The preparation prompt owns the interactive preflight. Create and iteratively update goal-focused `charter.md`, profile-owned `operations.md`, compact `status.md`, and append-only `log.md` as reviewable drafts. Mark status **Draft — awaiting approval; not dispatched**. Use `ask_user` when an answer changes the goal, an edge, target, destructive-data choice, delivery mechanism, working location, or non-obvious base. Ask related questions together. This profile supplies routine mechanics, so the user approves the prepared Relay rather than designing the protocol.
+
+After pointing the user at the final drafts, summarize the goal/edges, operating setup, and first bounded leg, then explicitly ask **Approve and dispatch**, **Revise**, or **Do not dispatch**. Never infer dispatch approval from the initial request, permission to create drafts, or the absence of objections. A material change after approval invalidates it and requires another review. On revision, update and re-present the drafts. On refusal, mark status not dispatched, append the decision, and stop. Drafting and checkout setup may happen before approval; `spawn_session` may not.
+
+### Approved-dispatch workflow
+
+After explicit approval, finalize all four documents, mark the packet approved, and record approval in status and log. Seed active leg tracking with last completed leg 0, the first leg identifier/task, targeted context, blockers, `review attempts: 0`, `third-attempt contingency: unused`, and any active pointers. In fresh-worktree mode, move the packet into the target worktree, update recorded paths and location facts, and remove the stale drafting copy before handoff.
+
+Dispatch exactly one first leg with `spawn_session`, after all state is durable in its final location. Use the selected checkout/worktree as `cwd`. After `spawn_session` returns, report the Relay name, packet path, location and branch, interpreted finish line and material non-goals, delivery target, first leg, and dispatch confirmation. Perform no further operational action and never promise a total leg count.
+
+## Run every leg
+
+Use this loop:
+
+1. Read `charter.md`, `operations.md`, `status.md`, and only targeted context they reference. Then load canonical project skills applicable to this leg.
+2. Confirm that the prompt's leg identifier, status baton, working location, branch, and blockers are consistent. Resolve small baton defects with targeted inspection; intervene instead of broad archaeology or guessing about intent.
+3. Use status's next outcome as the starting point. Revise inherited sequencing or design when a simpler connected slice better advances it. Safe implementation splits within the charter are runner decisions, not approval requests. If the intended outcome remains ambiguous or falls outside the finish line, intervene.
+4. Re-anchor to the finish line and perform the containment check. Do exactly one bounded slice. Do not audit unrelated code, execute the next nominal leg too, or expand scope under the guise of quality.
+5. Run every focused check meaningful for the slice and report exact results. Before whole review, run the full verification named by `operations.md`. Never describe failed, skipped, or incomplete verification as passing.
+6. Make delivery changes durable under the operations record's commit policy without absorbing unrelated state. Keep packet-only writes out of delivery commits.
+7. Update status with the observable progress, completed and next leg identifiers, next outcome, existing seam to connect, concrete constraints, remaining unconnected work, targeted context, verification state, blockers and active transition/review pointers. Keep route choices provisional. Append the concise leg entry to the log before stopping or handing off.
+8. Stop without spawning when Relay completion is recorded, the leg is blocked, or an intervention trigger fires. When the chartered outcome is implemented but required review, approval, or delivery remains, name that lifecycle work as the next leg instead of stopping. Surface the intervention signal clearly. Otherwise hand off exactly once at the end with `spawn_session`.
+
+Use this handoff shape, substituting the actual paths and next identifier:
+
+```text
+Relay "<name>" leg <identifier> begins now.
+
+Work under the Relay method with the `relay-runner` operational profile.
+Load the `relay` and `relay-runner` skills, then read:
+- .pi-web/relays/<name>/charter.md
+- .pi-web/relays/<name>/operations.md
+- .pi-web/relays/<name>/status.md
+
+Do not read log.md end-to-end. Use only targeted entries referenced by charter.md, operations.md, or status.md.
+Run exactly one outcome-led leg under the profile's implementation-first rules. Use status's next outcome and connection priority; adapt the route within the charter. Make work and packet updates durable, then either hand off once or stop with the recorded intervention signal.
+```
+
+## Whole-work review and remediation
+
+Run whole-work review immediately before delivery and only after implementation and verification are believed complete and no transition remains active.
+
+Approval means the reviewed evidence reasonably demonstrates the chartered finish line under the repository's canonical quality guidance; it does not claim the work is perfect or free of every possible defect. Reviewers are not expected or rewarded to produce findings. A clean approval is the correct result when no concretely supported blocker is found.
+
+Use **two normal whole-work review attempts** from implementation-complete through delivery: the initial review and, only when needed, one post-remediation or pre-delivery re-review. A third review is an exceptional contingency, not routine capacity or a target. Invoke it only under the attempt 2 finding rule below or when delivery finds that materially changed review inputs made the prior approval stale. Record `review attempts: N` and `third-attempt contingency: unused` in status, changing the contingency field to `invoked — <reason>` before using it. Append each attempt, base, and HEAD to the log. Focused subreviews consolidated by one reviewer are part of one attempt, not separate attempts.
+
+Attempt 1 is the only broad, proportionate review pass. Report its concretely supported blockers together rather than serializing already-known concerns across later attempts; this calls for a proportionate pass, not an exhaustive search. Later reviews still judge the exact delivery diff as a whole, but carry prior decisions forward and focus on remediation, changed evidence, and regressions. Do not restart review from zero, expand the audit surface, or apply a newly stricter standard because another attempt is available.
+
+For each attempt:
+
+- Review the exact delivery diff recorded in `operations.md` against the charter's goal and edges and the repository's canonical quality instructions. Do not derive a technical bug-hunting checklist from incidental charter wording.
+- Keep the reviewer report-only for implementation and delivery artifacts. Its only writes are packet updates needed to record review and handoff.
+- Confirm the full verification required by `operations.md` at the reviewed HEAD and record exact results.
+- Approve when no blocking finding meets the evidence threshold below, even if non-blocking limitations or theoretical risks remain. Record exact reviewed base and HEAD, point status at the approval, and name delivery as next.
+- When attempt 1 has blocking findings, record them in risk order in the log, name one coherent remediation leg in status with a targeted pointer, and dispatch it. Remediation runners resolve the recorded blockers in bounded slices and dispatch attempt 2 only after the attempt 1 report has been addressed; do not spend another whole-work review merely to reveal the next already-known item.
+- When attempt 2 has a blocking finding, do not automatically consume attempt 3. Invoke the remediation contingency only when concrete evidence shows that an attempted remediation reasonably expected to resolve a blocker did not, remediation introduced an in-scope regression, or materially new evidence reveals a blocker that could not reasonably have been assessed earlier—and one bounded remediation is likely to resolve it. Record that justification, mark the contingency invoked, and dispatch one coherent remediation leg followed by attempt 3. Expanded scrutiny, a changed standard, deferred already-available evidence, or speculative possibility does not qualify. If a genuine blocker remains but the contingency is not justified or bounded, intervene.
+- When exceptional attempt 3 still has any blocking finding, stop the automatic loop. Record the unresolved findings and exact decision needed, raise the human intervention signal, and do **not** dispatch remediation or a fourth review. A human may accept an authorized risk, change the agreement, stop the Relay, or explicitly grant a bounded additional remediation/review attempt.
+
+The reviewer chooses proportionate independent review and records that decision. Independent subreviews are optional; use them only when a specific changed surface benefits from focused expertise, not to create review theater or increase the chance of finding something. The reviewer may use `spawn_subsession` for report-only focused reviews, then `yield_to_subsessions` and consolidate. Subreview prompts must identify repository, base and exact diff, the charter's goal and edges, canonical quality instructions, and the prohibition on all writes including packet changes. The consolidating reviewer is the sole packet writer. The Relay handoff still uses one `spawn_session` only at the end of the leg.
+
+A blocking finding needs concrete evidence of an in-scope defect: for example a reproduced failure, a failing relevant check, a specific execution path that violates the approved outcome, or a clear breach of a material contract, invariant, security, authorization, or data-integrity boundary. Mere possibility, stylistic preference, optional hardening, hypothetical future requirements, or “there could be an edge case” is not blocking. If proportionate targeted inspection cannot establish applicability and impact, classify the concern as non-blocking or omit it rather than forcing remediation.
+
+Review cannot over-specify the agreement. Decide materiality from the charter's goal and edges and the repository's canonical guidance, not from a reviewer-created standard. A concern outside those authorities is non-blocking or out of scope even when it describes a possible improvement. Non-blocking findings do not prevent approval or consume a remediation leg. Do not turn review into an audit of unrelated pre-existing shortcomings.
+
+### Review-decision continuity
+
+Create `review-decisions.md` only when a finding disposition must survive into later reviews. Point to it from status continuously through remediation and delivery; later reviewers read it instead of reconstructing history from the log.
+
+Give recurring findings stable identifiers. Record concern, disposition, concise rationale, evidence, authority, applicability, and revisit conditions. A remediated decision cites the fixing commit and verification. Not-applicable cites concrete evidence. Accepted-risk or out-of-scope cites an exact charter edge, canonical project guidance, or explicit human direction. Do not create speculative risk analyses merely to populate the register.
+
+Do not duplicate an existing finding. Honor supported decisions while facts remain unchanged, but reopen for materially new evidence, changed applicability, or a demonstrable error or charter conflict. Record what supersedes the old decision. A reviewer cannot unilaterally waive an in-scope defect.
+
+Keep the register compact and current. It is subordinate to the charter: changing the goal, minimum outcome acceptance, or a scope edge requires human agreement, a charter update, and a log entry.
+
+## Delivery finish
+
+The final leg performs only the delivery mechanism recorded in `operations.md`.
+
+1. Read the targeted approval entry cited by status.
+2. Verify that the integration base still resolves to the reviewed base commit, HEAD equals the reviewed HEAD, and the working tree matches the allowable state recorded in `operations.md`, normally clean apart from the packet.
+3. If the base advanced or expected in-scope work changed, intervene when the mismatch is unrelated, unexpected, or of unclear ownership. Otherwise dispatch a fresh whole-work review when a normal attempt remains. After two attempts, invoke the exceptional third only when the changed inputs materially invalidate the prior approval and a targeted review can assess the new exact range; record that reason before dispatch. If neither condition applies, intervene.
+4. Create or update the recorded pull/merge request, push the branch, produce the agreed patch, or leave the agreed clean committed local branch. Do not invent delivery infrastructure the repository does not use.
+5. State what changed and why, behavioral or contract changes, migration or deployment ordering when applicable, and exact verification with results.
+6. Record the delivery result—URL, pushed branch, patch path, or local commit/branch—in status and log before declaring completion. Required push, authentication, or review-tool failure is intervention, not completion.
+
+## Intervention triggers
+
+Stop, update status, append the log, surface the intervention signal recorded in `operations.md`, and do not spawn when:
+
+- the finish line or a stable outcome must change without explicit human agreement;
+- the environment is unusable;
+- destructive-data behavior is ambiguous;
+- a product or business decision lies outside the charter;
+- proceeding would knowingly weaken a material invariant or security/authorization boundary;
+- unexpected unrelated branch changes make ownership or the review range unclear;
+- required delivery or authentication fails;
+- review remains blocked after the normal attempts and the third-attempt contingency is unavailable or exhausted;
+- the finish line is infeasible; or
+- another user-, repository-, charter-, or operations-defined trigger fires.
+
+Ordinary implementation defects stay within the agreed route and review findings go through remediation. Neither justifies changing scope, ignoring canonical project guidance, or relabeling unexpected breakage as transitional.

package/dist/pi-web-plugins/files/browser/assets/files-icon-DZObYhxb.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M3 6.5A2.5 2.5 0 0 1 5.5 4H10l2 2h6.5A2.5 2.5 0 0 1 21 8.5v8A2.5 2.5 0 0 1 18.5 19h-13A2.5 2.5 0 0 1 3 16.5z"/>
+</svg>