pi-herdsman 0.1.0

package/docs/development/documentation.md

@@ -0,0 +1,175 @@
+# Documentation maintenance
+
+[Documentation index](../README.md)
+
+The documentation is deliberately split by responsibility so each feature stays
+on its canonical page while readers can enter through audience-specific paths.
+
+## Ownership rule
+
+Every public concept has one canonical page.
+
+Use the ownership table in [the documentation index](../README.md).
+
+When another page needs the same concept:
+
+- summarize only enough to establish context;
+- link to the canonical page;
+- do not paste the complete table or contract again.
+
+Audience entry pages are navigation, not competing ownership. They may establish
+reading order and show a minimal first-use example, but exhaustive behavior stays
+on the canonical concept, guide, or reference page.
+
+Asynchronous orchestration is owned by [Lifecycle](../concepts/lifecycle.md).
+README, Getting started, and Agent coordination API may repeat the concise user
+or caller consequence, but they must link back to Lifecycle for the exact
+contract.
+
+## Page types
+
+### Audience entry points
+
+The documentation index routes readers first by audience:
+
+- [Getting started](../getting-started.md) is the shortest human UI and
+  configuration path;
+- [Agent coordination API](../agent-api.md) is the model and agent coordination
+  reading path;
+- development pages are maintainer-only.
+
+These pages should link across audiences when useful, but must not grow parallel
+copies of the same API, lifecycle, configuration, or presentation contract.
+
+The physical `concepts`, `guides`, `reference`, and `development` directories
+remain content-type organization. Do not add another documentation hierarchy or
+navigation manifest just to represent audiences.
+
+### Getting started
+
+Shortest human path from prerequisites to useful Pi Herdsman delegation,
+continued lead-session interaction, UI, configuration, and observability.
+
+Do not turn it into a structured API reference.
+
+### Agent coordination API
+
+Reading order and first-use orientation for model and agent-facing coordination.
+
+Link to the exact `worker`, `ask_owner`, lifecycle, delegation, handoff, state,
+and error owners instead of restating their full contracts.
+
+### Concepts
+
+Explain mental models and invariants.
+
+Do not enumerate every request field.
+
+### Guides
+
+Task-oriented procedures and examples.
+
+Link to reference for exhaustive semantics.
+
+### Reference
+
+Exact accepted values, precedence, states, and API rules.
+
+Avoid tutorial narrative.
+
+### Development
+
+Maintainer-only validation, smoke, and documentation-process material.
+
+Do not mix these procedures into normal user setup.
+
+### `SKILL.md`
+
+Optional model-facing reinforcement of the self-contained runtime operational
+contract plus deeper strategy, rationale, examples, and recovery guidance.
+
+It does not own product API schemas or runtime behavior.
+
+## Runtime and skill synchronization
+
+Pi Herdsman has one deliberate instruction duplication.
+
+The runtime controller and managed-worker instructions are the authoritative,
+self-contained operational contract. Root `SKILL.md` intentionally mirrors
+those mandatory operational instructions so loading the skill can reinforce
+them in a long model context.
+
+Therefore:
+
+- every mandatory operational rule must exist at runtime;
+- corresponding operational guidance must remain represented in `SKILL.md`;
+- `SKILL.md` may add strategy, rationale, examples, and deeper explanation;
+- no capability or normal workflow may depend on loading `SKILL.md`;
+- runtime wins if the two surfaces conflict;
+- a change to either mirrored runtime or skill instructions requires checking
+  the other side in the same change.
+
+This is intentional reinforcement, not competing authority.
+
+Do not replace it with runtime skill loading, generated prompt files, a prompt
+registry, or another synchronization subsystem.
+
+## Style
+
+- Plain Markdown.
+- Relative repository links.
+- One H1 per file.
+- Short descriptive headings.
+- Current behavior only.
+- Spell the visible product name `Pi Herdsman`, the package and repository identifier `pi-herdsman`, the local coordination directory `.pi-herdsman`, the settings namespace `piHerdsman`, and the upstream dependency `herdr`.
+- No backlog task numbers in product docs.
+- Keep canonical user and reference pages focused on current behavior.
+- Examples must match current accepted schemas.
+- Never document unshipped backlog behavior as available.
+- Avoid em dashes in product documentation.
+
+## Cross-links
+
+Every page under `docs/` links back to the documentation index.
+
+Audience entry pages may also link directly to each other so a reader can switch
+paths without returning to the index.
+
+Use a `See also` section when the neighboring concept is useful.
+
+Do not create a separate nav manifest or documentation framework unless plain
+Markdown stops meeting a demonstrated need.
+
+## Source verification
+
+When implementation and existing prose disagree:
+
+1. public source/test behavior is authoritative;
+2. current accepted runtime evidence can clarify integration behavior;
+3. stale prose should be deleted, not preserved as an alternative contract.
+
+Particularly verify the runtime implementation for `worker`, `ask_owner`,
+`/workers`, `/chief`, `staff`, states, definition schema/composition, text-file snapshots,
+state projection, error categories, and presentation behavior;
+
+- `package.json` for supported Pi versions and package resources.
+
+## Link integrity
+
+Before handoff, resolve every repository-relative Markdown link. Links must
+target current repository pages and anchors; do not reference deleted pages or
+removed examples.
+
+## Update policy
+
+A feature should normally change:
+
+- its one canonical reference page;
+- a guide or concept only when user workflow or mental model changes;
+- an audience entry page only when its reading path or first-use experience
+  changes;
+- README only when first-use or product capability changes;
+- SKILL only when controller coordination guidance changes.
+
+Update only the surfaces whose current ownership or links change; keep README,
+SKILL, smoke testing, guides, and status docs aligned with their responsibilities.

