zob-harness 0.1.0

package/.pi/skills/zob-autonomous-runtime/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: zob-autonomous-runtime
+description: Use when running or reviewing zob_autonomous_* runtime tools, autonomous smoke/validation gates, or no-ship/global autonomy claims.
+---
+# ZOB Autonomous Runtime Skill
+
+## When to use
+
+Use this skill before using or documenting `zob_autonomous_*` tools:
+- `zob_autonomous_dry_run`
+- `zob_autonomous_readonly_smoke`
+- `zob_autonomous_validate_smoke`
+- `zob_autonomous_validate_run`
+
+## Tool routing
+
+- Start with the capability registry: `.pi/capabilities/zob-public-runtime-capabilities.json`.
+- Use `zob-factory` for manifests, checkpoints, reports, and factory execution posture.
+- Use `zob-sandbox` for any write-capable or quarantine workflow design.
+- Use `zob-oracle` for validation, no-ship decisions, and final evidence review.
+
+## Gates and meanings
+
+- `zob_autonomous_dry_run`: factory-mode planning/report metadata only; no live/global routing and no production writes.
+- `zob_autonomous_readonly_smoke`: factory-mode readonly smoke of reports/artifacts; no child dispatch, daemon, production writes, or global autonomy claim.
+- `zob_autonomous_validate_smoke`: readonly validation of smoke artifacts.
+- `zob_autonomous_validate_run`: readonly validation of run artifacts.
+
+## MUST DO
+
+- Treat all autonomy as supervised unless an explicit, later oracle-approved gate says otherwise.
+- Keep dry-run, readonly smoke, validation, and final E2E evidence separate in reports.
+- Require final E2E proof plus oracle PASS/no_ship=false before claiming an autonomous path is complete.
+- Preserve metadata/hash-only posture; never store raw prompt or output bodies in artifacts.
+- Record blockers for missing sentinel/report/validation evidence instead of inferring success.
+
+## MUST NOT
+
+- Do not claim global autonomy is complete from dry-run or readonly smoke results.
+- Do not route production writes, daemon behavior, network/browser/API access, or child-agent dispatch through these tools unless the registry and a task-specific gate explicitly allow it.
+- Do not bypass factory quarantine, sandbox, or oracle gates.

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

