@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/knowledge/delegation-dispatch/delegation-modes.md

@@ -0,0 +1,84 @@
+<!--
+  scaffold: delegation-modes.md
+  bucket: delegation-dispatch (Bucket 3)
+  what belongs here: how to choose between the three delegation modes.
+    - Single subagent (default for well-bounded work).
+    - Task group (orchestrator + 2+ workers).
+    - Single-threaded (trivial, or context already burned).
+    - Topic-differs pollution-prevention: off-topic tasks always dispatch.
+-->
+
+# Delegation modes
+
+Three modes. Selection is a choice, not a default — each has a distinct trigger shape.
+
+## Mode 1 — Single subagent
+
+**Default for any task the operator hands the PA.** Well-bounded work that fits one worker.
+
+Pattern: PA hands intent to `dispatch-briefer` → Briefer produces 8-section brief → PA dispatches target worker with the brief → worker returns → PA reviews and reports.
+
+Trigger:
+- Work fits one role.
+- The context to load is reasonable but non-trivial (otherwise Mode 3).
+- The output shape is well-defined.
+
+Standards: 8-section brief via `dispatch-briefer` (or direct-authored if the exceptions apply — see `briefing-contract.md`).
+
+## Mode 2 — Task group
+
+**For read-heavy parallelisable work, work exceeding the PA's context budget, or a multi-role software project.**
+
+Pattern: PA dispatches a Project Lead (or orchestrator role appropriate to the domain) as `general-purpose`. The orchestrator plans the group's shape, dispatches role-workers with per-worker briefs, collects returns, integrates.
+
+Trigger:
+- 2+ workers needed on the same problem.
+- Work spans multiple roles (writer + code + docs + review).
+- Fan-out reading (10+ files to survey, docs to catalogue, etc.) that would blow the main-thread context.
+
+Constraints (from dispatch-envelope findings):
+- Orchestrator MUST be `general-purpose` or `claude` — other types lack the Agent tool.
+- Design for depth-1 or depth-2. Depth-3+ is possible but the observability tax is real.
+- Structured return from orchestrator must enumerate each child's outcome — the parent only sees the orchestrator's final message.
+- MCP shared state (Playwright, OAuth-gated) hazards apply to parallel workers.
+
+Standards: task-group pattern with per-worker briefs; see `task-groups-and-orchestrators.md`.
+
+## Mode 3 — Single-threaded (do it yourself)
+
+**For trivial work, or when context is already burned and dispatching would cost more than finishing.**
+
+Trigger:
+- Genuinely trivial: one-line edit, single file read, status check, quick answer from `pa knowledge`.
+- The context to load is small (already in main thread).
+- Dispatching would cost more than executing.
+- **Topic proximity — the ask sits close enough to what you're already doing that a dispatch would add pollution or confusion without benefit.** Executing inline keeps the thread coherent.
+
+## Topic-differs pollution-prevention
+
+Rev 4 Bucket 3 rule 1 addition. Off-topic tasks always dispatch — different subjects in one thread degrade both.
+
+**How to tell:** if you'd have to switch mental register (from LI comment drafting to code review, from a scheduling question to a voice-guide edit), the topic differs. If the switch is small (from one sub-question of the same brief to another), the topic is the same.
+
+The signal is not size — a trivial off-topic ask still dispatches. A large ask on-topic still executes inline (if context allows). Two axes: size, subject-continuation. Both matter.
+
+## Selection tree (quick reference)
+
+```
+Is the ask trivially small AND on-topic?
+  Yes → Mode 3 (single-threaded)
+  No ↓
+
+Does it need multiple roles OR heavy parallel reads OR context-budget breach?
+  Yes → Mode 2 (task group with orchestrator)
+  No ↓
+
+Default → Mode 1 (single subagent via Briefer)
+```
+
+## Related
+
+- CLAUDE.md.template Bucket 3 rules 1, 4, 5.
+- `briefing-contract.md` — the brief pattern all modes use.
+- `dispatch-envelope.md` — capability and concurrency findings.
+- `task-groups-and-orchestrators.md` — Mode 2 details.

package/dist/engineering-pa-core/knowledge/delegation-dispatch/dispatch-envelope.md

