pi-herdsman 0.31.1 → 0.32.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +7 -0
  2. package/SKILL.md +24 -22
  3. package/dist/agent-definitions/managed-lead.md +4 -0
  4. package/dist/agent-definitions/manager.md +7 -5
  5. package/dist/index.js +6978 -4949
  6. package/dist/index.js.map +4 -4
  7. package/docs/adr/0012-manager-owns-project-assignment-resolution.md +4 -0
  8. package/docs/adr/0013-use-herdr-worktree-removal-for-project-retirement.md +4 -0
  9. package/docs/adr/0017-use-project-assignments-for-managed-lead-authority.md +5 -2
  10. package/docs/adr/0018-use-standalone-lead-execution-profiles.md +4 -0
  11. package/docs/adr/0019-retire-project-assignments-when-worktrees-are-absent.md +4 -0
  12. package/docs/adr/0020-authorize-confirmed-manager-worktree-removal.md +15 -5
  13. package/docs/adr/0022-commit-project-retirement-before-message-cleanup.md +5 -2
  14. package/docs/adr/0023-deliver-worktree-retirement-through-pending-manager-context.md +4 -0
  15. package/docs/adr/0025-propagate-explicit-required-assignment-evidence.md +8 -0
  16. package/docs/adr/0026-manager-owns-project-required-evidence.md +7 -0
  17. package/docs/adr/0028-reference-historical-assignment-evidence.md +54 -0
  18. package/docs/adr/0029-use-immutable-managed-lead-session-identity.md +44 -0
  19. package/docs/adr/0030-project-scoped-manager-removal-approval.md +44 -0
  20. package/docs/adr/0031-durable-manager-worktree-removal-approval.md +46 -0
  21. package/docs/concepts/coordination.md +9 -11
  22. package/docs/concepts/lifecycle.md +14 -5
  23. package/docs/coordination-api.md +2 -5
  24. package/docs/development/instruction-interface-design.md +39 -0
  25. package/docs/development/smoke-testing.md +29 -13
  26. package/docs/development/validation.md +2 -2
  27. package/docs/guides/handoffs.md +34 -20
  28. package/docs/guides/project-orchestration.md +37 -22
  29. package/docs/guides/recovery.md +4 -0
  30. package/docs/reference/agent-states.md +19 -11
  31. package/docs/reference/agent.md +35 -7
  32. package/docs/reference/commands.md +38 -40
  33. package/docs/reference/configuration.md +16 -9
  34. package/docs/reference/peer.md +8 -7
  35. package/docs/reference/staff.md +18 -16
  36. package/docs/reference/status-widget.md +9 -6
  37. package/docs/reference/supervisor.md +3 -1
  38. package/package.json +7 -7
package/README.md CHANGED
@@ -107,6 +107,13 @@ Project work is durable by Git branch. It does not belong to the Manager session
107
107
  that happened to start it, so assignments can be paused, resumed, or retired
108
108
  across Manager turnover.
109
109
 
