pi-herdsman 0.2.1 → 0.3.1

package/docs/concepts/delegation.md

@@ -37,6 +37,27 @@ A lead may have many direct agents, and each direct agent that is explicitly
 delegation-enabled may have its own direct agents. A delegation-capable agent
 remains an agent at every depth; it is not a separate public role.
 
+Physical placement is presentation only and never determines ownership. The
+lead's placement setting controls direct agents: `tab` shares one tab per lead,
+`subtree` gives each direct agent a fresh tab, and `split` stays in the caller's
+tab. Nested delegation always splits inside the owner's current tab, regardless
+of the setting.
+
+For example, the logical ownership tree and a subtree layout are separate:
+
+```text
+logical ownership             physical subtree layout
+
+lead                          [lead]
+├── implementer        →      [implementer]
+│   └── scout                  ├─ implementer
+└── reviewer                    │  └─ scout
+                               └─ [reviewer]
+```
+
+Physical layout never determines ownership; the durable owner/session
+relationships do.
+
 ## Inferred `agent` capability
 
 A non-empty `agents` field implies the `agent` tool when the definition uses

package/docs/concepts/lifecycle.md

@@ -107,6 +107,10 @@ agent generation for the new assignment. The continuation uses the saved cwd
 and session history together with the current effective authorized definition
 configuration. Use `delegate.definition` with `fork` when a separate derived
 session is required.
+Session continuation does not retain the old Herdr tab. A still-live
+generation may be restored from its exact managed identity, while ordinary
+same-workspace tab movement remains presentation-only and does not change
+assignment ownership.
 
 ## Steering is different
 

package/docs/development/smoke-testing.md

@@ -26,7 +26,10 @@ The supported repository contract requires:
 - herdr `>=0.8.0`
 - herdr Pi integration version `2` or newer
 
-Run the repository validation gate first.
+Run focused tests and other intermediate checks before this smoke suite. Do
+not format during smoke testing; complete smoke testing and review before the
+final formatting and read-only verification sequence in
+[Development validation](validation.md).
 
 ## Current mailbox contract
 

package/docs/development/validation.md

@@ -5,16 +5,24 @@
 Repository handoff is not complete until the current validation gates have been
 run or a concrete environment blocker is recorded.
 
-## Required gate
+## Validation order
 
-Run:
+Focused tests, smoke testing, review, and all intermediate checks happen first.
+Do not format during those phases. Once implementation and review are
+complete, run the following as the final pre-commit sequence:
 
 ```sh
+# Final pre-commit mutation; run once only.
 prettier . --write
+
+# Read-only verification before staging or committing.
 npm run check
 git diff --check
 ```
 
+Do not run formatting again between these verification commands and staging or
+committing.
+
 When reviewing staged work, also run as appropriate:
 
 ```sh
@@ -82,13 +90,15 @@ tracked separately in [Smoke testing](smoke-testing.md).
 File selection is the primary focusing mechanism. A name pattern narrows the
 tests within the selected file; it does not select which files Node loads.
 
-Before final acceptance, run the full repository gate:
+After focused tests, smoke testing, review, and intermediate checks are
+complete, run the final pre-commit sequence above. The full repository check is
+the read-only verification step:
 
 ```sh
 npm run check
 ```
 
-`npm run check` remains the bounded full gate, including process-group cleanup
+`npm run check` remains the bounded full check, including process-group cleanup
 when the test runner times out or leaks descendants.
 
 ## Dependency availability

package/docs/getting-started.md

@@ -99,8 +99,11 @@ global override. Definition Details shows the effective metadata and can
 expand the resolved definition instructions with Pi's native `Ctrl+O`
 behavior. These edits always write global overrides, never project files.
 
-Use `Layout` to choose the current `tab` or `split` placement for newly started
-agents.
+Use `Layout` to choose the current placement for newly started lead-direct
+agents: `subtree` is the default and gives each lead-direct agent one tab;
+`tab` uses one lead-owned agents tab; `split` stays in the caller's tab. Nested
+delegation always splits inside the owner's current tab. Placement changes
+affect future starts only.
 
 For complete configuration ownership, see:
 

package/docs/reference/agent-definition-schema.md

@@ -19,8 +19,21 @@ tools: ["read", "bash"]
 Prompt body.
 ```
 
-Known string arrays use inline JSON arrays. YAML block sequences are not
-supported.
+Agent definitions use YAML frontmatter. Array fields accept normal YAML flow or
+block sequences.
+
+For example, block sequences are valid for array fields:
+
+```yaml
+---
+name: reviewer
+tools:
+  - read
+  - grep
+skills:
+  - "/absolute/path/to/code-review/SKILL.md"
+---
+```
 
 Unknown frontmatter fields fail validation.
 