@@ -0,0 +1,238 @@
+# Dispatch Envelope — What Actually Works
+
+## Purpose
+
+This document is the canonical reference for what actually works when the PA dispatches subagents through the Claude Code Agent tool: which subagent types can spawn children, how deep nesting goes, what tools children inherit, what isolation is real vs illusory, and what fails silently or loudly. It exists because the PA's operating model — especially the Project Lead orchestrator pattern — makes architectural bets on these mechanics; those bets have now been verified empirically (2026-07-05) rather than assumed.
+
+The scope is the dispatch *mechanism*, not the briefing content. For brief-writing standards see `@stravica-ai/engineering-pa-core/docs/standards/briefing-contract.md`; this doc is upstream of that — the constraints below shape what a brief can and cannot ask a worker to do.
+
+All findings were gathered by a live diagnostic run on 2026-07-05 in an operator instance codebase. Re-verify if the harness version shifts materially.
+
+---
+
+## Capability Matrix
+
+| subagent_type | Dispatchable? | Has Agent tool? | Can spawn children? | Full MCP inventory? | Notes |
+|---|---|---|---|---|---|
+| `general-purpose` | yes | yes | yes | yes | Default choice for orchestrators. Tool inventory `*`. |
+| `claude` | yes | yes | yes | yes | Equivalent to general-purpose for dispatch purposes. Tool inventory `*`. |
+| `Explore` | yes | **no** | **no** | (moot — no Agent) | Read-only search agent. Excludes Agent, Artifact, ExitPlanMode, Edit, Write, NotebookEdit. |
+| `Plan` | yes | **no** | **no** | (moot — no Agent) | Architect/planner. Same exclusions as Explore. |
+| `claude-code-guide` | yes | **no** | **no** | (moot — no Agent) | Tools limited to Bash, Read, WebFetch, WebSearch. |
+| `statusline-setup` | yes | **no** | **no** | (moot — no Agent) | Tools limited to Read, Edit. |
+
+**Rule:** any orchestrator that must dispatch its own workers MUST be dispatched as `general-purpose` or `claude`. Dispatching an orchestrator role as any other type is a silent architectural bug — the runtime tool inventory won't include Agent, so the nested dispatch will fail the moment the orchestrator tries to spawn a worker.
+
+Source for tool inventories: the harness's own `Available agent types` system reminder, corroborated by nested-dispatch runtime tests.
+
+---
+
+## Depth Findings
+
+Nested dispatch works cleanly to at least **depth 4** with no permission prompts, no runtime errors, and modest per-level overhead.
+
+**Confirmed chain from root to leaf:**
+
+```
+Parent (root)
+  └─ Child (general-purpose)                     ~1.2s spawn overhead
+       └─ Grandchild (general-purpose)           returned "DEPTH-3-ECHO"
+            └─ Great-grandchild (general-purpose) returned "DEPTH-4-ECHO", ~2.7s
+```
+
+Root parent thread observed:
+- Depth-3 grandchild sentence verbatim, echoed through the child's report.
+- Depth-4 great-grandchild sentence verbatim, echoed through the child's report of the grandchild's report.
+
+Per-level cost (zero-tool child, echo only):
+- Depth-2 → depth-3 hop: ~1.2s (`duration_ms: 1184`)
+- Depth-3 → depth-4 hop: ~2.7s (`duration_ms: 2746`)
+- Wrapping orchestrator wall-clock: ~15-30s including its own reasoning
+- The overhead is dominated by the orchestrator's model turn, not the spawn itself
+
+No signs of a depth cap up to depth-4. Depth-5+ was not tested and remains open; assume it works but verify before betting on it.
+
+**Observability trade-off scales linearly with depth.** Each nesting level is a summarisation checkpoint — the root only sees what the level-1 orchestrator reports, which only saw what the level-2 orchestrator reported, and so on. Depth-4 means the root's view of the leaf is triply summarised. For debugging or high-fidelity output the shallowest possible dispatch shape is preferable.
+
+---
+
+## Foreground vs Background
+
+### Foreground (`run_in_background: false`)
+
+- Returns the child's final assistant message as plain text directly in the Agent tool result.
+- Blocks the parent turn until the child completes.
+- Tail of the result includes: `agentId: a...-... (use SendMessage with to: 'a...-...' to continue this agent)` — the agentId is available for resumption even from a foreground call.
+- No streaming, no partial progress visible during execution.
+- **Use for:** short critical-path work where the parent literally cannot proceed without the result (e.g. a design decision, a lookup that gates the next dispatch).
+
+### Background (`run_in_background: true` — the default)
+
+- Returns immediately with a metadata blob containing `agentId`, an `output_file` symlink pointing at the child's JSONL transcript, and a warning explicitly forbidding reading it (context-overflow risk).
+- Completion arrives asynchronously as a `<task-notification>` message with `<status>completed</status>` and a `<result>...</result>` block containing the child's final message.
+- Notification includes: `A task-notification fires each time this agent stops with no live background children of its own. The user can send it another message and resume it, so the same task-id may notify more than once.`
+- Multiple background dispatches from a single message run **in parallel** — confirmed with 10 concurrent dispatches completing within a tight 3-second window.
+- Notifications from many parallel completions arrive in bursts of 2-4 rather than one-per-line.
+- **Use for:** anything that isn't gating the very next turn — which is most things.
+
+### SendMessage / resume semantics
+
+- SendMessage to an existing agentId resumes it in the background with full transcript context. The response says `resumed from transcript in the background with your message`.
+- The resumed agent is the **same** agent — same agentId, same conversation history, notification fires again on next stop.
+- Recipient MUST be an agentId (format `a...`) or a live teammate name. Referring to a peer by `subagent_type` fails — e.g. `SendMessage({to: "general-purpose"})` returns `"No agent named 'general-purpose' is reachable"`. There is no group addressing by role.
+- SendMessage supersedes dispatching a fresh Agent when continuing prior work is cheaper than briefing a new one. Use it to hand a follow-up task to a child that already has the context loaded.
+- `to: "main"` is available from a background subagent to talk back to the parent — but the parent still receives it as a normal message, not a special channel.
+
+### Return-shape parity across foreground and background
+
+| Aspect | Foreground | Background |
+|---|---|---|
+| What returns | child's final assistant message text | metadata + async notification with final message |
+| agentId available | yes (in tail) | yes (up front) |
+| Intermediate tool events visible | no | no |
+| Transcript file on disk | yes | yes (as symlink, do not read) |
+| Resumable via SendMessage | yes | yes |
+
+The transcript is always on disk as JSONL under `/private/tmp/claude-<uid>/<session>/tasks/{agentId}.output` (symlink) → `~/.claude/projects/<session>/subagents/agent-{agentId}.jsonl`. The harness warns not to read these directly — they include full tool traces and will blow the parent's context. If per-child transcript inspection matters, do it out-of-band after the session ends, not inline.
+
+---
+
+## MCP Tool Availability
+
+**Finding: MCP tools do inherit into subagents.** The parent's full deferred-tool inventory is visible in every child spawned as `general-purpose` or `claude`. Confirmed by direct load-and-call diagnostics from a child agent.
+
+Verified in a subagent's tool inventory:
+- `WebFetch` — loads and returns real fetched content
+- `WebSearch` — available
+- `mcp__rcf-tools__rcf_status` — loads and returns valid JSON response
+- `mcp__playwright__browser_navigate` — loads and successfully navigates
+- `mcp__claude_ai_Gmail__authenticate` — listed as available
+- `mcp__claude_ai_Atlassian__authenticate` — listed as available
+- `SendMessage`, `Monitor` — listed as available
+- `ToolSearch` itself — available (subagents must use it to load deferred schemas, same as the parent)
+
+**Important shared-state caveat — Playwright browser session is shared with the parent.** When a subagent called `browser_navigate`, the response showed a pre-existing second tab open from a prior parent-thread run. The Playwright MCP browser context is **not** per-subagent; it's session-scoped. Implication:
+
+- If the parent has a Playwright session in flight and dispatches a child that also uses Playwright, they share the same browser instance and can step on each other's tabs.
+- OAuth-gated MCP tools (Google Drive, Gmail, Calendar, Atlassian, Canva) also share the parent's auth state — a child does not need to re-authenticate.
+- For MCP tools like Playwright where state matters, only one agent at a time should be driving the browser. Serialise.
+
+The subagent-type restrictions apply here too: `Explore`, `Plan`, `claude-code-guide`, and `statusline-setup` have restricted tool inventories that exclude MCP tools by default. Only `general-purpose` and `claude` inherit the full inventory.
+
+---
+
+## Concurrency and Limits
+
+- **Documented cap:** none. The Agent tool description mentions parallel dispatch (`When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently`) but specifies no numeric ceiling, queue, or throttle.
+- **Observed cap:** none up to N=10. Ten concurrent background subagents launched from a single message all started immediately, ran in parallel, and completed within a tight ~3-second spread. No queuing, no refusal, no throttling.
+- **Untested:** N > 10. If the harness has a hard ceiling it's above 10; do not rely on unbounded parallelism without re-testing.
+- **Notification batching:** completion notifications arrive in bursts of 2-4 messages when many finish close together. This is a UX detail — it doesn't change semantics, and the ordering per-agent is preserved.
+
+**Practical guidance:** dispatch as many parallel workers as make sense for the problem. Don't artificially cap at 3 or 5 — the harness accepts real parallelism. But note that each concurrent dispatch is a real token cost against the account, so parallelism is expensive even when it's fast.
+
+---
+
+## Worktree Isolation
+
+Passing `isolation: "worktree"` to the Agent tool cuts a git worktree for the child. What that actually isolates:
+
+**Isolated (git-only sandbox):**
+- Working tree — each worktree gets its own filesystem view of the repo at `.claude/worktrees/agent-{agentId}/` under the parent repo root.
+- Git branch — auto-named `worktree-agent-{agentId}`, cut from the parent's current HEAD.
+- Repo-relative operations — file edits, staged changes, `git status` are per-worktree.
+- The parent's working tree is untouched by child edits inside the worktree.
+
+**NOT isolated (shared with parent and other agents):**
+- `/tmp` — writes visible to parent and to sibling worktree-isolated agents.
+- `$HOME` — shared user config.
+- Network, credentials, MCP session state (see Playwright caveat above).
+- Any absolute path outside the repo root.
+- Environment variables (unless explicitly overridden).
+
+**Cleanup:** manual when the child made changes. The Agent tool description states worktrees are auto-cleaned only when the agent made no changes. Both dirty test worktrees persisted at `.claude/worktrees/agent-{agentId}/` after completion. Prior sessions accumulate stale worktrees under `{OPERATOR_REPO_ROOT}/.claude/worktrees/` — worth a periodic `git worktree prune` + directory sweep.
+
+**Concurrency safety:** two parallel worktree-isolated agents do not conflict on repo files — each has its own branch and its own working tree. But they DO share `/tmp` and any other absolute paths outside the repo, so treat worktree isolation as "git-safe parallel edits" not "sandboxed process".
+
+---
+
+## Long-Running Health
+
+**Signals available to the parent while a child is running:**
+
+- Presence of the child's task output file at `/private/tmp/claude-<uid>/<session>/tasks/{agentId}.output` (symlink to the JSONL transcript). The symlink exists as soon as the child starts.
+- Absence of a task-notification for that agentId means "still running (or crashed silently — rare)".
+- No documented API for peeking at partial progress, and the harness explicitly warns not to read the transcript file directly (context overflow risk).
+
+**Detecting a stalled vs slow child:**
+
+- There is no built-in health signal beyond notification-vs-silence.
+- A child that runs quietly for a long time and never notifies is indistinguishable from a slow child until it finishes.
+- Mitigation for genuinely long dispatches: brief the child to send periodic `SendMessage` updates to `main` at natural checkpoints. This makes progress observable without reading the transcript.
+- For jobs whose duration is genuinely unknown (multi-hour scrapes, model runs), the harness is not the right container — kick them off via `schedule` (cloud routine) or a scheduled task instead.
+
+**Concurrency test data point:** a background child running for ~78s wall-clock produced zero partial signals. Only the final `<task-notification>` fired at completion. Assume the same for anything below the notification threshold.
+
+---
+
+## Brief-Writing Implications
+
+Rules derived from the findings above. Fold into `briefing-contract.md` when it's next updated.
+
+**DO:**
+
+1. **Dispatch orchestrators as `general-purpose` or `claude`.** Any Project Lead, task-group orchestrator, or worker that will itself spawn children MUST be one of these two types. State the subagent_type constraint explicitly in the brief so future refactors don't accidentally downgrade the type.
+2. **Prefer background dispatch by default.** Foreground blocks the parent turn and is only justified when the result gates the very next action. All fan-out and parallelisable work goes background.
+3. **Design for depth-1 or depth-2 orchestration whenever possible.** The observability tax on each nesting level (final-message-only rollup) makes depth-3+ progressively harder to reason about. Use nested orchestrators only when the problem genuinely needs a multi-role team.
+4. **Require structured returns from orchestrators.** Since the parent only sees the orchestrator's final message, the brief must specify the exact return shape covering every child's outcome (name/role, agentId, status, key artefacts). Otherwise child work becomes opaque.
+5. **Brief periodic SendMessage checkpoints for long-running children.** For any child expected to run >5 minutes, the brief should require it to `SendMessage` progress to `main` at natural checkpoints. Otherwise a stalled child is indistinguishable from a slow child.
+6. **Explicitly name MCP shared-state hazards.** If a child will use Playwright, Gmail, or any MCP with session state, the brief must acknowledge the shared browser/OAuth session and instruct the child to serialise with any other agent using the same tool.
+7. **Address SendMessage recipients by agentId, not by type.** Any brief that instructs a child to message a peer must include the peer's agentId. Referring to peers by role or subagent_type will fail at runtime.
+
+**DON'T:**
+
+1. **Don't dispatch a Project Lead (or any orchestrator) as `Plan`, `Explore`, `claude-code-guide`, or `statusline-setup`.** Those types lack the Agent tool. The nested dispatch will fail — usually at the worst possible moment.
+2. **Don't run two Playwright agents in parallel.** Browser session is shared. Serialise, or accept that they will clobber each other's tabs.
+3. **Don't rely on worktree isolation as a security or sandbox boundary.** It isolates the git tree only. `/tmp`, `$HOME`, network, and everything absolute-path outside the repo are wide open.
+4. **Don't put critical writes to shared paths (`/tmp`, `~/.claude/`) inside parallel workers.** They'll race. Use per-agent output directories or namespace files by agentId.
+5. **Don't assume worktrees auto-clean.** If a worker makes changes and doesn't merge or discard them, the worktree persists. Include a cleanup instruction or accept the accumulation.
+6. **Don't ask children to read each other's transcript files.** The `output_file` symlinks exist but reading them will overflow whoever tries. Route inter-worker communication through SendMessage or through the shared context store (task-group standard).
+7. **Don't ship a brief that asks a child to "let me know when you're done at each step".** Streaming intermediate events isn't available. The child can `SendMessage("main", ...)` for progress, but that's model-driven and needs to be requested explicitly.
+
+---
+
+## Failure Modes
+
+Catalogue of dispatches that will fail. Most of these fail silently or late — the point of listing them here is to catch them at brief-write time.
+
+| Failure | Symptom | Root cause |
+|---|---|---|
+| Dispatch a `Plan`/`Explore`/`claude-code-guide`/`statusline-setup` orchestrator that needs to spawn workers | Orchestrator tries to call Agent, tool not in inventory, dispatch fails at runtime | Restricted tool inventories exclude Agent |
+| SendMessage to a peer by subagent_type instead of agentId | Response: `No agent named 'general-purpose' is reachable` | No group addressing by role — must use agentId or teammate name |
+| Two parallel Playwright agents both driving `browser_navigate` | Tabs interleave, screenshots capture the wrong page | Playwright MCP browser session is parent-scoped, not per-subagent |
+| Parallel workers writing to the same `/tmp/foo.txt` or the same file inside a shared parent dir | Last-write-wins race | `/tmp` and any absolute path outside the worktree is shared |
+| Worker reads its own `output_file` (JSONL transcript) to check progress | Context overflow | Transcript is full tool-trace JSONL, forbidden by the tool warning |
+| Parent expects progress signals from a 30-minute background child | Silence until completion | No streaming; only final-message notification |
+| Depth-N orchestrator returns "success" but the leaf actually errored | Root gets a rolled-up "done" without the failure detail | Each nesting level is a summarisation checkpoint; leaves are opaque unless the orchestrator brief requires child-outcome enumeration |
+| Worktree-isolated worker changes `$HOME/.claude/settings.local.json` | Change persists to the parent's config | Only the git tree is isolated |
+| Dispatch depends on unloaded MCP tool without ToolSearch first | `InputValidationError` | Deferred tools need schema loaded before invocation, same rule as the parent |
+| OAuth-gated MCP tool called before auth is completed | Auth flow error | Auth state is inherited from parent — if parent hasn't authenticated, child can't either |
+
+---
+
+## Related
+
+- **Project Lead role definition** — operator-side; documents the `subagent_type: "general-purpose"` dispatch constraint that this doc justifies. <!-- OPERATOR: this reference is operator-side; operators substitute their equivalent role path -->
+- **Bucket 3 of the CLAUDE.md always-on rules** — `packages/scaffold/templates/CLAUDE.md.template`. Rule 6 ("Any multi-role project: dispatch a Project Lead") depends on the nested-dispatch capability confirmed here.
+- **Briefing contract standard** — `packages/core/docs/standards/briefing-contract.md`. The Do/Don't rules above should be folded into the briefing template so orchestrator briefs pick up the constraints automatically.
+- **Task group standard** — a task-group standard in operator-side knowledge governs the group shape a Project Lead assembles; the isolation and concurrency findings here govern what a group can safely do in parallel. <!-- OPERATOR: this reference is operator-side; operators substitute their equivalent standard path -->
+- **Agent terminology** — operator-side; "orchestrator", "worker", "task group", and "run folder" as used in this doc. <!-- OPERATOR: this reference is operator-side -->
+
+---
+
+## Verification metadata
+
+- **Investigated:** 2026-07-05
+- **Harness:** Claude Code, Opus 4.7, an operator-instance project scope
+- **Method:** live diagnostic dispatches from the main thread; each test topic recorded WHAT was tried, WHAT happened, and the implication. Full details preserved in the parent's transcript for the session.
+- **Confidence:** high for all findings up to depth-4, N=10 concurrent, and the six subagent-type inventories. Untested and open: depth-5+, N>10, remote isolation mode, long-lived (>1 hour) child health signals.
+- **Re-verify when:** Claude Code harness version changes materially, subagent-type registry gains new types, or MCP inventory grows (esp. new session-stateful tools).

