zob-harness 0.1.0

package/.pi/skills/zob-goal-todo-tree/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: zob-goal-todo-tree
+description: Use when planning, using, reviewing, or implementing ZOB /goal-linked TODOs, subtodos, TODO HUD progress, delegated TODO claims, or hierarchical subagent work graphs.
+---
+# ZOB Goal TODO Tree Skill
+
+## When to use
+
+Use this skill when a task involves any of:
+
+- `/goal todo`, `/todo`, or goal progress tracking;
+- TODO/subtodo planning under an active runtime goal;
+- showing progress in the HUD;
+- linking TODOs to `delegate_task`, `delegate_agent`, `child_goal`, orchestration, chains, or factories;
+- accepting/rejecting subagent completion claims;
+- reviewing whether a goal can move to `ready_for_oracle` or `complete`;
+- designing X-depth TODO/delegation systems.
+
+Canonical design/runtime doc:
+
+- `docs/ZOB_GOAL_TODO_TREE_PLAN.md`
+
+Runtime support now includes `/goal todo ...`, `/todo`, `/todos overlay`, goal TODO tools, delegated claim acceptance/rejection, oracle claim validation, strict PASS/no_ship=false auto-accept, artifact imports, HUD/prompt summaries, and completion blockers.
+
+## Core model
+
+A ZOB goal TODO is not a standalone checklist. It is a parent-owned work graph attached to a `RuntimeGoal.goalId`.
+
+```text
+RuntimeGoal = objective + loop + oracle + final gate
+GoalTodoGraph = work breakdown + progress + evidence
+DelegationGraph = subagent execution/claims linked to TODO nodes
+EvidenceGraph = validation commands, reports, checkpoints, sentinels, hashes
+```
+
+## Non-negotiable invariants
+
+- Do not create floating TODOs without an active runtime goal.
+- Do not mark root goal complete from TODO status alone.
+- Do not call `update_goal complete` before `propose_goal_completion` and oracle `PASS/no_ship=false`.
+- Do not propose root completion while required TODOs are open, blocked, delegated, or awaiting user/oracle review.
+- Use `resolve_goal_todo` as the primary API for TODO transitions (`auto`, `complete`, `accept_claim`, `reject_claim`, `block`, `skip`, `reopen`).
+- Do not use `update_goal_todo` to mark TODOs `done` or `skipped`; it is metadata-only.
+- Do not let a subagent directly mutate canonical TODO state.
+- Refresh active TODO refs with `get_goal_todos` before TODO-linked delegation.
+- Do not pass stale or invented `child_goal.todo_id` values. Prefer canonical active IDs from `get_goal_todos`; if you only know the visible tree path, use `child_goal.todo_path` rather than fabricating shorthand IDs.
+- Safe auto-open/delegation is allowed for runtime-delegatable TODOs (`planned`, `ready`, `in_progress`, `needs_review`) when no active child/run owns the leaf and scope/ownership are clear; do not auto-open `needs_user`, `needs_oracle`, `blocked`, `claim_returned`, or active delegated/review states.
+- Recover delegated/recovery leaves only when no active child/run owns the TODO and stale metadata can be safely cleared; otherwise block/review and do not redelegate the same leaf.
+- No same-leaf parallel write workers. If multiple agents or parallel work are needed, split into subtodos first and dispatch one owner per writable leaf.
+- Parallel owner pools use read-across/write-by-owner: sibling workers may read cited outputs/context and Goal Room summaries, but only the leaf owner edits its owned paths, and planned write paths must be within owned paths. Read-across never grants write access; overlap with write paths requires a hash-only justification. Workspace claims are metadata-only; an owner's own active listed write claim can cover write intent while other overlaps remain conflicts. Cross-owner changes require a parent-visible owner request and owner/parent decision, with requested paths covered by the named owner assignment when a plan exists; children without harness extensions may emit a hash/body-free `OWNER_CHANGE_REQUEST.v1` final-output block for parent-side extraction only.
+- Goal Room is canonical for pool coordination, owner requests/decisions, blockers, evidence refs, and oracle-visible history. ZPeer is optional transient live clarification and must be summarized to Goal Room when it changes decisions.
+- A subagent returns a claim; the parent accepts or rejects it.
+- Child-spawns-child is forbidden. Child-proposes-child is allowed only through parent-owned adaptive delegation gates.
+- Children may propose XDEF/deeper splits with `TODO_SPLIT_REQUEST.v1`; only the parent applies `split_goal_todo` and dispatches follow-up agents.
+- Persisted coms/Mission Control/adaptive TODO refs must remain hash-only/body-free.
+
+## Stop-on-blocker context layer
+
+When runtime goal context shows a human-decision blocker was already recorded (blocker score >=90, no `nextAgent`, goal paused, blocker visible), report it once and stop. Do not re-dispatch, re-ask the same human question, mark done/skip, hide the blocker, auto-resume, or bypass oracle/no_ship/evidence gates. Wait for explicit `/goal resume` or `resume_goal` before continuing.
+
+## Activation-mode behavior
+
+Respect `/goal mode` (default: `auto` unless a session explicitly persisted `manual` or `validation`):
+
+### manual
+
+Only create TODOs when the user explicitly asks.
+
+### validation
+
+For long work, propose a TODO plan and ask confirmation before creating/applying it.
+
+### auto
+
+For clearly long, multi-step, delegated, factory, or oracle-gated work, create a bounded initial TODO plan, but keep it visible and editable. Use `add_goal_todos` for multi-item plans instead of repeated `add_goal_todo` calls.
+
+## TODO planning rules
+
+When creating TODOs:
+
+0. For an initial plan, batch top-level items with `add_goal_todos`; use `get_goal_todos` or `/goal todo tree` only when the full tree is needed.
+1. Keep TODOs atomic and evidence-oriented.
+2. Prefer 3-9 top-level TODOs for a normal feature.
+3. Use subtodos when a step is too broad, needs delegation, or would require multiple agents/parallel writable work.
+4. Split-before-parallel: create distinct child leaves and acceptance criteria before dispatching concurrent workers.
+5. Mark required vs optional explicitly.
+6. Assign owner: `agent`, `user`, `oracle`, `subagent`, `factory`, or `orchestration`.
+7. Add acceptance criteria for critical TODOs.
+8. Add expected evidence refs or validation commands where possible.
+9. Avoid over-splitting; respect depth/fanout caps.
+
+## Status meanings
+
+Recommended statuses:
+
+```text
+planned        known but not ready/started
+ready          next actionable item
+in_progress    parent agent is working on it
+delegated      child agent/run owns execution temporarily
+claim_returned child output exists, parent has not accepted it
+needs_review   parent review required
+needs_oracle   oracle review required
+needs_user     user input/action required
+blocked        cannot proceed without replan/input/fix
+done           accepted with evidence
+skipped        intentionally skipped with reason
+```
+
+## Delegated TODO claims
+
+When delegating a TODO, pass TODO metadata via `child_goal` once the runtime supports it:
+
+```text
+child_goal.objective = bounded child objective
+child_goal.todo_id = <canonical-active-todo-id from get_goal_todos>  # only when freshly verified
+child_goal.parent_todo_id = <canonical-active-parent-todo-id if freshly verified>
+child_goal.todo_path = <visible-todo-path such as 1.2>  # safe fallback when canonical id is not freshly known; parent resolves it before dispatch when unique
+child_goal.delegation_depth = current agent-depth + 1
+child_goal.completion_policy = return_claim
+child_goal.agentic_validation.mode = oracle_then_auto_accept  # optional; validates claim with oracle child before safe auto-accept
+```
+
+Expected child claim shape (v2 preferred; v1 remains compatible):
+
+```text
+TODO_CHILD_RESULT.v2
+
+todo_id: <id>
+child_goal_status: ready_for_oracle | incomplete | blocked
+status_claim: done | incomplete | blocked
+evidence_refs:
+validation_commands:
+risks:
+acceptance_blockers: <blockers parent must resolve before accepting, or none>
+target_readiness: ready_for_parent_acceptance | needs_parent_review | blocked
+no_ship: true/false  # advisory/readiness evidence; parent/oracle decides review_no_ship; runtime computes hard/effective no_ship
+subtodo_delta_proposals:
+FINAL_MARKER: TODO_CHILD_RESULT_V2_END
+```
+
+Parent action after a claim:
+
+- accept claim only after output contract/gate/evidence checks pass;
+- for `child_goal.agentic_validation.mode=oracle_then_auto_accept`, runtime requests an oracle child to return `todo-claim-validation.v1` and auto-accepts only when worker gate passed, child status is `ready_for_oracle`, status claim is `done`, target readiness is `ready_for_parent_acceptance`, no acceptance blockers remain, oracle `claim_hash` exactly matches the returned claim, `recommended_action=accept_claim`, confidence is MEDIUM/HIGH, no oracle blocking issues remain, and oracle verdict is `PASS` with `no_ship=false`;
+- `WARN`, `FAIL`, oracle `no_ship=true`, missing evidence, missing final marker, or mismatched `claim_hash` must leave the TODO in review/blocked state, not `done`;
+- treat child `no_ship=true` as advisory review evidence, not an automatic child delivery failure when a deliverable was returned;
+- reject/block the claim if evidence is missing or the parent agrees the advisory no_ship is a real blocker;
+- import subtodo proposals only after checking depth/fanout and relevance.
+
+Oracle validation output shape:
+
+```text
+TODO_CLAIM_VALIDATION.v1
+
+todo_id: <id>
+claim_hash: <sha256 returned claim hash>
+verdict: PASS | WARN | FAIL
+recommended_action: accept_claim | needs_review | reject_claim | block
+evidence_refs:
+validation_commands:
+blocking_issues: <issues, or none>
+no_ship: true/false
+confidence: LOW | MEDIUM | HIGH
+FINAL_MARKER: TODO_CLAIM_VALIDATION_END
+```
+
+If a delegated TODO claim has returned:
+
+- Primary Tool API: `resolve_goal_todo({ todo_id, action: "auto" | "complete" | "accept_claim", evidence_refs, validation_commands })`.
+- Compatibility Tool API: `complete_goal_todo` and `accept_goal_todo_claim` use the same parent-owned acceptance behavior for returned claims.
+- Slash command: `/goal todo done <todoId> [evidence]` and `/goal todo accept-claim <todoId> [evidence]` both route through parent acceptance for returned claims.
+- Never mark delegated TODOs `done` while the delegation is queued/running/failed and no returned claim exists.
+- If evidence is missing or `no_ship=true`, call `reject_goal_todo_claim` or `block_goal_todo` unless parent review explicitly accepts the advisory risk.
+
+If a high/xhigh/max TODO-linked child determines the TODO is too broad for its scope/context, or discovers safe completion requires multiple agents/parallel writable leaves, it may return a split request instead of a poor completion:
+
+```text
+TODO_SPLIT_REQUEST.v1
+
+todo_id: <id>
+reason: <why this exceeds child scope/context>
+recommended_action: split | replan | factory | needs_user | blocked
+proposed_subtodos:
+- <bounded child TODO title>
+risk_level: low | medium | high
+validation_plan:
+- <expected evidence or command>
+evidence: <why this split request is justified>
+risks_blockers: <unresolved risks, or none>
+compliance: parent-owned split request only; no child dispatch or parent TODO mutation
+no_ship: false
+FINAL_MARKER: TODO_SPLIT_REQUEST_END
+```
+
+Parent action after a split request:
+
+- validate output contract, depth/fanout caps, scope, no_ship, and relevance;
+- apply `split_goal_todo` only from the parent;
+- assign one writable owner per new leaf and record owned/write paths plus read-across refs;
+- mark the original parent TODO skipped/decomposed only after child TODOs are created;
+- never let the child directly split, dispatch, or complete the parent TODO.
+
+## Completion gate checklist
+
+Before calling `propose_goal_completion`, verify:
+
+- `get_goal_todos.details.completion_ready` is true and `effective_no_ship` is false;
+- all required TODOs are `done` or `skipped` with explicit reason; critical/delegated/factory/orchestration skips also cite evidence refs or validation commands;
+- no required TODO is `planned`, `ready`, `in_progress`, `delegated`, `claim_returned`, `needs_user`, `needs_oracle`, or `blocked`;
+- critical/delegated TODOs have evidence refs or validation commands;
+- factory/orchestration TODOs cite validation/sentinel/checkpoint artifacts when relevant;
+- known risks are included in the completion proposal;
+- no hard or unresolved review no-ship blocker remains (`hard_no_ship=false`, `review_no_ship=false`, `effective_no_ship=false`).
+
+If any item fails, continue work or report the blocker instead of proposing completion.
+
+## HUD guidance
+
+HUD should show compact summary, not the whole tree:
+
+```text
+runtime goal active · loop on 2/12 · oracle none
+todos 5/12 · active 2 · blocked 1 · delegated 3
+next agent 1.2 add reducer · next user 3 confirm UX
+```
+
+Use detailed commands/overlay for the full tree.
+
+## Coms and Mission Control safety
+
+For TODO-linked communication:
+
+- use `taskId=todoId`;
+- use `taskHash` and `outputHash`;
+- use safe repo-relative `artifactRefs`;
+- keep `bodyStored=false`;
+- keep command proposals parent-owned and proposal-only;
+- never target direct worker writes from Mission Control.
+
+## Factory/orchestration evidence
+
+When TODOs represent factories/orchestrations/chains, reference existing artifacts instead of duplicating bodies:
+
+- `reports/factory-runs/<runId>/validation.json`
+- `reports/factory-runs/<runId>/checkpoints/*.checkpoint.json`
+- `reports/factory-runs/<runId>/DONE.sentinel`
+- `reports/orchestrations/<runId>/orchestration-plan.json`
+- `reports/orchestrations/<runId>/status.jsonl`
+- `reports/chains/<runId>/chain-plan.json`
+
+## Implementation advice
+
+The harness implements the core phases. For future changes, preserve the phased safety model:
+
+1. Flat TODOs attached to `/goal`.
+2. HUD summary and prompt injection.
+3. Completion blocker in `propose_goal_completion`.
+4. Tree/subtodos.
+5. Delegated TODO claims.
+6. TODO overlay.
+7. Adaptive delegation mapping.
+8. Factory/orchestration/chain imports.
+9. Mission Control/context/queue integrations.
+
+Do not start with full X-depth delegation. First prove flat TODOs, restore, HUD, and completion blocking.
+
+## Oracle review behavior
+
+For oracle review of a goal with TODOs:
+
+- inspect TODO summary;
+- sample critical done TODO evidence;
+- verify delegated claims were parent-accepted, not child-self-completed;
+- verify required TODOs are closed;
+- verify validation commands and sentinels exist when claimed;
+- return PASS/WARN/FAIL and explicit `no_ship`.
+
+Missing TODO evidence means WARN or FAIL, never PASS.