package/docs/development/smoke-testing.md

@@ -0,0 +1,293 @@
+# Smoke testing
+
+[Documentation index](../README.md)
+
+These are maintainer acceptance checks for behavior that benefits from a real
+Pi/herdr boundary.
+
+Use disposable workers and exact-ID cleanup. Do not disturb unrelated user
+workspaces or agents.
+
+## Preconditions
+
+Verify:
+
+```sh
+node --version
+pi --version
+herdr --version
+herdr integration status
+```
+
+The supported repository contract requires:
+
+- Node `>=22.19.0`
+- Pi `>=0.84.2 <0.86.0`
+- herdr `>=0.8.0`
+- herdr Pi integration version `2` or newer
+
+Run the repository validation gate first.
+
+## Current mailbox contract
+
+For a current managed run, inspect the persisted state, request, ask, and
+result records and verify they use protocol version `3` and contain no lifetime
+field. Control prompts use the `__PI_HERDSMAN_WORKER_V3__:` marker prefix.
+
+## One-shot definition and session continuation
+
+Delegate a small deterministic read-only task to the `scout` definition. Record
+the returned worker, request, session, and pane identities.
+
+Verify:
+
+- one managed worker starts;
+- the task is acknowledged;
+- the worker completes with exactly one result reaching the owner;
+- the terminal result identifies the exact session;
+- cleanup removes the worker, pane, mailbox, and runtime;
+- the exact Pi session remains available.
+
+Use the exact returned session ID or path for a follow-up assignment:
+
+```json
+{
+  "action": "delegate",
+  "session": "<exact session>",
+  "task": "Continue the investigation with one short follow-up."
+}
+```
+
+Verify:
+
+- the same Pi session and session file are used;
+- a new worker generation, run ID, request ID, and pane are created;
+- the saved conversation context is available;
+- the current effective definition configuration is used;
+- exactly one result reaches the owner;
+- cleanup removes the second worker, pane, mailbox, and runtime.
+
+While the continuation assignment is active, submit another
+`delegate.session` request for the same exact session. Verify it fails with
+`worker_busy`, creates no duplicate worker or pane, and leaves the active
+assignment unchanged. After both assignments finish, `worker list` must show
+no completed idle worker.
+
+## Historical session delegation
+
+Use an exact saved session path or full UUID.
+
+Verify:
+
+- saved definition and cwd are respected;
+- session delegation uses the saved cwd;
+- current effective agent override values are used for the new worker
+  generation;
+- the exact session continues.
+
+## Fork
+
+Delegate to a definition with `fork` pointing to an exact saved session.
+
+Verify:
+
+- a new worker/session is created;
+- the fork source is explicit;
+- the current controller session is not implicitly used.
+
+## Inferred delegation
+
+Use a bundled delegating worker definition whose source `tools` list does not explicitly
+contain `worker`, such as the current `implementer`.
+
+Ask it to delegate one bounded scout task.
+
+Verify:
+
+- the real Pi worker can call `worker`;
+- worker result reaches the delegating worker;
+- delegating worker integrates it once;
+- all one-shot workers clean up.
+
+This proves effective-definition inference reaches Pi launch policy rather than
+only metadata.
+
+## Body reference expansion
+
+Create a temporary global definition with a whole-line body reference:
+
+```markdown
+---
+name: worker
+bodyMode: append
+---
+
+@../temporary-policy.md
+```
+
+Use a distinctive instruction in the referenced file.
+
+Verify the worker obeys that instruction through the expanded private prompt.
+
+Afterward remove the temporary definition and referenced file, confirm discovery
+no longer lists the temporary definition, and verify no repository file changed.
+
+## `ask_owner` round trip
+
+Give a worker a task whose correct continuation requires an owner choice.
+
+Verify:
+
+1. worker calls `ask_owner` alone;
+2. owner receives one question;
+3. worker becomes `blocked`;
+4. owner replies with exact `worker reply`;
+5. reply continues the same assignment;
+6. worker produces exactly one final result;
+7. no worker/mailbox leak remains.
+
+## Delegating-worker natural waiting
+
+Ask a delegating worker to delegate required reconnaissance when no useful independent
+local work remains.
+
+Inspect the actual transcript and verify the delegating worker:
+
+- ends its turn normally after the assignment;
+- does not poll `worker list`;
+- does not sleep or use a separate wait mechanism;
+- wakes when the worker result is delivered;
+- integrates the result into one final delegating worker outcome.
+
+## Useful concurrency
+
+Give a delegating worker one delegated task A and independent local task B.
+
+Verify it can work on B while A is active, then ends its turn when no useful
+independent work remains and integrates A after result delivery.
+
+## Lead `/workers` commands
+
+In a lead session with UI:
+
+### `/workers agents`
+
+Verify the native Definitions selector shows:
+
+- bundled, project (when trusted project discovery is enabled), and global
+  definitions in the effective roster;
+- project participation marked `[project]`, with `*` for a global override
+  (`[project] *` means both layers contribute);
+- compact, aligned name/model/thinking columns, including Unicode names;
+- model, thinking, enabled, and details actions for a selected definition;
+- `Use default` for model and thinking;
+- narrow panes remain width-safe.
+
+Structured `worker list` should still retain exact deterministic metadata.
+
+Select a disposable bundled, project, or global definition and change its
+model, thinking, and enabled state. Confirm that project discovery requires a
+trusted project's `piHerdsman.projectAgents: true` setting and that these edits
+write global overrides only, not project files.
+
+Verify unrelated frontmatter and body remain unchanged, `Use default` removes
+only the selected field, fresh definition delegations and session continuations
+use the current effective value, and running workers are not mutated.
+
+### `/workers placement`
+
+Open the native selector, change to the alternate value, verify, then restore
+the original value.
+
+### `/workers stop`
+
+With disposable owned workers, verify the owned tree closes while an unrelated
+herdr agent remains untouched.
+
+## Failure diagnostics
+
+Use a disposable invalid resource/launch configuration only when safe.
+
+Verify startup failure:
+
+- settles within the bounded budget;
+- reports the stage and best available diagnostic;
+- performs exact ownership-safe rollback;
+- does not leave a false successful worker.
+
+## Cleanup checklist
+
+After every smoke:
+
+- `worker list` has no unintended managed workers;
+- temporary global definitions are removed;
+- temporary prompt/body files are removed;
+- disposable herdr resources are closed by exact ID;
+- no repository source file changed unless the smoke explicitly required it.
+
+## Chief supervision live matrix
+
+No live Pi/herdr smoke was run for the current worktree. Every scenario below
+is **NOT RUN**, not a claim of failure or success. The automated tests are not
+substitutes for these checks.
+
+| Scenario                                                                                                                             | Result  |
+| ------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| Normal lead has `worker` and `chief`, not `staff`                                                                                    | NOT RUN |
+| Active Chief has exactly `staff`, not lead controller tools                                                                          | NOT RUN |
+| Persisted Chief resume collision becomes suspended                                                                                   | NOT RUN |
+| Ordinary losing `/chief` collision remains a lead with its tools and offers Focus/Cancel                                             | NOT RUN |
+| Delegating worker and worker retain their current role tools                                                                         | NOT RUN |
+| Activate one Chief with `/chief`                                                                                                     | NOT RUN |
+| Activation refuses a lead with owned or unresolved worker work                                                                       | NOT RUN |
+| Two exact simultaneous Chief claims have one winner                                                                                  | NOT RUN |
+| Stale exact lease recovery                                                                                                           | NOT RUN |
+| Malformed role, lead state, lease, or descriptor fails closed; coordination publication invalidates stale state and disables actions | NOT RUN |
+| Discover leads across multiple workspaces                                                                                            | NOT RUN |
+| Exclude managed workers and the active Chief from leads                                                                              | NOT RUN |
+| Worker exclusion uses the production validated snapshot and stale/ambiguous generations fail closed                                  | NOT RUN |
+| Herdr `agent_status ?? status` lifecycle normalization is reflected                                                                  | NOT RUN |
+| Nested worker aggregation attaches only to the proven lead                                                                           | NOT RUN |
+| A blocked worker does not mark its lead `needs you`                                                                                  | NOT RUN |
+| Duplicate live agents, coordination records, or worker evidence fail closed                                                          | NOT RUN |
+| Target disappearance or replacement between list and action is rejected                                                              | NOT RUN |
+| Inspect a lead and compare bounded peek evidence                                                                                     | NOT RUN |
+| Focus a lead after exact revalidation                                                                                                | NOT RUN |
+| Chief `message` to idle, working, or blocked leads                                                                                   | NOT RUN |
+| Two Chief messages queue and arrive once and in order                                                                                | NOT RUN |
+| A quarantined message does not block a new message to the same lead                                                                  | NOT RUN |
+| Leads retain descendant ownership after a Chief `message`                                                                            | NOT RUN |
+| Lead `chief message` reaches the active Chief                                                                                        | NOT RUN |
+| Lead `chief ask` reaches the active Chief and creates one pending ask                                                                | NOT RUN |
+| Pending ask projects as `needs_you` with bounded public question and exact reply action                                              | NOT RUN |
+| A second lead ask while one is pending is rejected                                                                                   | NOT RUN |
+| Exact Chief `reply` reaches the lead and clears the ask after local acceptance                                                       | NOT RUN |
+| Pending ask remains replyable after chief replacement using the unchanged ask ID/current lease                                       | NOT RUN |
+| Failed ask queue restores the exact previous pending-ask state                                                                       | NOT RUN |
+| Metadata publication failure does not remove communication eligibility                                                               | NOT RUN |
+| Ordinary lead messages leave lead coordination state unchanged                                                                       | NOT RUN |
+| Follow-up delivery while the receiver is streaming, never steering                                                                   | NOT RUN |
+| Receiver restart delivers each queued message once                                                                                   | NOT RUN |
+| Accepted-before-delete crash deduplicates without reinjection                                                                        | NOT RUN |
+| Failed delivery/acceptance retains the queued record                                                                                 | NOT RUN |
+| Transient authorization lookup failure retains the queued message                                                                    | NOT RUN |
+| Stale lease, wrong sender/generation, duplicate identity, and malformed records fail closed                                          | NOT RUN |
+| Lead/Chief messages show bounded direction-aware model-visible sender and target identity                                            | NOT RUN |
+| Queued inbox records are ordered by `createdAt`, then ID                                                                             | NOT RUN |
+| Resume with a free or occupied lease                                                                                                 | NOT RUN |
+| Confirm `/chief leave` without mutating supervised leads                                                                             | NOT RUN |
+| Empty-roster Escape closes the native custom UI                                                                                      | NOT RUN |
+| Empty-roster Ctrl+C closes the native custom UI                                                                                      | NOT RUN |
+| Real terminal arrow sequences navigate the visual order                                                                              | NOT RUN |
+| Space switches overview to peek and Escape/Space returns without nested custom UI                                                    | NOT RUN |
+| Ctrl+C closes from peek                                                                                                              | NOT RUN |
+| Enter focuses the lead and closes the overview                                                                                       | NOT RUN |
+| Background refresh redraws the open overview                                                                                         | NOT RUN |
+| Ambient and overview rendering stay within the supplied width                                                                        | NOT RUN |
+| Named herdr sockets independently support one Chief each                                                                             | NOT RUN |
+
+Named herdr socket independence is also **NOT RUN** because no live Pi/herdr
+runtime was available for this worktree.
+
+The automated test gate is the available evidence for this worktree; see
+[Validation](validation.md).