package/dist/engineering-pa-core/knowledge/delegation-dispatch/task-groups-and-orchestrators.md

@@ -0,0 +1,62 @@
+<!--
+  scaffold: task-groups-and-orchestrators.md
+  bucket: delegation-dispatch (Bucket 3)
+  what belongs here: the task-group pattern and orchestrator role.
+    - Orchestrator + 2+ workers pattern.
+    - Depth-2 production posture (mechanism supports deeper).
+    - Project Lead as the canonical orchestrator role for multi-role projects.
+    - Per-worker brief; orchestrator return structure.
+-->
+
+# Task groups and orchestrators
+
+## Pattern
+
+**Orchestrator + 2+ workers**, all dispatched from the same PA session. The orchestrator plans, dispatches, collects, integrates. The workers execute in isolation.
+
+- **Orchestrator role.** For multi-role software projects: Project Lead. For domain-specific groups: the domain's orchestrator role. Both dispatch as `general-purpose` (see dispatch-envelope § Capability Matrix).
+- **Workers.** Role-specific — writer, code implementer, librarian, tool-developer, etc. Each gets an 8-section brief from the orchestrator.
+- **Orchestration accountability.** The orchestrator is responsible for the group's return shape. The PA reads only the orchestrator's final message.
+
+## Depth-2 production posture
+
+The dispatch mechanism supports deeper (verified to depth-4). Production posture is **depth-2**: PA → orchestrator → workers. Workers do NOT fan out further.
+
+**Why depth-2:**
+
+- Observability tax scales linearly with depth. At depth-2 the PA has direct visibility into orchestrator returns; at depth-3 the parent's view of the leaf is doubly summarised.
+- Coordination overhead scales worse. Multi-tier orchestrators mean recovering from a mid-tier failure requires re-briefing at every level.
+- Debugging cost is real. Deep chains mean tracing a failure back to root cause traverses multiple opaque summarisation checkpoints.
+
+If a genuinely nested problem shape appears (workers each need their own team), lift the sub-team to a sibling orchestrator at depth-2 rather than nesting.
+
+## Per-worker brief
+
+Every worker in the group gets its own 8-section brief authored by the orchestrator (or by `dispatch-briefer` on the orchestrator's behalf). Briefs share Context and Trace fields where the workers are all part of the same integration, but Goal / Boundaries / Done-when / Escalation-rule are per-worker.
+
+## Orchestrator return structure
+
+Because the PA only sees the orchestrator's final message, the orchestrator's return MUST enumerate each worker's outcome. Minimum shape:
+
+```
+### <group-name> — orchestrator return
+
+**Group status:** success | partial | escalation
+
+**Workers:**
+| Name/role | agentId | Status | Key artefacts |
+|---|---|---|---|
+| writer | a-… | success | PR #123, draft-1.md |
+| librarian | a-… | success | knowledge-graph-updated |
+
+**Integration outcome:** <one-paragraph summary of the integrated result>
+
+**Escalations (if any):** …
+```
+
+## Related
+
+- CLAUDE.md.template Bucket 3 rules 5, 6.
+- `dispatch-envelope.md` — depth findings, subagent-type constraint, MCP shared state hazards.
+- `delegation-modes.md` — task group as Mode 2.
+- Operator-side project-lead role definition — the canonical multi-role orchestrator. <!-- OPERATOR: this reference is operator-side; operators substitute their equivalent role path -->

package/dist/engineering-pa-core/knowledge/delegation-dispatch/team-improvement-loop.md

@@ -0,0 +1,48 @@
+<!--
+  scaffold: team-improvement-loop.md
+  bucket: delegation-dispatch (Bucket 3)
+  what belongs here: evaluate process AND result on every dispatch return.
+    - Worker asked a question you should have anticipated → gap in your brief or Baz-context.
+    - Worker misinterpreted → your Trace was thin.
+    - Worker lacked capability → update the role spec.
+    - Reusable pattern surfaced → capture in the role definition.
+    - Decision made under envelope that was wrong → move category to higher zone.
+-->
+
+# Team improvement loop
+
+Every dispatch return is a test of the operating system, not just a delivery of work. Evaluate BOTH the process AND the result.
+
+## What to evaluate
+
+When a dispatch returns, ask:
+
+- **Worker asked a question you should have anticipated?** Gap in your briefing or your knowledge of the operator. Fix the source: tighten the brief pattern, extend the operator profile, add a Trace note.
+- **Worker misinterpreted the brief?** Your Trace was thin or your Context assumed too much. Update the brief pattern; if the gap is structural, update the role definition.
+- **Worker lacked a capability the role should include?** Update the role spec. Add tools. Adjust domain access. Reshape the role's activation reads.
+- **Worker performed well in a way that reveals a reusable pattern?** Capture in the role definition so it persists.
+- **Decision made under your envelope that turned out to be wrong?** Move the relevant category to a higher zone. Right under your envelope and surfaced needlessly? Move it down.
+
+## Where the outputs land
+
+- **Role definitions** — under `operator/extensions/roles/<role>/definition.md` (operator-side) or `@stravica-ai/engineering-pa-core/roles/<role>/definition.md` (core roles, upstream PR).
+- **Brief patterns** — `briefing-contract.md` (this bucket) or `packages/core/docs/standards/briefing-contract.md`.
+- **Autonomy envelope** — `agents/<paName>/autonomy-envelope.md` via `pa autonomy set`.
+- **Operator profile / preferences** — via staging observations, promoted by the Librarian on distillation.
+- **Roster** — operator-side role/agent roster if you maintain one.
+
+## Cadence
+
+This is continuous, not periodic. Every dispatch return is an evaluation opportunity. Don't defer to a "team retrospective" that never happens.
+
+## What NOT to do
+
+- Don't blame the worker for a brief that was ambiguous. The brief is your responsibility.
+- Don't update the role definition on the basis of one anomalous run. Two or three data points before you change the spec.
+- Don't let the improvement work accumulate. If you notice a pattern gap and don't fix it, the next dispatch will hit it again.
+
+## Related
+
+- CLAUDE.md.template Bucket 3 rule 11.
+- `briefing-contract.md` — the brief pattern is a first-order target for improvement.
+- `packages/core/roles/*/definition.md` — role definitions are the persistent home for improvement outputs.

package/dist/engineering-pa-core/knowledge/delegation-dispatch/tool-development-policy.md

@@ -0,0 +1,48 @@
+<!--
+  scaffold: tool-development-policy.md
+  bucket: delegation-dispatch (Bucket 3)
+  what belongs here: the tool-development-through-tool-developer policy.
+    - Node.js only. Cross-platform breakage rationale.
+    - Every CLI or script — dispatch tool-developer with a briefing contract.
+    - Never build tools inline.
+-->
+
+# Tool development policy
+
+## Rule
+
+**All tool development goes through the `tool-developer` role.** Not the PA directly, not any other role — the tool-developer.
+
+## Language
+
+**Node.js only.** No shell scripts, no PowerShell, no Python (for the PA's own tool estate — this is the operating platform, not the operator's product).
+
+**Cross-platform breakage rationale:** the platform ships to macOS, Linux, and Windows. A `.sh` tool silently breaks on Windows; a `.ps1` tool silently breaks on Unix. Node runs the same on all three. Node stdlib (`node:child_process`, `node:fs`, `node:dns`, `node:http`, `node:path`) covers most of what a shell script would do.
+
+## When to dispatch
+
+- Any new CLI, script, or integration — dispatch tool-developer.
+- Any change to an existing tool — dispatch tool-developer.
+- Any diagnostic script that will get re-used — dispatch tool-developer to make it a real tool.
+
+## Brief shape for tool-development dispatches
+
+The tool-developer's brief follows the 8-section contract with two additions in the Boundaries section:
+
+- Node-only constraint stated explicitly (as a reminder that a briefer might otherwise let a `.sh` slip past).
+- Cross-platform runtime target stated: macOS + Linux + Windows.
+
+Full pattern in the tool-developer role definition.
+
+## Existing tool surface
+
+The platform ships a set of bins: `pa`, `desk`, `secrets`, `sync`, `scheduler`, `smoke`, `distill`, `memory-sync`, `pa-init`, `slice`, `launch`, `migrate-inspect`. The operator layers additional tools under `operator/extensions/tools/`.
+
+Always check the current surface before proposing a new tool — `pa --help`, `desk --help`, `ls operator/extensions/tools/`. Proactive-tool-proposal (Bucket 7 rule 9) applies here too: if a task pattern repeats and there's no tool, propose one.
+
+## Related
+
+- CLAUDE.md.template Bucket 3 rule 10.
+- `packages/core/roles/tool-developer/definition.md` — the tool-developer role.
+- `packages/core/docs/standards/tooling.md` — the tooling standard the role follows.
+- CLAUDE.md.template Bucket 7 rule 9 — proactive-tool-proposal.

package/dist/engineering-pa-core/knowledge/engineering-discipline/README.md

@@ -0,0 +1,33 @@
+# engineering-discipline — bucket knowledge scaffold
+
+**Bucket:** 5 of 7. Referenced from CLAUDE.md.template Bucket 5.
+
+## What this bucket carries
+
+Ship correct, safe, reversible changes. Never destroy the operator's work. Role ladder for matching engineering role to work shape, verify discipline, git safety, worktree isolation semantics, blast-radius awareness.
+
+## Scope — core vs operator overlay
+
+**In core.** Universal engineering discipline: the base role LADDER (tool-developer → web-developer → product-engineer → rcf-engineer), verify-runtime-behaviour discipline, blast-radius awareness, git safety protocol, worktree-isolation semantics (double-faced rule: parallel-in-own-estate, sequential-writes-in-project-repos), root-cause investigation, secret-scanning heuristics.
+
+**In operator overlay** (`operator/knowledge/engineering-discipline/`). The specific role LIST (`site-cloner`, `seo-analyser`, `linkedin-writer`, etc.) beyond the base ladder. Operator-specific engineering conventions (per-project git safety rules, CI-integration patterns, downstream-repo policies).
+
+## Canonical entries in this scaffold
+
+| File | Purpose |
+|---|---|
+| `role-ladder.md` | The base role LADDER as the CORE pattern; selection heuristics for when to reach for which tier. |
+| `verify-runtime-behaviour.md` | Tests verify code correctness, not feature correctness. Verify by driving the actual flow. |
+| `blast-radius-and-safety.md` | Local reversible = free; shared/hard-to-reverse = confirm. Git safety protocol. |
+| `worktree-isolation.md` | Double-faced rule — parallel in the PA's own estate, sequential writes in engineering project repos. |
+| `investigate-root-causes.md` | Root cause over patch; don't bypass safety checks as a shortcut. |
+
+## How operators adopt this
+
+Copy the shape into `operator/knowledge/engineering-discipline/`. Populate the specific specialised-role LIST and per-project conventions in the marked hooks.
+
+## Related
+
+- CLAUDE.md.template Bucket 5 — the rule list that references this deeper doc.
+- `packages/core/docs/standards/tooling.md` — the tooling standard.
+- `dispatch-envelope.md` — dispatch mechanics; worktree isolation semantics from the dispatch side.

package/dist/engineering-pa-core/knowledge/engineering-discipline/blast-radius-and-safety.md

@@ -0,0 +1,50 @@
+<!--
+  scaffold: blast-radius-and-safety.md
+  bucket: engineering-discipline (Bucket 5)
+  what belongs here: blast-radius awareness + git safety.
+    - Local reversible = free; shared / hard-to-reverse / visible = confirm.
+    - Never destructive git ops without ask.
+    - Prefer new commits over amending.
+    - Never skip hooks or bypass signing.
+    - Investigate unexpected state before overwriting.
+    - Review what's committed — never commit secrets.
+-->
+
+# Blast radius and safety
+
+## Blast-radius awareness
+
+Every action has a blast radius. Match confirmation to blast radius.
+
+- **Local reversible.** Editing a scratch file, running a query, reading. Free — no confirmation.
+- **Shared or persistent.** Writing to the operator's canonical files, committing, pushing, publishing. Confirmation warranted for anything the operator hasn't already scoped.
+- **Hard to reverse.** Force-push, delete-branch, drop-table, delete-cloud-resource. Confirmation required — and even then, the operator must be the one to fire the destructive action, not you.
+- **Visible to others.** Publishing to LinkedIn, filing an issue on someone else's repo, sending an email. Confirmation required — external audiences don't unwind.
+
+Match action scope to what was requested. If the operator asked for a change to file X, don't also change file Y "while I'm here" without checking.
+
+## Git safety protocol
+
+**Prefer new commits over amending.** Amend is a git operation on the PREVIOUS commit; a pre-commit hook failure means the current commit didn't happen, so amend would rewrite the wrong commit. New commit is safer.
+
+**Never destructive ops without an explicit operator ask.** The banned list:
+- `git reset --hard`
+- `git push --force` (and `--force-with-lease` — treat the same)
+- `git checkout .`
+- `git restore .`
+- `git clean -f`
+- `git branch -D`
+
+If a destructive op looks needed, propose it and wait for confirmation.
+
+**Never skip hooks or bypass signing.** `--no-verify`, `--no-gpg-sign`, `-c commit.gpgsign=false` — banned unless the operator has explicitly asked for the skip. If a hook fails, fix the underlying issue.
+
+**Investigate unexpected state before overwriting.** Unfamiliar files, branches, or config may represent the operator's in-progress work. `git status` before any command that could discard uncommitted changes.
+
+**Review what you're committing.** Never commit files that likely contain secrets — `.env`, credentials.json, private keys, `.aws/credentials`, `.ssh/*`. Suspicious filenames get contents-checked before push. Prefer `git add <specific-file>` over `git add -A` or `git add .` — the wildcard forms accidentally stage secrets and large binaries.
+
+## Related
+
+- CLAUDE.md.template Bucket 5 rules 3, 5, 6, 8, 9.
+- `investigate-root-causes.md` — investigate before overwriting.
+- `worktree-isolation.md` — how worktrees shift the safety calculus.

package/dist/engineering-pa-core/knowledge/engineering-discipline/investigate-root-causes.md

@@ -0,0 +1,48 @@
+<!--
+  scaffold: investigate-root-causes.md
+  bucket: engineering-discipline (Bucket 5)
+  what belongs here: investigate root causes; don't bypass safety checks.
+    - When a hook fails, understand why before proposing a workaround.
+    - When tests fail, understand why before adding an ignore.
+    - When a lint fails, understand why before disabling.
+    - Patch vs fix — the patch shortcut is what makes a codebase decay.
+-->
+
+# Investigate root causes
+
+## The rule
+
+When something fails — a hook, a test, a lint, a deploy — investigate the root cause BEFORE proposing a bypass. The bypass is often what someone in the future has to unwind at 10x the cost.
+
+## Common shortcut failures
+
+- **`--no-verify` to bypass a pre-commit hook.** The hook exists for a reason. Fix the underlying issue.
+- **`skip: true` on a failing test.** The test caught a real issue. Fix the code the test is asserting about.
+- **`// eslint-disable-next-line` on every failing lint.** The rule was enabled for a reason. Either follow it or (with reasoning) disable it project-wide.
+- **`try { ... } catch { /* ignore */ }`.** The error was raised for a reason. Handle it or let it propagate.
+- **Bumping a dep to work around a bug.** The bug was in your code, not the dep — the bump masked it.
+
+## When bypass is warranted
+
+- **The check itself is wrong.** Rare, but real. If the pre-commit hook has a bug and the fix will land in the next commit, bypassing THIS commit is defensible — but propose the bypass to the operator, don't do it silently.
+- **Time-sensitive fix under partial constraint.** A prod outage where a hook fires on unrelated files — bypass the hook, land the fix, come back and address the hook's over-broad match.
+
+In both cases the bypass is temporary and the underlying issue is captured. If the bypass becomes durable, the check is de facto disabled and should be either removed or fixed.
+
+## Investigation shape
+
+- Reproduce the failure locally.
+- Read the check's actual output. Not the summary — the actual output.
+- Read the code the check is asserting about.
+- Formulate a hypothesis about what's wrong.
+- Confirm the hypothesis before fixing.
+
+## Don't accept "flaky test" as an explanation
+
+Tests are either deterministic or they're broken. "Flaky" means "there's a real race / timing / state-leakage issue and no-one has time to fix it." The right response is to fix the flakiness (isolate the state, fix the race, add the retry-with-known-fix pattern), not to add `retry: 3` and hope.
+
+## Related
+
+- CLAUDE.md.template Bucket 5 rule 4.
+- `blast-radius-and-safety.md` — the safety context this rule lives in.
+- `verify-runtime-behaviour.md` — verification is how you confirm the root cause was actually fixed.