package/.pi/skills/zob-harness/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: zob-harness
+description: Use when working inside the ZOB Pi harness, designing agentic workflows, creating specialist prompts, adding Pi extensions, or turning repeated tasks into software factories.
+---
+# ZOB Harness Skill
+
+## When to use
+
+Use this skill for any task involving:
+- Pi extensions, prompt templates, skills, or agent definitions.
+- Multi-agent delegation workflows.
+- Safety gates and damage-control policy.
+- Software-factory design from repeated manual workflows.
+- Runtime tool/command routing via `.pi/capabilities/zob-public-runtime-capabilities.json`.
+
+For routing behavior, load `zob-tool-router` before non-trivial or tool-ambiguous work. For compaction/recovery behavior, load `zob-compaction-policy` before changing compaction hooks or resuming from a compacted long-running goal. For domain behavior, load the domain skill named by the registry instead of inlining details here: `zob-goal-todo-tree`, `zob-coms-v2-live`, `zob-coms-safety`, `zob-mission-control-coms`, `zob-autonomous-runtime`, `zob-factory`, `zob-sandbox`, `zob-oracle`, or `zob-spec` as applicable.
+
+## Operating model
+
+1. Classify the task as one of: `explore`, `plan`, `implement`, `oracle`, `factory`, `orchestrator`.
+2. For non-trivial or tool-ambiguous work, apply `zob-tool-router`: classify applicable families, then use/delegate/skip each with a reason.
+3. Use `orchestrator` when the task needs Chief Vision coordination, multi-agent decomposition, Lead/Worker routing, goal/TODO graph governance, or parent-owned dispatch; the root should delegate substantive work rather than do it directly.
+4. Check `.pi/capabilities/zob-public-runtime-capabilities.json` for the relevant tool/command family, mode allowlist, skill refs, and no-ship notes.
+5. If broad or risky, use the `delegate_agent` tool before editing.
+6. For delegated work, use the six-part contract:
+   - TASK
+   - EXPECTED OUTCOME
+   - REQUIRED TOOLS
+   - MUST DO
+   - MUST NOT DO
+   - CONTEXT
+7. For parallel owner micro-worker pools, split broad TODOs into owned leaves before dispatch; use `zob_worker_pool_plan`/`zob_worker_pool_status` only to create/read metadata-only owned/write/read-across coordination records, then dispatch actual children parent-owned through `delegate_task`/`delegate_agent` with explicit TODO linkage and repo-relative owned/write grants. `zob_worker_pool_owner_request`/`zob_worker_pool_owner_decision` record body-free Goal Room owner arbitration only; they never apply changes, mutate TODOs, or dispatch children.
+8. Use Goal Room as the canonical parent-visible coordination record; ZPeer is transient/local and cannot replace typed decisions, evidence, or owner arbitration.
+9. For code changes, verify with the smallest relevant command first.
+10. End with evidence and a compliance line.
+
+## Planning in auto-mode
+
+When the user asks for a plan:
+- Produce exactly one plan for the request.
+- If you already produce the plan in the current response, do not emit a `mode="plan"` intent.
+- Emit a `mode="plan"` intent only when deliberately deferring the actual detailed plan to the next turn; keep that response to a short handoff.
+- Never both: full plan content and `mode="plan"` intent in the same response.
+- If a prior assistant response already contained a complete plan for the same request, do not restate it; summarize that the plan exists and ask whether to refine, save, or implement it.
+- The harness may auto-capture complete plans into `plans/`; do not manually duplicate that artifact unless the user asks.
+
+## Project files
+
+- Extension: `.pi/extensions/zob-harness/index.ts`
+- Agents: `.pi/agents/*.md`
+- Prompt templates: `.pi/prompts/*.md`
+- Capability registry: `.pi/capabilities/zob-public-runtime-capabilities.json`
+- Damage rules: `.pi/damage-control-rules.json`
+- Architecture docs: `docs/`
+- Goal TODO tree plan: `docs/ZOB_GOAL_TODO_TREE_PLAN.md`
+
+## Safety reminders
+
+- Never read `.env` or secrets. Ask the user instead.
+- Never run destructive git/shell commands without explicit approval.
+- Do not commit unless explicitly requested.
+- Delegation/orchestration `allowed_paths` are repo-relative-only grants; do not use absolute/home/traversal/broad-root paths. Represent external context through repo-local `reports/...` snapshots or `context_ref` artifacts. `forbidden_paths` stay deny-only and may use specific absolute/home patterns when safe.
+- Stop-on-blocker: when a human-decision blocker is already visible on a paused goal (score >=90, no `nextAgent`), report once and wait for `/goal resume` or `resume_goal`; do not repeat the ask, redispatch, auto-resume, or bypass oracle/no_ship/evidence gates.
+- Parallel owner pools are supervised: worker-pool tools are metadata/coordination only; actual worker launch remains parent-owned through delegation tools. No child-spawns-child, no child parent-TODO mutation, no direct main-workspace apply/merge, no stale/offline delivery success, and no completion without validation/oracle evidence when required.
+
+## Bash timeouts
+
+Every `bash` call MUST set a `timeout` scaled to the action (small reads/greps: ~5-30 s; repo-wide greps/finds: ~60 s; npm/build/install: ~300 s). On timeout, first narrow the command (scope, glob, depth); only retry with a larger timeout when the narrow form is correct but genuinely slow, and stay reasonable — never set `timeout: 0`.