package/docs/development/validation.md

@@ -0,0 +1,124 @@
+# Development validation
+
+[Documentation index](../README.md)
+
+Repository handoff is not complete until the current validation gates have been
+run or a concrete environment blocker is recorded.
+
+## Required gate
+
+Run:
+
+```sh
+prettier . --write
+npm run check
+git diff --check
+```
+
+When reviewing staged work, also run as appropriate:
+
+```sh
+git diff HEAD --check
+```
+
+## What `npm run check` does
+
+The repository check command validates the development source and tests.
+
+It discovers the extension's TypeScript source and runs, under one bounded
+suite deadline:
+
+1. Node syntax checking for every extension TypeScript file;
+2. an import check for the extension entry point;
+3. the complete Node test set.
+
+The test phase uses:
+
+```text
+--experimental-test-module-mocks
+--experimental-strip-types
+--test
+--test-timeout=10000
+```
+
+## Process containment
+
+Validation phases run in detached POSIX process groups.
+
+On the suite deadline, the runner attempts:
+
+1. `SIGTERM`;
+2. a bounded grace period;
+3. `SIGKILL` when required;
+4. bounded proof that the process group disappeared.
+
+A phase that leaks descendants after normal exit is reported as a failure and
+cleaned through the same group boundary.
+
+Windows is not supported by this process-group validation runner.
+
+## Focused tests
+
+During implementation, use Node's direct test runner through the normal npm
+interface:
+
+```sh
+# all tests
+npm test
+
+# one test file
+npm test -- extension/<area>.test.ts
+
+# one test name within a selected file
+npm test -- --test-name-pattern="<pattern>" extension/<area>.test.ts
+```
+
+For supervision changes, useful focused examples are:
+
+```sh
+npm test -- extension/supervision.test.ts
+npm test -- --test-name-pattern="lease" extension/supervision.test.ts
+npm test -- --test-name-pattern="inspect" extension/controller-api.test.ts
+```
+
+These are command examples, not recorded results. Live Pi/herdr acceptance is
+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:
+
+```sh
+npm run check
+```
+
+`npm run check` remains the bounded full gate, including process-group cleanup
+when a validation phase times out or leaks descendants.
+
+## Dependency availability
+
+A fresh auxiliary worktree may not contain `node_modules`.
+
+Do not silently install dependencies as part of a source-only task unless that
+installation is authorized. If validation uses an existing dependency tree via a
+temporary link, record that fact and remove the link afterward.
+
+## Failed or non-converging check
+
+Record:
+
+- exact command;
+- exit/result classification;
+- process evidence when relevant;
+- cleanup result;
+- whether failure is source-related or environment-related.
+
+Do not claim a passing full check from a partial focused run.
+
+## Live verification
+
+Deterministic tests are the repository gate. Cross-process Pi/herdr behavior may
+also require the live smoke suite.
+
+See [Smoke testing](smoke-testing.md).