@@ -69,14 +82,14 @@ available actions; disabling a definition does not mutate that assignment.
 | `bodyMode`              | `append` or `replace`                                                 | `replace` for non-empty matching overlay body                     | Valid only when overlaying an existing lower-precedence definition; consumed during body composition.  |
 | `noTools`               | boolean                                                               | Pi normal tool policy                                             | `true` emits `--no-tools`; managed `ask_owner` remains infrastructure.                                 |
 | `noBuiltinTools`        | boolean                                                               | Pi normal built-in tool policy                                    | `true` emits `--no-builtin-tools`.                                                                     |
-| `tools`                 | inline array of non-empty strings                                     | no explicit allowlist                                             | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array.          |
-| `excludeTools`          | inline array of non-empty strings                                     | no explicit exclusions                                            | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array.          |
+| `tools`                 | array of non-empty strings                                            | no explicit allowlist                                             | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array.          |
+| `excludeTools`          | array of non-empty strings                                            | no explicit exclusions                                            | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array.          |
 | `noSkills`              | boolean                                                               | skills disabled unless `inheritSkills: true`                      | Controls Pi native skill discovery; explicit `skills` values are still passed separately.              |
 | `inheritSkills`         | boolean                                                               | does not enable by itself unless `true`                           | `true` changes omitted `noSkills` default so native skills remain available. Explicit `noSkills` wins. |
-| `skills`                | inline array of non-empty strings                                     | no explicit skill arguments                                       | Each value is passed unchanged as a Pi skill path/resource.                                            |
+| `skills`                | array of non-empty strings                                            | no explicit skill arguments                                       | Each value is passed unchanged as a Pi skill path/resource.                                            |
 | `noExtensions`          | boolean                                                               | Pi normal extension policy                                        | `true` emits `--no-extensions`. Required herdr agent infrastructure remains injected by the launcher.  |
-| `extensions`            | inline array of non-empty strings                                     | no extra extension arguments                                      | Each value is passed unchanged to Pi.                                                                  |
-| `agents`                | inline array of unique non-empty definition names                     | no direct agents                                                  | Names direct definitions this agent may delegate to; every name must exist.                            |
+| `extensions`            | array of non-empty strings                                            | no extra extension arguments                                      | Each value is passed unchanged to Pi.                                                                  |
+| `agents`                | array of unique non-empty definition names                            | no direct agents                                                  | Names direct definitions this agent may delegate to; every name must exist.                            |
 | `inheritProjectContext` | boolean                                                               | `true` only for definition name `delegate`; otherwise `false`     | Controls project context-file inheritance.                                                             |
 | `inheritGlobalContext`  | boolean                                                               | follows effective `inheritProjectContext`                         | Controls global context-file inheritance.                                                              |
 

package/docs/reference/commands.md

@@ -13,7 +13,7 @@ Commands require a lead Pi session with UI.
 ```text
 /agents
 /agents definitions
-/agents placement [tab|split]
+/agents placement [tab|subtree|split]
 /agents stop
 ```
 
@@ -95,10 +95,12 @@ is sent.
 ## `/agents placement`
 
 Selecting Layout opens a native selector showing the effective setting.
+When unset, the effective setting is `subtree`.
 Explicit values continue to set directly:
 
 ```text
 /agents placement tab
+/agents placement subtree
 /agents placement split
 ```
 

package/docs/reference/configuration.md

@@ -14,7 +14,7 @@ Settings shape:
 ```json
 {
   "piHerdsman": {
-    "spawnPlacement": "tab"
+    "spawnPlacement": "subtree"
   }
 }
 ```
@@ -23,19 +23,26 @@ Supported values:
 
 ```text
 tab
+subtree
 split
 ```
 
 Default:
 
 ```text
-tab
+subtree
 ```
 
-`tab` places future agents in the managed agent-tab workflow.
+When no `spawnPlacement` value is configured, it resolves to `subtree`.
+Unrecognized values remain invalid and resolve to `tab`.
+
+`tab` places future direct agents owned by a lead in one dedicated agents tab.
+
+`subtree` gives each future lead-direct agent its own tab. Descendants always
+split inside their owner's current tab.
 
-`split` places future agents by splitting from the caller's tab/pane placement
-boundary.
+`split` places future lead-direct agents by splitting from the caller's current
+pane. Descendants always split inside their owner's current tab.
 
 This affects future starts, not existing agents.
 
@@ -83,12 +90,12 @@ Project settings are stored in:
 A project placement value is effective only when:
 
 - the project is trusted by Pi; and
-- the project setting is `tab` or `split`.
+- the project setting is `tab`, `subtree`, or `split`.
 
 If no valid trusted project placement is active, the global value is used.
 
 `/agents placement` opens a native selector showing the effective value and
-offering `tab` or `split`. Selecting a value writes to the current effective
+offering `tab`, `subtree`, or `split`. Selecting a value writes to the current effective
 scope and verifies the value after writing; the confirmation reports whether
 that scope is `project` or `global`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "description": "Asynchronous Pi agent orchestration with nested delegation, parallel execution, and supervision in herdr.",
   "license": "Apache-2.0",