package/.pi/skills/zob-mission-control-coms/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: zob-mission-control-coms
+description: Use when reading or controlling ZOB coms from Mission Control, including live presence, stale peers, command proposals, and oracle/no-ship review.
+---
+# ZOB Mission Control Coms Skill
+
+## When to use
+
+Use for:
+- `zob_mission_control_snapshot` interpretation;
+- `zob_coms_readiness` review;
+- live peer online/stale/offline diagnosis;
+- command proposal creation;
+- oracle/no-ship communication reviews.
+
+## MUST DO
+
+- Read Mission Control as metadata-only.
+- Use `zob_mission_control_snapshot` for queue/runs/coms/live presence overview.
+- Use `zob_coms_readiness` before approving coms changes.
+- Use `zob_mission_control_propose_command` for pause/resume/replan/request_oracle/stop/approve.
+- Treat direct worker command targets as blocked.
+- Escalate stale/offline peers as blockers or replan candidates.
+- Verify `proposalOnly=true`, `directWorkerWrites=false`, `transportDispatch=false` for dashboard commands.
+
+## MUST NOT
+
+- Do not dispatch worker writes from Mission Control.
+- Do not override topology or stale/no-ship gates.
+- Do not store raw rationale or command body; use hashes and artifact refs.
+- Do not use dashboard state as proof of task completion unless live response/output hash exists.
+
+## Operator checklist
+
+1. Snapshot shows live presence and no direct writes.
+2. Readiness PASS.
+3. No stale/offline peer counted as success.
+4. Command is proposal-only.
+5. Oracle/no-ship gates remain enforceable.

