pi-delegation-policy 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.1.2 - 2026-08-26
+
+### Fixed
+
+- Restored the canonical role-selection guidance for bounded execution, planning and ambiguity, repetitive volume, and exceptional blockers.
+- Made the `normal` and `aggressive` thresholds and the three Small/Medium preference biases operational at their boundaries.
+- Corrected session-branch guidance: a session without policy state starts at `off`, while a fork inherits the latest valid entry in its active history.
+
+## 0.1.1 - 2026-08-26
+
+### Added
+
+- Added a public task-oriented documentation site on GitHub Pages.
+
+### Fixed
+
+- Clarified that the selector reset action changes the draft until you apply it.
+
+### Security
+
+- Restricted documentation deployments to `main`, isolated pull request cancellation, and pinned privileged workflow actions.
+
 ## 0.1.0 - 2026-08-25
 
 ### Added

package/README.md

@@ -2,7 +2,9 @@
 
 A local Pi extension that lets you choose delegation intensity and exact model references for Small, Medium, Large, and an optional UI Design role. It guides the main agent; it does not run, route, or enforce delegated work.
 
-> **Status:** Version 0.1.0 is available from npm. Every new session starts at `off`.
+> **Status:** Version 0.1.2 is available from npm. Every new session starts at `off`.
+>
+> **Documentation:** Read the [documentation site](https://yivas.github.io/pi-delegation-policy/).
 
 ## What it does
 
@@ -37,7 +39,9 @@ It supports Pi `0.84.1`. Restart Pi or run `/reload` after installation. To inst
 /delegate reset                   Reset this session branch to off
 ```
 
-`Ctrl+Shift+D` opens the selector when the shortcut is available. The footer shows `D:OFF`, `D:NORM`, `D:AGG`, or `D:ERR` without replacing Pi's own status.
+`Ctrl+Shift+D` opens the selector when the shortcut is available. There is no separate off shortcut; use `/delegate off` or choose `off` in the selector. Changes apply to the next agent run. An agent already running keeps the system prompt it started with.
+
+The footer shows `D:OFF`, `D:NORM`, `D:AGG`, or `D:ERR` without replacing Pi's own status.
 
 ## Configuration
 
@@ -78,29 +82,36 @@ Schema version 1 is inactive and is not migrated automatically. Open `/delegate`
 
 ### Global defaults and session branches
 
-A new session or branch always starts at `off`. It inherits global model references and preference until `/delegate` changes a field in that branch. Session fields override only their matching global values. Selecting **Save effective configuration as defaults** copies the current roles, preference, and UI Design setting to the global file without copying intensity.
+A new session with no delegation entry starts at `off`. A branch restores the latest valid delegation entry in its active history, so a fork created after `normal`, `aggressive`, or `off` inherits that state until the branch records another change. Global model references and preference apply until the session branch overrides their matching fields. Selecting **Save effective configuration as defaults** copies the current roles, preference, and UI Design setting to the global file without copying intensity.
 
 `/delegate reset` writes a session state with `off` and returns non-intensity fields to their global defaults.
 
 ### Intensity
 
-- `off` injects nothing. Invalid or incomplete defaults still show `D:OFF`.
-- `normal` delegates substantial, bounded, independent work when doing so saves effort without losing essential context.
-- `aggressive` favors delegating that work when its objective and acceptance criteria are clear.
+- `off` injects nothing into the next agent run. Pi rebuilds the system prompt for each run, so a policy injected into an earlier run is absent; an agent already running is not rewritten. Invalid or incomplete defaults still show `D:OFF`.
+- `normal` delegates substantial, separable work only when the expected benefit clearly outweighs briefing, supervision, review, and integration. It keeps borderline work with the main agent.
+- `aggressive` delegates substantial, separable, independently checkable work by default when it has a clear objective and acceptance criteria. A plausible benefit can be enough, but tightly coupled work or clearly prohibitive overhead stays with the main agent.
 
-The main agent keeps global decisions, coordination, integration, and final review in every mode.
+The main agent keeps global strategy, coordination, integration, final review, and work whose essential context is too costly or risky to transfer in every mode.
 
 ### Model roles and preference
 
 Active modes require exact `provider` and `model` references for Small, Medium, and Large. Pi must expose each reference in the current scope or available model catalog, and its provider must be authenticated. A missing, out-of-scope, unavailable, or unauthenticated role produces `D:ERR` and injects no policy. The extension never substitutes another model or role.
 
-The preference only changes the policy's selection bias:
+The policy chooses a role and thinking together from task demand, difficulty, and quantity. No single factor decides the role:
+
+- Small is habitual for bounded, planned, and verifiable execution. Difficult but well-defined work can remain Small with higher thinking.
+- Medium can be selected directly when the combined demands materially require planning, ambiguity reduction, broad synthesis, several-module tracing, comparison, context coordination, or difficult decisions. Small does not need to fail first.
+- Large is exceptional and only unblocks genuinely stuck work, such as persistent failures, severe framework conflicts, or contradictory hypotheses. Reliable prior evidence can justify it without ceremonial failed attempts.
+- Large quantities of repetitive, independent work favor multiple Small delegations. Agent type does not determine the model role.
+
+Preference shifts credible Small/Medium choices; a clearly better task fit overrides it:
 
-- `efficient` favors Small.
-- `standard` uses Small for routine work, Medium for planning, ambiguity, or broad synthesis, and Large for exceptional blockers.
-- `intensive` favors Medium.
+- `efficient` favors Small more strongly and uses Medium when it provides a material advantage.
+- `standard` reproduces the canonical policy and chooses Small on a genuine Small/Medium tie.
+- `intensive` normally favors Medium for non-trivial bounded work when both roles are credible, while retaining Small for clearly narrow, routine, mechanical, or especially clear Small work.
 
-All three ordinary roles remain available in every preference. The main agent chooses thinking for each delegated task from the task, difficulty, volume, and model capabilities. Thinking is not configured or persisted by this extension.
+All three ordinary roles remain available in every preference. The main agent chooses thinking for each delegated task from task demand, difficulty, quantity, and model capabilities. Thinking is not configured or persisted by this extension.
 
 UI Design is optional. When configured, it is limited to visual design direction, exploration, and review. It must not implement an interface, write code, or run tests. When it is off, ordinary roles handle design-related work.
 

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.1.0 is the first supported release.
+Only the latest published version is supported. Version 0.1.2 is the current supported release.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",
   "license": "MIT",
   "repository": "https://github.com/Yivas/pi-delegation-policy",
   "bugs": "https://github.com/Yivas/pi-delegation-policy/issues",
-  "homepage": "https://github.com/Yivas/pi-delegation-policy",
+  "homepage": "https://yivas.github.io/pi-delegation-policy/",
   "keywords": [
     "pi-package",
     "pi-extension",

package/src/prompt.ts

@@ -2,18 +2,34 @@ import { hasRuntimeError, type RuntimeState } from "./runtime.ts";
 import type { ModelRef, Preference } from "./types.ts";
 
 const NORMAL_POLICY =
-  "Delegate substantial, bounded, and independent work when doing so reduces effort without losing essential context. Keep architecture, global strategy, coordination, integration, final review, and work whose context is costly or risky to transfer in the main agent.";
+  "Delegate substantial, separable work only when the expected benefit clearly outweighs briefing, supervision, review, and integration cost. Count parallelism as a benefit only when valuable work can advance now or elapsed time matters. A merely possible fresh perspective is not enough by itself. Keep borderline work with the main agent.";
 const AGGRESSIVE_POLICY =
-  "Default to delegating substantial work with a clear objective and acceptance criteria. Keep global decisions, coordination, integration, final review, and work whose context is costly or risky to transfer in the main agent.";
+  "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 ROLE_SELECTION_POLICY = `Choose the role and thinking together from the combination of:
+- task demand: execute, search, plan, decide, or unblock;
+- difficulty: clarity, ambiguity, dependencies, risk, and competing hypotheses;
+- quantity: files, modules, systems, sources, and context volume.
+No single factor decides the role.
+
+Use Small habitually for bounded, planned, and verifiable work: concrete searches, scoped exploration, defined implementation, focused documentation, tests, reviews, mechanical changes, evident bugs, and bounded UI implementation whose design and stack are decided. Difficult but well-defined execution can remain Small with higher thinking.
+
+Use Medium directly when the combined demands materially require defining a plan, reducing meaningful ambiguity, broad synthesis, tracing several modules, comparing sources or options, coordinating substantial context, or making difficult decisions. These are evidence, not automatic triggers. Small does not need to fail first.
+
+Use Large only to unblock genuinely stuck work: persistent failures, severe framework conflicts, contradictory hypotheses, or reliable prior evidence that ordinary roles have not produced a trustworthy answer. Do not require ceremonial failed attempts. Large remains exceptional.
+
+Large quantities of repetitive, independent work favor multiple Small delegations; volume alone does not justify Medium or Large. Agent type does not determine the model role. A clearly better task fit overrides preference; preference only shifts credible Small/Medium choices.
+
+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.`;
 
 function preferenceGuidance(preference: Preference): string {
   if (preference === "efficient") {
-    return "Favor Small for routine delegated work. Medium and Large remain available when the task warrants them.";
+    return "Favor Small more strongly than standard. When Small can safely satisfy the acceptance criteria, choose it unless Medium provides a material advantage.";
   }
   if (preference === "intensive") {
-    return "Favor Medium for substantial delegated work. Small and Large remain available when the task warrants them.";
+    return "When Small and Medium are both credible, normally prefer Medium. Keep Small for work that is clearly narrow, routine, mechanical, or an especially clear Small fit.";
   }
-  return "Use Small for routine delegated work, Medium for planning, ambiguity, or broad synthesis, and Large only for exceptional blockers.";
+  return "Choose Small on a genuine Small/Medium tie; otherwise follow the role-selection policy above.";
 }
 
 function promptString(value: string): string {
@@ -42,9 +58,11 @@ export function buildDelegationPolicy(state: RuntimeState): string | undefined {
 Intensity: ${effective.intensity}.
 ${intensityPolicy}
 
+${ROLE_SELECTION_POLICY}
+
 Model preference: ${effective.preference}. ${preferenceGuidance(effective.preference)}
 
-Use the exact provider and model for the selected role. The references below use JSON string syntax; interpret escaped characters as JSON before use. Do not invent a fallback model or role. Choose thinking dynamically for each delegation from the task, difficulty, volume, and the selected model's capabilities. Do not treat thinking as persisted configuration.
+Use the exact provider and model for the selected role. The references below use JSON string syntax; interpret escaped characters as JSON before use. Do not invent a fallback model or role. Choose thinking dynamically for each delegation from task demand, difficulty, quantity, and the selected model's capabilities. Do not treat thinking as persisted configuration.
 
 Roles:
 - Small: ${formatReference(effective.small)}

package/src/ui.ts

@@ -30,7 +30,7 @@ const USE_GLOBAL_DEFAULT = "Use global default";
 const DISABLE_FOR_SESSION = "Disable for this session";
 const APPLY_TO_SESSION = "Apply changes to this session";
 const SAVE_AS_DEFAULTS = "Save effective configuration as defaults";
-const RESET_SESSION = "Reset session to off";
+const RESET_SESSION = "Reset draft to off";
 const CANCEL = "Cancel";
 
 type ModelSelection =