pi-delegation-policy 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.8.0 - 2026-09-07
+
+### Changed
+
+- Tighten `orchestrator` guidance to require delegation before all transferable execution, including detailed review and integration mechanics; require waiting for and consuming pending results, concrete gap-only reinspection, and a brief exception before minimum direct work. Size, triviality, convenience, economics, transfer cost, and final-review or integration labels are not bypasses. The published `0.7.0` policy remains unchanged.
+
 ## 0.7.0 - 2026-09-06
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 A local Pi extension that helps the main agent decide **when delegation is worth it** and which exact models to use for Small, Medium, Large, and optional Visual Design. It provides guidance; it is not a subagent runner.
 
-> **Status:** Version **0.7.0** is the latest published package and supports `off`, `normal`, `aggressive`, and `orchestrator`. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline.
+> **Status:** Version **0.8.0** is the latest published package and supports `off`, `normal`, `aggressive`, and `orchestrator`. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline.
 >
 > **Docs:** [Read the documentation site](https://yivas.github.io/pi-delegation-policy/).
 
@@ -13,13 +13,13 @@ A local Pi extension that helps the main agent decide **when delegation is worth
 - Keep global defaults and session-branch overrides across reload, resume, and tree navigation.
 - Validate active configurations before injecting one policy block through Pi's public `before_agent_start` event.
 
-The extension guides the main agent. It never creates, launches, routes, supervises, or blocks subagents; changes Pi's main model or thinking; stores credentials; intercepts tools; or makes its own network requests. `orchestrator` delegates transferable execution detail and batches small work while the main agent retains objectives, critical decisions, coordination, integration responsibility, requested evidence, and final acceptance. It has no model fallback, telemetry, project configuration, presets, or external skill loading.
+The extension guides the main agent. It never creates, launches, routes, supervises, or blocks subagents; changes Pi's main model or thinking; stores credentials; intercepts tools; or makes its own network requests. In `0.8.0` `orchestrator`, an enabled capable role and authorized launcher require delegation of all transferable execution before it begins, regardless of size: small lookups, code reading, detailed planning, edits, tests, writing, detailed review, and integration mechanics. Bootstrap is limited to mandatory instructions, tool discovery, and a narrow assignment scope; after assigning, the main agent coordinates only disjoint work, waits through the host, and consumes results before dependencies or finalizing. It retains strategy, critical user decisions, coordination, safety, evidence evaluation, final acceptance, and concise synthesis, not permission to perform transferable review or integration. Direct work requires a briefly stated concrete exception: genuinely non-transferable work, no enabled capable role, a confirmed unavailable authorized launcher, or an explicit user or higher-priority requirement. It reinspects only a concrete gap, risk, or contradiction and delegates transferable fixes or rechecks. A final-review or integration label, size, triviality, convenience, economics, transfer cost, or familiarity never justifies doing the whole task personally. Published `0.7.0` retains its original policy; `0.8.0` contains this stricter guidance. It has no model fallback, telemetry, project configuration, presets, or external skill loading.
 
 A valid active policy requires an explicit decision for Small, Medium, and Large: an exact model reference or disabled. At least one ordinary role must remain enabled. A disabled role is not validated. An absent role, an invalid enabled reference, or no enabled ordinary role produces `D:ERR` and injects no policy. `off` always produces `D:OFF` without injection.
 
 The policy considers only enabled ordinary roles, chooses the least costly role that can satisfy the task's acceptance criteria and evidence, and keeps work with the main agent when none can. It never invents a model or role. `efficient` and `intensive` are tie-breaks only when both Small and Medium are enabled; otherwise their bias is inactive.
 
-Visual Design is an independent optional specialist for direction, assets, bounded presentation-layer implementation, and visual review. Use it only when behavior and data contracts are already defined and unchanged, the affected surface is bounded, and visual quality or user experience is the primary acceptance criterion. It does not count as an ordinary role or replace one. Route business logic, data, APIs, routes, application architecture, tooling, interaction behavior, and cross-system integration to an enabled ordinary role by task fit. The main agent retains final integration and acceptance.
+Visual Design is an independent optional specialist for direction, assets, bounded presentation-layer implementation, and visual review. Use it only when behavior and data contracts are already defined and unchanged, the affected surface is bounded, and visual quality or user experience is the primary acceptance criterion. It does not count as an ordinary role or replace one. In published `0.7.0` and `normal` or `aggressive`, route business logic, data, APIs, routes, application architecture, tooling, interaction behavior, and cross-system integration to an enabled ordinary role by task fit; the main agent retains final integration and acceptance. In `0.8.0` `orchestrator`, the main agent instead retains integration responsibility, coordination, and final acceptance while a capable ordinary role performs transferable integration mechanics and detailed review unless a named direct-work exception applies.
 
 ## Install and start
 

package/SECURITY.md

@@ -14,4 +14,4 @@ Include the affected version or commit, operating system, Pi version, reproducti
 
 ## Supported versions
 
-Only the latest published version is supported. Version 0.7.0 is the current supported release.
+Only the latest published version is supported. Version 0.8.0 is the current supported release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",

package/src/prompt.ts

@@ -11,7 +11,7 @@ const NORMAL_POLICY =
 const AGGRESSIVE_POLICY =
   "Default to delegating substantial, separable, independently checkable work with a clear objective and acceptance criteria. Delegate when the benefit is plausible even if not proven, including a useful independent perspective. Keep work with the main agent when it is poorly bounded, tightly coupled, dominated by integration or final accountability, or has clearly prohibitive delegation overhead.";
 const ORCHESTRATOR_POLICY =
-  "Minimize the main agent's execution and generated narration without surrendering ownership. Delegate research, detailed planning, implementation, testing, detailed writing, review, and integration mechanics when the work is transferable and a capable enabled role can satisfy the objective, acceptance, and evidence. Batch small independent work when doing so reduces launches and duplicated context, request minimal briefs and results with file references and evidence, and do not duplicate inspection unless there is a concrete gap, risk, or contradiction. Keep objectives, critical decisions, coordination, integration responsibility, requested detail, safety, and final acceptance with the main agent. Delegate detailed review and integration mechanics when transferable; final acceptance does not require the main agent to execute every detail. Keep narration and final text concise, but never omit risks, evidence, safety, or requested detail. Do not promise savings or force recursive fanout. Do work directly, regardless of size, when it is not transferable, no enabled role can satisfy it, or transfer and context costs exceed doing it here.";
+  "Delegate all transferable execution before performing it whenever an enabled capable role and authorized launcher are available, regardless of size. This includes small lookups, code reading, detailed planning, implementation, tests, writing, detailed review, and integration mechanics. Perform only minimal bootstrap: mandatory instructions, tool discovery, and narrow assignment scope; do not pre-solve or broadly inspect the repository. Batch small tasks without forcing recursive fanout. After assigning a task, do not take it over or run an equivalent worker while it is pending; coordinate only disjoint work, use the host wait/completion mechanism, and consume its result before dependent work or finalizing. Retain strategy, objectives, critical user decisions, coordination, safety, evidence evaluation, final acceptance, and concise synthesis; final responsibility does not permit personally completing review or integration mechanics. Reinspect returned work only for a concrete gap, risk, or contradiction; delegate transferable fixes or rechecks. Direct execution is allowed only for genuinely non-transferable work, no enabled capable role, a confirmed unavailable authorized launcher, or an explicit user or higher-priority requirement. Before direct work, state the concrete exception briefly, do only the minimum, do not repeat it while unchanged, and resume delegation when it ends. Never use a final-review or integration label to do the whole task personally. Triviality, convenience, economics, transfer cost, size, or familiarity do not justify direct execution. Keep narration concise, but never omit requested detail, risks, evidence, or safety information. Do not promise savings.";
 
 const ROLE_SELECTION_POLICY = `Choose the role by task fit before considering model preference:
 - demand: execute, search, plan, decide, coordinate, or unblock;
@@ -31,7 +31,7 @@ A more capable enabled role may cover work normally suited to a disabled role on
 const LEGACY_OWNERSHIP_POLICY =
   "In every intensity, keep global strategy, coordination, integration, final review, and work whose essential context is too costly or risky to transfer with the main agent.";
 const ORCHESTRATOR_OWNERSHIP_POLICY =
-  "In orchestrator, keep global strategy, objectives, critical decisions, coordination, integration responsibility, requested evidence, safety, and final acceptance with the main agent. Detailed review and integration mechanics may be delegated when transferable; retaining final responsibility does not require executing every detail.";
+  "In orchestrator, keep global strategy, objectives, critical decisions, coordination, safety, evidence evaluation, final acceptance, and concise synthesis with the main agent. The main agent MUST delegate transferable detailed review and integration mechanics; final responsibility does not permit personal execution except under the named direct-work exceptions.";
 
 const VISUAL_DESIGN_POLICY = `Visual Design is an optional specialist role. Use it only when all four conditions hold:
 1. the primary acceptance criterion is a visual or user-experience result;
@@ -39,9 +39,11 @@ const VISUAL_DESIGN_POLICY = `Visual Design is an optional specialist role. Use
 3. the patch is bounded to an identifiable surface, component, or set of assets;
 4. it requires no business logic, data flow, APIs, routes, application architecture, tooling, or cross-system coordination.
 
-When eligible, Visual Design may design, create, implement, and review scoped presentation code and visual assets, including layout, styles, responsive presentation, typography, images, icons, logos, SVGs, diagrams, and documentation visuals. It may address visual accessibility such as contrast and focus visibility. It must run and report the relevant existing checks for its patch.
-
-Route interaction behavior, state, validation, semantic HTML changes, keyboard mechanics, ARIA behavior, authentication, permissions, persistence, test infrastructure, and behavior-test ownership to an enabled ordinary role that fits, or keep it with the main agent. If any eligibility condition fails, use an enabled ordinary role or split the visual portion from the broader task. The main agent retains cross-domain integration and final acceptance.`;
+When eligible, Visual Design may design, create, implement, and review scoped presentation code and visual assets, including layout, styles, responsive presentation, typography, images, icons, logos, SVGs, diagrams, and documentation visuals. It may address visual accessibility such as contrast and focus visibility. It must run and report the relevant existing checks for its patch.`;
+const LEGACY_VISUAL_DESIGN_ROUTING_POLICY =
+  "Route interaction behavior, state, validation, semantic HTML changes, keyboard mechanics, ARIA behavior, authentication, permissions, persistence, test infrastructure, and behavior-test ownership to an enabled ordinary role that fits, or keep it with the main agent. If any eligibility condition fails, use an enabled ordinary role or split the visual portion from the broader task. The main agent retains cross-domain integration and final acceptance.";
+const ORCHESTRATOR_VISUAL_DESIGN_ROUTING_POLICY =
+  "In orchestrator, route interaction behavior, state, validation, semantic HTML changes, keyboard mechanics, ARIA behavior, authentication, permissions, persistence, test infrastructure, and behavior-test ownership to an enabled ordinary role that fits. If any eligibility condition fails, use an enabled ordinary role or split the visual portion from the broader task. The main agent retains cross-domain integration responsibility, coordination, and final acceptance, but MUST delegate transferable integration mechanics and detailed review to a capable enabled ordinary role unless a named direct-work exception applies.";
 
 function hasSmallMedium(enabled: readonly ModelRole[]): boolean {
   return enabled.includes("small") && enabled.includes("medium");
@@ -124,7 +126,7 @@ export function buildPolicyPreview(effective: EffectiveDelegateState): string[]
     `Enabled: ${enabled.map(roleName).join(", ")}${disabled.length ? ` · Disabled: ${disabled.map(roleName).join(", ")}` : ""}`,
     `${references} · exact model plus per-task thinking required; neither uses an ambient default.`,
     ...(effective.intensity === "orchestrator"
-      ? ["Batch transferable detail; main agent keeps ownership and final acceptance."]
+      ? ["Delegate all transferable work; main agent keeps final acceptance."]
       : []),
   ];
 }
@@ -149,6 +151,10 @@ export function buildDelegationPolicy(state: RuntimeState): string | undefined {
   const uiDesign = effective.uiDesign
     ? `\n- Visual Design: ${formatReference(effective.uiDesign)}; exact model base: ${formatLaunchModel(effective.uiDesign)}; pi-subagents form: ${formatThinkingLaunchModel(effective.uiDesign)}`
     : "";
+  const visualDesignPolicy =
+    effective.intensity === "orchestrator"
+      ? `${VISUAL_DESIGN_POLICY}\n\n${ORCHESTRATOR_VISUAL_DESIGN_ROUTING_POLICY}`
+      : `${VISUAL_DESIGN_POLICY}\n\n${LEGACY_VISUAL_DESIGN_ROUTING_POLICY}`;
   const roleLines = enabled
     .map((role) => {
       const reference = effective[role] as ModelRef;
@@ -172,7 +178,7 @@ Before every delegated launch, name the selected role and take its exact combine
 
 Roles:
 ${roleLines}${uiDesign}
-${effective.uiDesign ? `\n${VISUAL_DESIGN_POLICY}\n` : ""}
+${effective.uiDesign ? `\n${visualDesignPolicy}\n` : ""}
 This is guidance for the main agent. It does not create, execute, route, supervise, or enforce delegated work.
 </delegation_policy>`;
 }