110
+ Manager-created project Leads are dedicated Managed Lead sessions: identity stays
111
+ with the exact Pi session, while only a current project assignment authorizes
112
+ execution. Unavailable or retired assignments never enable ordinary Lead tools.
113
+ Use native Pi `/fork` or `/clone` for independent ordinary continuation with copied
114
+ history, not a separate checkout or fresh process configuration. See
115
+ [Project orchestration](docs/guides/project-orchestration.md#dedicated-sessions-and-independent-continuation).
116
+
110
117
  See [Coordination](docs/concepts/coordination.md) for the mental model and
111
118
  [Project orchestration](docs/guides/project-orchestration.md) for the Manager
112
119
  workflow.
package/SKILL.md CHANGED
@@ -31,24 +31,26 @@ Use these high-salience rules for the model-facing agent boundary:
31
31
  execute or assign overlapping work while it is delegated.
32
32
  - For any coordination tool that accepts `files`, pass every user-supplied or
33
33
  already-available artifact relevant to what the recipient must do or decide
34
- that is not already registered as required evidence for the recipient's
34
+ that is not already registered as retained evidence for the recipient's
35
35
  verified assignment. Do not assume another session inherits arbitrary
36
36
  conversation or attachments. Preserve exact supplied result refs when
37
37
  forwarding them and omit unrelated evidence. `files` carries evidence, not
38
38
  runtime capability.
39
- - For a verified managed project assignment, required evidence is supplied to
39
+ - For a verified managed project assignment, retained evidence is supplied to
40
40
  new descendant assignments automatically. Use `files` for relevant evidence
41
- not registered as required or specific to one recipient. When forwarding
42
- evidence that must remain required downstream, set `retain: true` on
41
+ not registered as retained or specific to one recipient. When forwarding
42
+ evidence that must remain available downstream, set `retain: true` on
43
43
  `message_staff` (Manager, retaining its message text and files for the
44
44
  target project assignment) or `delegate_agent` (retaining its files, not its
45
45
  task text, eligible managed Agents only, for their own descendants).
46
+ Retained evidence is available to eligible descendants; inspect relevant
47
+ references as needed, not every entry.
46
48
  Project-wide requirements are controlled only by the Manager. Leads forward
47
49
  continuing findings through `message_supervisor.files` for Manager evaluation;
48
50
  ordinary delegation files remain recipient-specific. On supported operations,
49
51
  omitted or false `retain` keeps files one-time. Never assume retention if it fails.
50
52
  Ordinary Leads without a verified project assignment have no automatic
51
- required-evidence scope.
53
+ retained-evidence scope.
52
54
  - When agent work is unresolved, handle required agent control, then continue
53
55
  only necessary work you still own or end the turn without concluding; agent
54
56
  results or attention will resume the session automatically. Do not check
@@ -176,12 +178,15 @@ conflict resolution, and final technical decisions within your assigned
176
178
  objective. Decompose only as far as useful. Reuse adequate existing evidence
177
179
  instead of duplicating work. The active Lead execution profile determines the
178
180
  balance between direct and delegated work. Ordinary Leads use `flexible-lead`
179
- or `orchestrator-lead` according to their persisted `Flexible` or
180
- `Orchestrate` execution mode. Manager-assigned Leads use `managed-lead`; the
181
+ or `orchestrator-lead` according to their persisted `flexible` or
182
+ `orchestrate` execution mode. Manager-assigned Leads use `managed-lead`; the
181
183
  exact current `ProjectAssignment`, not the profile, establishes Manager
182
- authority. Confirmed `/takeover` releases that authority and continues the
183
- session in ordinary Orchestrate mode. Lead execution configuration does not
184
- change Agent ownership semantics.
184
+ authority. Managed identity is permanent for the exact Pi session, including
185
+ when assignment evidence is unavailable or the assignment is retired. Only a
186
+ current exact assignment permits fresh project execution; exactly owned Agent
187
+ recovery remains separate. Use native Pi `/fork` or `/clone` for independent
188
+ ordinary continuation, not a separate Git checkout or fresh process configuration.
189
+ Lead execution configuration does not change Agent ownership semantics.
185
190
 
186
191
  <!-- pi-herdsman-runtime-lead:end -->
187
192
 
@@ -216,7 +221,7 @@ authority, and acceptance criteria.
216
221
 
217
222
  Treat supplied files as message evidence. Complete strict UTF-8 text may be
218
223
  embedded; other files are canonical local references and are not copied or
219
- snapshotted. The exception is required evidence in a verified project
224
+ snapshotted. The exception is retained evidence in a verified project
220
225
  assignment: supported text up to 1 MiB is preserved and automatically
221
226
  propagated to new descendants; unsupported or oversized evidence cannot be
222
227
  registered. Reference delivery to a preserved snapshot remains possible when
@@ -405,7 +410,7 @@ Chief uses `list_staff`, `inspect_staff`, `read_staff_transcript`, and
405
410
  `message_staff`. Manager has those same direct-report tools, peer tools, and
406
411
  `delegate_project`, `resume_project`, and `stop_lead`.
407
412
  For administrative removal of a project-owned evidence requirement, use the
408
- Manager project-assignment action menu: **Required evidence**, inspect the
413
+ Manager project-assignment action menu: **Retained evidence**, inspect the
409
414
  entry, then **Remove** and confirm. Inherited requirements are protected; this
410
415
  does not delete snapshots or change evidence already accepted by Agents.
411
416
  `inspect_staff` provides bounded live terminal/process evidence;
@@ -469,10 +474,8 @@ Pi Herdsman uses one durable vocabulary:
469
474
  stopped Lead does not retire an assignment while its checkout exists.
470
475
  Successful Herdr worktree removal or verified checkout absence retires the
471
476
  matching assignment and pending project messages while preserving the Git
472
- branch and Pi session. Explicit
473
- `/takeover` by the assigned Lead also releases Manager control and removes
474
- pending project messages while preserving the session, worktree, branch, and
475
- owned Agents. Never infer
477
+ branch and Pi session. Managed identity and exact Agent ownership survive
478
+ retirement; retirement does not imply completion or stop a live Pi process. Never infer
476
479
  ownership from worktree membership or start an overlapping writer beside
477
480
  another Lead;
478
481
  - `/manager leave` preserves project work; a later Manager can resume the same
@@ -483,12 +486,11 @@ Pi Herdsman uses one durable vocabulary:
483
486
  from supervising a Lead and never gives them control over the Lead's tree. A
484
487
  managed project Lead uses
485
488
  `message_supervisor` for timely coordination with its Manager; routine
486
- information that can wait should go in its automatic result. An unassigned
487
- Lead
488
- routes to Chief when available, never to Manager merely because both share a
489
- project scope. Continuing the exact assigned Pi session manually remains
490
- managed; `managed-lead` is launch policy, not authority. Use `/takeover` to
491
- release that assignment explicitly;
489
+ information that can wait should go in its automatic result. An ordinary Lead
490
+ contacts its verified active project Manager, otherwise Chief when eligible.
491
+ A Managed Lead never falls back to Chief when assignment authority is missing.
492
+ Continuing the exact Pi session preserves its kind; `managed-lead` is launch
493
+ policy, not authority;
492
494
  - an **Agent** handles one bounded assignment and may delegate only when its
493
495
  definition allows it;
494
496
  - the **chief** supervises direct reports through `list_staff`,
@@ -16,5 +16,9 @@ assignments only after their prerequisites resolve.
16
16
  Retain decomposition, architecture, technical direction, review, integration,
17
17
  conflict resolution, acceptance, and final technical decisions.
18
18
 
19
+ Resolve technical problems within your assignment using your own reasoning,
20
+ available tools, and Agents. Escalate decisions or blockers outside your
21
+ authority or capabilities; continue independently actionable work.
22
+
19
23
  Surface findings that may change continuing project requirements to the
20
24
  Manager for evaluation.
@@ -8,9 +8,11 @@ tools: []
8
8
 
9
9
  Coordinate assigned project work through Leads.
10
10
 
11
- Set priorities, review outcomes, resolve decisions, request corrections, and
12
- integrate accepted work. Delegate project execution and technical
13
- implementation to assigned Leads.
11
+ Set priorities, resolve project-level decisions and dependencies, review
12
+ outcomes, and request corrections through the responsible Lead.
13
+ Leave technical investigation, implementation, review, validation, and
14
+ integration to that Lead and its Agents rather than doing or delegating
15
+ the work yourself.
14
16
 
15
- Treat routine progress as informational. Provide direction when review,
16
- correction, or a meaningful decision is needed.
17
+ Treat routine progress as informational. Intervene when a project-level
18
+ decision or meaningful coordination is needed.