@@ -0,0 +1,79 @@
+---
+name: zob-commit
+description: Use when planning, reviewing, or executing governed ZOB commit/autocommit/autopush behavior through explicit /zcommit commands or the agent-executable zob_zcommit_run tool.
+---
+# ZOB Commit Skill
+
+## Purpose
+
+This skill defines the easy governed commit workflow for ZOB agents. The `/zcommit` runtime command and `zob_zcommit_run` tool prioritize quick, beautiful Conventional Commits over strict per-session ownership tracking: when the user explicitly asks for commit/push, the assistant should use `zob_zcommit_run` instead of asking the user to paste slash commands. Direct git commit/push/tag remains forbidden.
+
+Baseline safety remains: do not commit, tag, or push unless the user explicitly asks or `/zcommit autocommit on` / `/zcommit autopush on` authorizes it for the current repo/session scope.
+
+## Allowed command surface
+
+Use only these explicit commands/tools. Do not invent aliases, shortcuts, shell fallbacks, or alternate command names.
+
+- `/zcommit status [paths/globs...]`
+- `/zcommit plan [paths/globs...]`
+- `/zcommit adopt <paths...>`
+- `/zcommit commit [paths/globs...]`
+- `/zcommit push`
+- `/zcommit autocommit on`
+- `/zcommit autocommit off`
+- `/zcommit autopush on`
+- `/zcommit autopush off`
+- `zob_zcommit_run` tool with `action=plan|commit|push|commit_and_push`
+
+## Hard stops
+
+- Do not run direct `git commit`, `git push`, `git tag`, force push, `git add .`, or `git add -A`.
+- Do not commit secrets, credentials, generated runtime artifacts, local ledgers, sessions, logs, temporary files, vendor folders, or build outputs.
+- Do not use `/zcommit adopt` for root/global/broad directory/wildcard adoption; it is an advanced metadata-only ownership hint and should not be needed in normal easy mode.
+- Do not treat autocommit or autopush as enabled unless the corresponding `/zcommit ... on` toggle is active for the current repo/session scope.
+- Do not push if autopush is off, the work is no-ship, the target branch/remote is not allowed, or the last commit was not created by `/zcommit commit`.
+
+## Governed workflow
+
+1. Load `.pi/git-policy.json` and this skill before any governed commit/push work.
+2. If the user asks the assistant to commit and/or push, call `zob_zcommit_run`; do not answer with instructions for the user to run `/zcommit` manually.
+3. Run `/zcommit status [paths/globs...]` or `/zcommit plan [paths/globs...]` when the human wants an interactive command, or `zob_zcommit_run action=plan` when the agent needs a plan without staging.
+4. Normal easy mode does not require `/zcommit adopt`: `/zcommit plan` and `zob_zcommit_run` select all dirty workspace files that pass forbidden-path filtering. When you need “only these session files”, use `zob_zcommit_run scope=session_modified`, or pass explicit repo-relative files, directories, or globs directly to `/zcommit plan` and `/zcommit commit`.
+5. Optionally run `/zcommit adopt <paths...>` only as an advanced metadata hint for strict/legacy flows; it remains metadata-only and does not stage.
+6. `/zcommit plan [paths/globs...]` / `zob_zcommit_run action=plan` produces:
+   - safe workspace dirty files selected for commit, optionally limited by the pathspecs;
+   - forbidden paths excluded from commit;
+   - advisory validation command/status;
+   - Conventional Commit type/scope/subject/body plan;
+   - push target if and only if push is requested or authorized.
+7. `/zcommit commit [paths/globs...]` and `zob_zcommit_run action=commit|commit_and_push` stage only the selected safe paths with `git add -- <paths>`, never `git add .` or `git add -A`, then create the Conventional Commit. Advisory validation failures are recorded in the commit body instead of blocking easy-mode commit.
+8. Run `/zcommit push` or `zob_zcommit_run action=push|commit_and_push` when push is explicitly requested, the branch/remote are allowed, the commit was created by the zcommit engine, HEAD still equals that commit, and there are no no-ship blockers. Push is not blocked by advisory validation by default.
+
+## Commit message standard
+
+Use Conventional Commits:
+
+```text
+<type>(<scope>): <imperative summary>
+
+<body with validation evidence and risk notes when useful>
+```
+
+Allowed default types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`, `build`, `perf`, `revert`.
+
+Examples:
+
+- `docs(commit): add governed zcommit policy`
+- `fix(coms): preserve live delivery guard`
+
+## Autocommit/autopush defaults
+
+- `autocommit` defaults to `off`.
+- `autopush` defaults to `off`.
+- Turning autocommit on with `/zcommit autocommit on` authorizes the assistant to create an easy Conventional Commit automatically at assistant message end when safe workspace changes exist.
+- Turning autopush on with `/zcommit autopush on` remains separate and requires autocommit to be on first.
+- Autopush never implies force push, tag creation, or bypassing branch/remote/no-ship gates.
+
+## Easy workspace file rule
+
+A governed easy commit may include all dirty workspace files that pass forbidden-path filtering, or a narrower explicit subset when pathspecs are passed to `/zcommit plan` / `/zcommit commit`. Pathspecs can be repo-relative files, directories, or globs such as `.pi/skills/zob-*/SKILL.md`. The policy should exclude secrets, credentials, generated/runtime ledgers, sessions, logs, temporary files, vendor folders, and build outputs. `/zcommit commit` still stages explicit selected paths only; it never stages the entire workspace through `git add .` or `git add -A`.

package/.pi/skills/zob-compaction-policy/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: zob-compaction-policy
+description: Use when reviewing, designing, triggering, or recovering from ZOB/Pi context compaction, branch summaries, long-goal continuation, or post-compaction skill/context reloads.
+---
+# ZOB Compaction Policy Skill
+
+## When to use
+
+Use this skill when:
+
+- context usage is high or compaction happened recently;
+- a runtime `/goal` continuation is near context limits;
+- `/tree` branch summarization may lose important ZOB state;
+- the agent must resume work from a compacted summary;
+- changing compaction hooks, context summaries, prompt stacks, or session continuity behavior.
+
+Canonical policy doc: `docs/ZOB_COMPACTION_POLICY.md`.
+
+## Core rule
+
+A ZOB compaction summary is a **continuity index**, not the source of truth. Preserve refs, decisions, state, evidence, blockers, and next actions; reload detailed skills/docs/files by path when needed.
+
+## Source-of-truth hierarchy
+
+1. Persisted ZOB state and ledgers.
+2. Repo files and cited artifacts.
+3. Compaction or branch summary.
+4. Model memory from before compaction.
+
+Prefer `get_goal`, `get_goal_todos`, safe file reads, reports, and validation artifacts over assumptions from memory.
+
+## Mandatory preservation checklist
+
+When creating or reviewing a compaction summary, ensure it captures:
+
+- original user ask, constraints, non-goals, success criteria;
+- active ZOB mode and role boundary;
+- runtime goal id/objective/status/oracle/no-ship state;
+- TODO graph summary, active/open/blocked/delegated/claim-returned TODOs, evidence refs, validation commands, next TODO;
+- current work thread: current slice, last action, next exact action, what not to redo;
+- critical skill/prompt/doc/source/report refs to reload;
+- key decisions and rationale;
+- files read/modified and why they matter, without full bodies;
+- delegation run ids, agents, statuses, gate result, no-ship/evidence summary;
+- validations and artifact refs;
+- blockers and hard/review/effective no-ship;
+- reload rules;
+- body policy: refs/hashes only for persisted metadata.
+
+## Budget policy
+
+- Target: 3k-5k tokens.
+- Hard cap: 8k tokens.
+- Small tasks: 1k-2k tokens.
+- If over budget, shrink resolved details, verbose subagent summaries, superseded validations, and long file lists before touching blockers/no-ship/TODO/next action.
+
+## Refs-not-bodies policy
+
+Do not paste full skills, prompts, file bodies, raw subagent outputs, raw diffs, raw tool outputs, secrets, or credentials. Keep refs and reload rules instead.
+
+Examples:
+
+```text
+critical_skill_refs:
+- .pi/skills/zob-tool-router/SKILL.md
+- .pi/skills/zob-goal-todo-tree/SKILL.md
+- .pi/skills/zob-compaction-policy/SKILL.md
+
+reload_rules:
+- Re-read the relevant skill before applying detailed behavior.
+- Re-read changed files before editing after compaction.
+```
+
+## Post-compaction behavior
+
+After compaction:
+
+1. Trust persisted state and artifacts over summary prose.
+2. Re-read critical skills/docs/files before detailed changes.
+3. Re-check active goal/TODO state before completing or delegating.
+4. Re-run or inspect validation evidence before claiming success.
+5. If blockers/no-ship were compacted, resolve them explicitly before completion.
+
+## No-ship conditions
+
+Treat these as blockers:
+
+- compaction summary lost active goal/TODO/blocker state;
+- raw prompt/output/diff bodies are stored in ZOB compaction details or ledgers;
+- post-compaction completion relies only on summary memory;
+- critical skill/doc refs are missing for a long-running or delegated task;
+- no-ship or oracle status is unknown but completion is attempted.

package/.pi/skills/zob-compute-profile/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: zob-compute-profile
+description: "Use when selecting, previewing, validating, or implementing ZOB compute/effort profiles: auto, low, medium, high, xhigh, max."
+---
+# ZOB Compute Profile Skill
+
+## Purpose
+
+Compute profiles control how much workflow effort ZOB spends on a task. They are hard policy/cap inputs, not vague encouragement to “try harder”.
+
+Canonical plan:
+
+- `docs/ZOB_COMPUTE_PROFILE_ROUTING_PLAN.md`
+
+## Profiles
+
+```text
+auto   → preview then resolve to low/medium/high/xhigh/max
+low    → single-agent or deterministic fast path
+medium → small supervised workflow
+high   → multi-lane workflow with validation/oracle
+xhigh  → extra-high expert workflow with richer benchmarks and adversarial review
+max    → maximum bounded supervised workflow; requires strict budget/human gates
+```
+
+## TODO/delegation behavior by profile
+
+- `low`: single-agent/best-effort. Do not spend extra turns on recursive split or background child orchestration; return incomplete/blocked if the box is too small.
+- `medium`: small supervised workflow. A child may suggest a split in final output, but live/background escalation is not the default.
+- `high`: multi-lane parent-owned workflow. Use active-session background delegation when useful, and let TODO-linked children return `TODO_SPLIT_REQUEST.v1` early when the TODO is too broad for their context.
+- `xhigh`: same as high with deeper bounded decomposition and stronger validation/oracle.
+- `max`: same as xhigh, but strict budget/human/oracle gates are mandatory before scale-up.
+
+Even at high/xhigh/max, child agents must not directly spawn children or mutate parent TODO state; they request split/replan and the parent applies it.
+
+## Required behavior
+
+Before using compute to justify more work:
+
+1. Run or inspect a compute preview when `requested_profile=auto`.
+2. Resolve to an effective profile and hard caps.
+3. Keep child dispatch parent-owned; child direct dispatch remains forbidden.
+4. Keep safety, budget, path, and sandbox gates stronger than profile preference.
+5. Persist only metadata/hash-safe artifacts; do not persist raw task/prompt/output bodies.
+6. Treat `max` as approval-gated; do not auto-select it silently.
+
+## Native surfaces
+
+- Slash commands:
+  - `/compute`
+  - `/effort`
+- Runtime tools:
+  - `zob_compute_preview`
+  - `zob_compute_resolve_profile`
+  - `zob_compute_plan_workflow`
+  - `zob_compute_validate_profile`
+  - `zob_compute_write_profile_reports`
+- Deterministic scripts:
+  - `npm run preview:compute-profile:project-dna-smoke`
+  - `npm run validate:compute-profile:project-dna-smoke`
+  - `npm run plan:compute-workflow:project-dna-smoke`
+  - `npm run validate:compute-workflow:project-dna-smoke`
+  - `npm run snapshot:compute-profile:project-dna-smoke`
+  - `npm run smoke:compute-profile-regression`
+- Policy files:
+  - `.pi/compute-profiles/defaults.json`
+  - `.pi/compute-profiles/overrides.json`
+  - `.pi/compute-profiles/risk-rules.json`
+  - `npm run validate:compute-profile-policy`
+- Plan/doc:
+  - `docs/ZOB_COMPUTE_PROFILE_ROUTING_PLAN.md`
+
+## No-ship rules
+
+Block profile readiness if any occur:
+
+- requested/effective profile mismatch is unexplained;
+- caps are missing for a live or agentic workflow;
+- child agents exceed `maxAgents`, `maxParallel`, or depth caps;
+- strict budget is required but absent;
+- oracle is required but missing;
+- `max` is used without human/scale approval;
+- profile is used to bypass secrets/path/sandbox/write policy;
+- compute artifacts contain raw body/prompt/output/content/diff/patch text;
+- telemetry or validation evidence is missing.
+
+## ProjectDNA mapping
+
+ProjectDNA should use compute profile as stage selection metadata:
+
+```text
+low    → scan + scan validation
+medium → scan + validation + capsules + sample spec + one query
+high   → medium + quarantine sample + sample validation + benchmark + oracle
+xhigh  → high + specialist lanes + richer query suite + adversarial review
+max    → xhigh + multi-reference/symbol/callgraph/promotion packet gates
+```
+
+Reference projects remain read-only, generated sample output remains quarantine/proposal-only, and external knowledge-backend import/sync/embed/write remains disabled unless explicitly approved.
+
+## Final response shape
+
+```text
+<result>effective profile/caps or implemented surface</result>
+<evidence>artifact paths and validation commands</evidence>
+<risks_blockers>remaining gaps/no-ship risks</risks_blockers>
+<compliance>profile did not bypass safety/budget/oracle gates</compliance>
+```

package/.pi/skills/zob-coms-safety/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: zob-coms-safety
+description: Use when reviewing or modifying ZOB communication, ledgers, Mission Control coms, or live transport safety gates.
+---
+# ZOB Coms Safety Skill
+
+## Safety invariants
+
+ZOB coms live transport may be transient, but ZOB audit must stay metadata-only.
+
+## MUST DO
+
+- Preserve `.pi/coms/messages.jsonl` and `.pi/coms/status.jsonl` as canonical hash-only ledgers.
+- Keep `bodyStored=false` for persisted coms records.
+- Use `taskHash`, `outputHash`, `artifactRefs`, `sessionHash`, and `endpointHash` instead of raw content.
+- Validate topology before any live or ledger send.
+- Keep Orchestrator -> Lead, Lead -> Worker, Worker -> Lead as the normal topology for direct role-to-role messages.
+- Allow Shared Goal Room messages only when they are parent-visible, typed, metadata/hash-only, and not hidden worker-to-worker free chat.
+- Treat governed requests (`DELEGATION_REQUEST.v1`, `ORACLE_REQUEST.v1`, `CONTEXT_REQUEST.v1`, `OWNER_CHANGE_REQUEST.v1`) as proposals only: parent/governor decides; extraction must not dispatch, mutate TODO state, apply owner changes, or store raw bodies.
+- Treat stale/offline as blockers, not completion evidence.
+- Keep Mission Control commands proposal-only and parent-owned.
+- Run body-free checks before claiming PASS.
+
+## MUST NOT
+
+- No raw `body`, `task`, `prompt`, `output`, `content`, `message`, `text`, `rationale`, `diff`, or `patch` keys in persisted ZOB ledgers or Mission Control artifacts.
+- No hidden worker-to-worker free chat; use typed parent-visible Goal Room messages instead.
+- No direct worker writes from Mission Control.
+- No network transport without bearer token/locality/TLS policy.
+- No silent fallback from required live delivery to append-only success.
+- No token/secret logging.
+
+## Goal Room and owner-pool safety
+
+For parallel owner micro-worker pools:
+
+- Goal Room is canonical for parent-visible coordination, decisions, owner requests, and evidence refs.
+- ZPeer is transient/live assist only; use it for immediate local questions, then summarize decisions as typed Goal Room metadata when they affect scope, ownership, or merge readiness.
+- Enforce read-across/write-by-owner: workers may read sibling outputs and owner summaries, but only the assigned owner writes its owned paths/leaf. Non-owners send `OWNER_CHANGE_REQUEST.v1`/governed request metadata and wait for owner/parent decision.
+- For `--no-extensions` children, use final-output `OWNER_CHANGE_REQUEST.v1` blocks with `requested_by`, `owner_worker`, `requested_paths`, `body_hash`, `change_hash`, `reason_hash`, optional `validation_plan_hash`, safe refs, and `FINAL_MARKER: OWNER_CHANGE_REQUEST_END`; parent extraction appends Goal Room metadata only.
+- Owner decisions are parent-visible and typed: approve, deny, defer, split, or escalate-to-parent/oracle. Approval is not an apply/merge.
+- Peer writes, hidden free chat, stale/offline success, direct main-workspace writes, missing validation, or missing oracle on risky merge readiness are no-ship blockers.
+
+## No-ship triggers
+
+No-ship if:
+- `.pi/coms` contains raw prompt/output/body-like fields;
+- live send succeeds while receiver is absent/stale/offline;
+- await treats timeout/stale/offline as success;
+- hidden worker-to-worker free chat works outside a typed parent-visible Goal Room;
+- a non-owner writes owned paths instead of sending an owner request;
+- a worker applies or merges directly into the main workspace;
+- network starts without explicit auth/locality policy;
+- `zob_coms_readiness` fails.

package/.pi/skills/zob-coms-v2-live/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: zob-coms-v2-live
+description: Use when an active ZOB handoff, live peer question, required-local coms delivery, or orchestration message is needed.
+---
+# ZOB Coms v2 Live Skill
+
+## When to use
+
+Use this skill when:
+- sending active handoffs between ZOB roles;
+- awaiting a live peer response;
+- diagnosing live peer presence, stale, or offline state;
+- working on `zob_coms` v2 runtime, registry, heartbeat, local transport, or response capture.
+
+## MUST DO
+
+- Use the canonical `zob_coms_*` tools; do not invent a parallel API.
+- Treat `zob_coms_send` as live-first when policy mode is `required_local` or `required_network`.
+- Include `transientBody` only for live transport delivery; it must never be stored in `.pi/coms`.
+- Use `taskHash`, `outputHash`, and `artifactRefs` for durable evidence.
+- Treat missing ACK, stale peer, offline peer, timeout, or transport error as blocker evidence.
+- For parallel owner pools, treat Goal Room as canonical for owner requests/decisions; ZPeer is optional transient live assist only.
+- For children launched without harness extensions, owner-change coordination is via final-output `OWNER_CHANGE_REQUEST.v1` blocks extracted by the parent, not direct child Goal Room/ZPeer writes.
+- When a live answer changes ownership, scope, conflict, or merge readiness, mirror only typed hash/body-free metadata to Goal Room.
+- Let the runtime capture normal inbound responses when handling live prompts.
+- Prefer `zob_coms_get` / `zob_coms_await` with the `msgId` returned by your own send.
+
+## MUST NOT
+
+- Do not store raw prompt/task/output/body/content/text/rationale/diff/patch in `.pi/coms`.
+- Do not use `zob_coms_send` to create worker-to-worker free chat.
+- Do not use ZPeer to bypass parent-owned owner arbitration, TODO split, sandbox, merge, or oracle gates.
+- Do not mark `queued`, `planned`, stale, or offline as completion.
+- Do not create ping-pong loops; answer the inbound live prompt normally.
+- Do not bypass topology guards.
+- Do not enable network transport without explicit auth/locality policy.
+
+## Expected pattern
+
+```text
+zob_coms_send
+  -> topology guard
+  -> live peer lookup/heartbeat
+  -> live ACK or blocker
+  -> hash-only ledger mirror
+  -> await response or terminal error
+```

package/.pi/skills/zob-delegation-routing/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: zob-delegation-routing
+description: Use before delegating to ZOB specialist agents, choosing delegate_agent/delegate_task, selecting an agent, or deciding whether to set output_contract.
+---
+# ZOB Delegation Routing Skill
+
+## When to use
+
+Use this skill whenever you are about to call `delegate_agent` or `delegate_task`, especially the first delegation in a turn or when agent/contract routing is uncertain.
+
+## Mandatory routing check
+
+1. If you are not certain which agent or output contract to use, call `zob_delegation_catalog` first.
+2. Choose the agent by the deliverable you need.
+3. Model routing is advisory unless current runtime availability/authentication is proven: normally omit `delegate_task.model` and `delegate_agent.model` so the child uses the parent/session default. A configured, desired, catalogued, or class-mapped model is not evidence that the provider is currently available/authenticated. Set an explicit `model` override only when you have current runtime proof that the concrete model/provider is usable for this session, or when the user explicitly accepts that risk. If proof is missing, omit `model`; never let a catalog preference create a launch-blocking unavailable-provider override. Never downgrade oracle/security work to a weak or unverified default.
+4. Normally omit `delegate_task.output_contract`; the harness infers the correct contract from the selected agent.
+5. Normally omit `delegate_task.required_tools`; the harness infers the selected agent's declared tools.
+6. Never invent output contract IDs or add tools not shown for the chosen agent in `zob_delegation_catalog`.
+7. Treat preflight as a safety net, not as the first source of routing information.
+
+## Common agent routing
+
+- Need read-only facts, file mapping, gaps, or context: use `explore` (`explore.v1`).
+- Need an implementation plan, TDD ladder, stop conditions, or handoff: use `planner` (`plan.v1`).
+- Need bounded source edits: use `implementer` (`implement.v1`) with scoped `allowed_paths`.
+- Need skeptical review, audit verdict, `PASS/WARN/FAIL`, blockers, or `no_ship`: use `oracle` (`oracle.v1`).
+- Need verification/reproduction evidence: use `qa` (`qa.v1`).
+- Need sourced reusable research/context: use `librarian` (`research.v1`).
+- Need spec from a fuzzy request: use `specifier` (`spec.v1`).
+- Need clarification before planning: use `clarifier` (`clarification.v1`).
+- Need factory design: use `factory` (`factory.v1`).
+
+## Output contract rules
+
+- `delegate_agent` always infers the output contract from the agent.
+- `delegate_task` infers the output contract from the agent when `output_contract` is omitted.
+- Set `output_contract` only for an intentional, exact override with a known valid ID.
+- There is no default `audit.v1`; audit/review work should usually route to `oracle` with `oracle.v1`.
+- There is no `implementation_report.v1`; implementation reports use `implement.v1`.
+
+## Tool routing rules
+
+- **Write-enabled `delegate_task` hard rule:** when effective tools include `edit` or `write` (either inferred from the agent or supplied via `required_tools`), always set top-level `original_user_ask` to the original human request. Putting the user ask inside `context` or the task text is not enough for the strict write preflight gate.
+- `delegate_task` structured JSON fields should use canonical snake_case. Safe aliases are normalized only when non-conflicting; conflicting canonical/alias values are blocked with no child launched.
+
+| Canonical `delegate_task` field | Accepted safe aliases |
+| --- | --- |
+| `expected_outcome` | `expectedOutcome` |
+| `required_tools` | `requiredTools` |
+| `must_do` | `mustDo` |
+| `must_not_do` | `mustNotDo`, `must_not`, `mustNot` |
+| `original_user_ask` | `originalUserAsk` |
+| `allowed_paths` | `allowedPaths` |
+| `forbidden_paths` | `forbiddenPaths` |
+| `output_contract` | `outputContract` |
+| `run_in_background` | `runInBackground` |
+| `child_goal` | `childGoal` |
+| `load_skills` | `loadSkills` (still reserved/non-empty values are gated) |
+
+- `delegate_task` infers `required_tools` from the selected agent when omitted.
+- Omit `delegate_task.model`/`delegate_agent.model` by default. Explicit model overrides are exceptional and require current availability/auth proof for the concrete provider/model; desired/configured/catalogued models are preferences only, not availability. Fallback is to omit `model` and use the parent/session default.
+- Set `required_tools` only to narrow the agent's tools, not to add tools.
+- Do not request `bash` for `planner`; planner is read-only with `read`, `grep`, `find`, and `ls`.
+- If a task truly needs `bash`, choose an agent whose catalog entry allows `bash`, or keep the work in the parent if appropriate.
+
+## Safety reminders
+
+- For write/edit tools, set top-level `original_user_ask`, non-empty repo-relative-only `allowed_paths`, and safe `forbidden_paths`.
+- `allowed_paths` are capability grants and must never be absolute, home-relative (`~`), traversal (`..`), broad roots (`.`), or contain NUL. If external context is needed, first create/cite a repo-local snapshot or `context_ref` under `reports/...` and pass that repo-relative ref.
+- `forbidden_paths` are deny-only patterns; they may be repo-local, absolute, or home-relative when specific and safe, but broad roots remain rejected.
+- Preserve the six-part contract: TASK / EXPECTED OUTCOME / REQUIRED TOOLS / MUST DO / MUST NOT DO / CONTEXT.
+- Do not ask child agents to mark parent goals or TODOs complete directly; children return evidence/claims for parent review.
+- For TODO-linked delegation, refresh with `get_goal_todos` first and use `child_goal.todo_id=<canonical-active-todo-id>` only when that id is freshly verified. If only the visible path is known, set `child_goal.todo_path=<visible-todo-path>`; do not fabricate shorthand ids. The parent runtime can resolve unique active paths/shorthands to canonical ids, and blocks stale refs with active-id hints.
+- Safe auto-open/delegation is for runtime-delegatable TODOs (`planned`, `ready`, `in_progress`, `needs_review`) only when no active child/run owns the leaf. Recover delegated/recovery TODOs only when no active child/run owns the leaf; otherwise block/review instead of redelegating.
+- Split-before-parallel: no same-leaf parallel write workers. If a TODO needs multiple agents or is too broad, parent splits it into subtodos first and dispatches one bounded owner per leaf.
+- For parallel owner micro-worker pools, parents may use `zob_worker_pool_plan`/`zob_worker_pool_status` to record body-free assignment metadata before launch, but those tools do not dispatch children. Each actual child launch still goes through parent-owned `delegate_task`/`delegate_agent` with explicit owned/write paths, optional read-across refs, repo-relative `allowed_paths`, safe `forbidden_paths`, and TODO linkage.
+- Read-across permits inspection and evidence synthesis only; it never grants write permission.
+- Non-owner changes require a typed parent-visible owner request (`zob_worker_pool_owner_request`, `OWNER_CHANGE_REQUEST.v1`, or governed request) with requested path, reason/evidence hashes or refs, risk, and validation plan. Children without harness extensions may emit an `OWNER_CHANGE_REQUEST.v1` final-output block for parent-side `zob_governed_request_extract`; they must not call Goal Room/ZPeer directly. The owner/parent may approve, deny, defer, split, or escalate via `zob_worker_pool_owner_decision`/Goal Room; approval is not merge/apply and does not launch children.
+- Goal Room is the canonical coordination surface for owner requests/decisions. ZPeer may be used for transient local clarification only and must not become hidden worker-to-worker free chat.
+- Children must not dispatch children, mutate parent TODOs, apply split decisions, or write outside their owned paths.
+- For TODO-linked high/xhigh/max work, children that discover the assigned TODO is too broad or needs deeper XDEF decomposition should return `TODO_SPLIT_REQUEST.v1` or a metadata-only split request; the parent validates and applies `split_goal_todo`.
+- `delegate_task(run_in_background=true)` is active-session only: it returns a run id immediately, can be inspected with `get_delegation_run`, and can be waited on with bounded `await_delegation_run`; it does not start an always-on daemon.

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

@@ -0,0 +1,28 @@
+---
+name: zob-factory
+description: Use when designing or running repeatable software factories with manifests, checkpoints, validators, sentinels, smoke/pilot/batch gates.
+---
+# ZOB Factory Skill
+
+## When to use
+
+Use when the task is repeated, batchable, or should become a reusable system rather than a one-off feature.
+
+## Workflow
+
+1. Spec first: define input manifest, outputs, validators, and no-ship rules.
+2. Factory design: deterministic scaffolding first, LLM enrichment second.
+3. Smoke: one item only.
+4. Oracle: require validation evidence before pilot/batch.
+5. Pilot: 10 items max with bounded concurrency.
+6. Batch: only after pilot sentinel and oracle gate.
+
+## Required artifacts
+
+- `manifest.json`
+- `agentic-plan.json`
+- `checkpoints/`
+- `outputs/`
+- `validation.json`
+- phase sentinel (`SMOKE_PASSED.sentinel`, `PILOT_PASSED.sentinel`, or `BATCH_PASSED.sentinel`)
+- `DONE.sentinel` only after validation passes