package/.pi/skills/zob-oracle/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: zob-oracle
+description: Use for skeptical validation, no-ship decisions, evidence gates, final reports, and regression/security reviews.
+---
+# ZOB Oracle Skill
+
+## When to use
+
+Use before marking work complete, before pilot/batch, before sandbox writes are applied, and before enabling any autonomous path.
+
+## Gate rules
+
+- Lead with PASS / WARN / FAIL.
+- `no_ship=true` blocks completion.
+- Missing evidence means WARN or FAIL, never PASS.
+- Oracle/security roles must not be downgraded silently.
+- Final reports must include evidence refs, blockers, and no-ship decision.
+
+## Safety
+
+Oracle is read-only by default. It may inspect artifacts and commands/logs, but does not patch.

package/.pi/skills/zob-owner-pool-drill-writer/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: zob-owner-pool-drill-writer
+description: Use when the owner gives a plain-language intention and wants it rewritten into a safe, copy-pasteable ZOB parallel owner micro-worker pool drill or execution prompt.
+---
+# ZOB Owner Pool Drill Writer Skill
+
+## Purpose
+
+Use this skill to turn a short owner ask into a complete ZOB parallel owner micro-worker pool prompt. The owner may write only a few plain-language notes; the assistant expands them into a structured, safe drill with objective, assumptions, path grants, worker assignments, phases, owner arbitration, validation, metadata audit, and result contract.
+
+This skill writes prompts only. It does not dispatch workers, apply changes, mutate TODOs, commit, or enable autonomous production writes.
+
+## Lightweight intake form
+
+Ask for missing details only when they change safety. Otherwise use the defaults.
+
+```text
+1. Objective: [what should the worker pool accomplish?]
+2. Source/read paths: [default: ask owner; never assume broad repo access]
+3. Desired outputs: [default: reports/proposals only]
+4. Workers: [default: 3 micro-workers: mapper, implementer/planner, oracle]
+5. Write mode: [default: reports-only]
+   - reports-only: workers may write only report/proposal artifacts
+   - source-write: requires explicit owner request plus sandbox/merge/oracle gates
+6. Validation commands: [default: narrowest relevant read/check command; if unknown, ask]
+7. Time/scale: [default: one bounded slice, no batch scaling]
+8. Special constraints: [forbidden paths, no-ship gates, human decisions]
+```
+
+## Defaults
+
+- Mode: `reports-only`.
+- Dispatch: parent-owned only.
+- Coordination record: Goal Room is canonical.
+- Peer/live chatter: ZPeer is transient only and cannot replace typed Goal Room decisions or evidence.
+- Worker policy: no child-spawns-child; no child mutates parent TODOs; no direct main-workspace apply/merge.
+- Persistence: no raw body persistence in coordination metadata; use body-free summaries, hashes, paths, and evidence refs.
+- Writes: read-across/write-by-owner. Workers can read cited context, but only the owning worker may propose or perform writes within granted owned paths.
+- Source writes: prohibited unless the owner explicitly requests `source-write` and the generated prompt states sandbox, merge, rollback, validation, oracle, and human approval gates.
+- Git: no commits, pushes, tags, staging, or direct git state changes unless separately authorized by governed ZOB commit policy.
+
+## Conversion procedure
+
+1. Extract the owner intent into one sentence: `OBJECTIVE`.
+2. Identify concrete `READ_PATHS`, `OWNED_PATHS`, and `OUTPUT_PATHS`. If paths are absent, use placeholders and ask the owner to fill them.
+3. Choose worker roles. Prefer small, bounded micro-workers:
+   - Mapper: inventories relevant files/artifacts and creates a path/evidence map.
+   - Planner or Implementer: drafts the proposed changes or performs the bounded owned slice.
+   - Oracle: checks safety, evidence, validation, and no-ship conditions.
+   Add workers only when the objective has clearly separable owned paths.
+4. Choose mode:
+   - `reports-only` for exploration, planning, audits, prompts, specs, and proposals.
+   - `source-write-gated` only when explicitly requested.
+5. Generate a copy-pasteable prompt using the template below.
+6. End with a strict result contract so downstream agents return comparable evidence.
+
+## Copy-paste template
+
+```text
+ORIGINAL_OWNER_ASK: [paste the owner’s plain-language request]
+
+1. TASK: Run a bounded ZOB parallel owner micro-worker pool drill for [OBJECTIVE].
+2. EXPECTED OUTCOME: [observable deliverable: report/proposal/diff candidate/validation verdict], with evidence and no auto-apply.
+3. REQUIRED TOOLS: [list allowed tools only; default: read, grep, find, ls, bash, write/edit only for allowed report paths]
+4. MUST DO:
+   - Keep this to one bounded slice: [SCOPE].
+   - Use Goal Room as the canonical coordination record; ZPeer is transient only.
+   - Use parent-owned dispatch only; workers must not spawn children.
+   - Enforce read-across/write-by-owner.
+   - Persist no raw message bodies in metadata; use paths, hashes, summaries, and evidence refs.
+   - Default to reports-only outputs under [OUTPUT_PATHS].
+   - Record owner requests for any cross-owner or source-write need; decisions are metadata only and never auto-apply.
+   - Run validation commands: [VALIDATION_COMMANDS].
+   - Produce a metadata audit: worker IDs/roles, owned paths, read paths, outputs, evidence refs, validation results, no-ship status.
+5. MUST NOT DO:
+   - Do not commit, push, tag, stage, or alter git state.
+   - Do not read/write secrets or forbidden paths: [FORBIDDEN_PATHS].
+   - Do not write source files unless source-write is explicitly requested and sandbox/merge/oracle/human gates are stated.
+   - Do not count append-only or stale/offline records as delivery success.
+   - Do not auto-apply, auto-merge, or claim autonomous production readiness.
+6. CONTEXT:
+   - Objective: [OBJECTIVE]
+   - Assumptions: [ASSUMPTIONS]
+   - Read paths: [READ_PATHS]
+   - Owned/write paths: [OWNED_PATHS]
+   - Output paths: [OUTPUT_PATHS]
+   - Write mode: [reports-only | source-write-gated]
+
+WORKER ASSIGNMENTS:
+- Worker A / Mapper:
+  - Owns: [owned report path]
+  - Reads: [read paths]
+  - Produces: path map, risk map, evidence refs.
+- Worker B / [Planner or Implementer]:
+  - Owns: [owned report or sandbox path]
+  - Reads: [read paths]
+  - Produces: [proposal, patch plan, or sandbox diff candidate].
+- Worker C / Oracle:
+  - Owns: [oracle report path]
+  - Reads: Worker A/B outputs and validation logs.
+  - Produces: PASS/WARN/FAIL, no_ship flag, evidence gaps, merge/apply blockers.
+
+PHASES:
+1. Intake and scope lock: confirm objective, paths, mode, forbidden paths, and validation.
+2. Metadata setup: create/read only body-free coordination records; no raw body persistence.
+3. Parallel work: workers operate only within owned grants; read-across is read-only.
+4. Owner arbitration: cross-owner/source-write requests must be explicit typed requests and parent decisions.
+5. Validation: run [VALIDATION_COMMANDS] or report why not feasible.
+6. Oracle review: verify evidence, safety rules, and no-ship status.
+7. Final synthesis: summarize outputs, evidence, risks, and exact next owner decision.
+
+RESULT CONTRACT:
+- gap_verdict: SUFFICIENT or GAP, with exact missing behavior if GAP
+- worker_outputs: paths and one-line summaries
+- validation_commands: exact commands run, or not run with reason
+- results: exact outcomes
+- metadata_audit: workers, owned paths, read paths, output paths, owner requests/decisions, hashes/evidence refs
+- no_ship: true/false with reason
+- risks/blockers: unresolved risks
+- compliance: Goal Room canonical, ZPeer transient, parent-owned dispatch, no child-spawns-child, read-across/write-by-owner, no raw body persistence, no auto-apply, no commits
+- deliverable_delivered: yes/no
+```
+
+## Example 1: reports-only full drill
+
+Owner writes:
+
+```text
+Je veux que plusieurs workers analysent notre workflow ProjectDNA et me sortent un plan clair, sans modifier le code.
+```
+
+Generated prompt:
+
+```text
+ORIGINAL_OWNER_ASK: Je veux que plusieurs workers analysent notre workflow ProjectDNA et me sortent un plan clair, sans modifier le code.
+
+1. TASK: Run a bounded ZOB parallel owner micro-worker pool drill to analyze the ProjectDNA workflow and produce a clear reports-only improvement plan.
+2. EXPECTED OUTCOME: Report artifacts with workflow map, improvement plan, oracle review, validation evidence, and no source changes.
+3. REQUIRED TOOLS: read, grep, find, ls, bash, write.
+4. MUST DO:
+   - Keep this to one bounded ProjectDNA workflow analysis slice.
+   - Use Goal Room as the canonical coordination record; ZPeer is transient only.
+   - Use parent-owned dispatch only; workers must not spawn children.
+   - Enforce read-across/write-by-owner.
+   - Persist no raw message bodies in metadata; use paths, hashes, summaries, and evidence refs.
+   - Write only reports under `reports/project-dna-owner-pool-drill/`.
+   - Run validation commands: `npm run validate:project-dna` if feasible.
+   - Produce a metadata audit with workers, paths, outputs, evidence refs, validation results, and no-ship status.
+5. MUST NOT DO:
+   - Do not edit source files, prompts, existing skills, docs, package files, or registry.
+   - Do not commit, push, tag, stage, or alter git state.
+   - Do not read/write secrets, `.env`, keys, `~/.ssh`, `~/.aws`, `node_modules`, `dist`, `build`, or `.git`.
+   - Do not auto-apply or claim autonomous production readiness.
+6. CONTEXT:
+   - Objective: Analyze the ProjectDNA workflow and produce a clear plan.
+   - Assumptions: Reports-only; no code changes.
+   - Read paths: `.pi/factories/project-dna`, `.pi/skills/zob-project-dna/SKILL.md`, relevant package scripts.
+   - Owned/write paths: `reports/project-dna-owner-pool-drill/worker-a-map.md`, `worker-b-plan.md`, `worker-c-oracle.md`.
+   - Output paths: `reports/project-dna-owner-pool-drill/`.
+   - Write mode: reports-only.
+
+WORKER ASSIGNMENTS:
+- Worker A / Mapper: produce workflow/path/evidence map.
+- Worker B / Planner: produce improvement plan and owner decision points.
+- Worker C / Oracle: review evidence, safety, validation, and no-ship status.
+
+PHASES: intake and scope lock; body-free metadata setup; parallel reports-only work; owner arbitration for any cross-owner need; validation; oracle review; final synthesis.
+
+RESULT CONTRACT:
+- gap_verdict
+- worker_outputs
+- validation_commands
+- results
+- metadata_audit
+- no_ship
+- risks/blockers
+- compliance
+- deliverable_delivered: yes/no
+```
+
+## Example 2: source-write plan remains gated/sandboxed
+
+Owner writes:
+
+```text
+Je veux que les workers préparent une petite correction dans le runtime, mais je veux valider avant que ça touche le repo.
+```
+
+Generated prompt:
+
+```text
+ORIGINAL_OWNER_ASK: Je veux que les workers préparent une petite correction dans le runtime, mais je veux valider avant que ça touche le repo.
+
+1. TASK: Run a bounded ZOB parallel owner micro-worker pool drill to prepare a gated sandbox source-write correction plan for the specified runtime issue.
+2. EXPECTED OUTCOME: Sandbox diff candidate plus validation and oracle reports; no main-workspace apply unless the owner later approves through explicit merge gates.
+3. REQUIRED TOOLS: read, grep, find, ls, bash, write, edit only inside the declared sandbox/allowed paths.
+4. MUST DO:
+   - Ask the owner to specify the exact runtime issue and allowed source paths before any source-write work.
+   - Use Goal Room as the canonical coordination record; ZPeer is transient only.
+   - Use parent-owned dispatch only; workers must not spawn children.
+   - Enforce read-across/write-by-owner.
+   - Work in a sandbox/temp workspace or explicit quarantine path, not direct main-workspace source files.
+   - Record diff hash, changed paths, rollback notes, validation logs, and oracle verdict.
+   - Treat owner merge approval as a later separate decision; this prompt does not auto-apply.
+5. MUST NOT DO:
+   - Do not write directly to main-workspace runtime files.
+   - Do not commit, push, tag, stage, or alter git state.
+   - Do not read/write secrets, `.env`, keys, `~/.ssh`, `~/.aws`, `node_modules`, `dist`, `build`, or `.git`.
+   - Do not auto-merge, auto-apply, or claim autonomous production readiness.
+6. CONTEXT:
+   - Objective: Prepare a small runtime correction candidate for owner review.
+   - Assumptions: Source-write is gated and sandboxed only.
+   - Read paths: [owner fills exact runtime paths].
+   - Owned/write paths: [sandbox/quarantine paths only].
+   - Output paths: [sandbox diff report, validation log, oracle report].
+   - Write mode: source-write-gated.
+
+WORKER ASSIGNMENTS:
+- Worker A / Mapper: inspect allowed runtime paths and identify minimal change surface.
+- Worker B / Sandbox Implementer: create only the sandbox diff candidate and rollback notes.
+- Worker C / Oracle: review diff hash, validation logs, safety gates, and no-ship status.
+
+PHASES: owner path confirmation; sandbox setup; parallel read/planning; sandbox-only implementation; validation; oracle review; owner merge decision request.
+
+RESULT CONTRACT:
+- gap_verdict
+- worker_outputs
+- validation_commands
+- results
+- metadata_audit
+- no_ship
+- risks/blockers
+- compliance
+- deliverable_delivered: yes/no
+```
+
+## Refusal and clarification triggers
+
+Refuse or ask for clarification instead of generating a runnable drill when:
+
+- The owner asks for commits, pushes, tags, secret access, destructive commands, or broad unbounded writes.
+- The owner requests source writes but gives no path boundaries or rejects sandbox/oracle gates.
+- The prompt would require child-spawns-child, auto-apply, raw body persistence, or treating non-live append-only records as delivery success.
+- The objective is too broad to be one bounded slice.