zob-harness 0.1.0

package/.pi/skills/zob-owner-pool-launcher/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: zob-owner-pool-launcher
+description: Use when the owner gives a plain-language intention and wants the assistant to actively launch and operate a supervised ZOB parallel owner micro-worker pool workflow instead of only generating a prompt.
+---
+# ZOB Owner Pool Launcher Skill
+
+## Purpose
+
+Use this skill when the owner writes a natural-language request such as:
+
+```text
+/skill:zob-owner-pool-launcher <user intent>
+```
+
+The assistant must turn the owner intent into one bounded supervised owner micro-worker pool run, then operate the workflow using existing ZOB coordination and delegation surfaces. This is an operational launcher, not a prompt generator.
+
+The launcher may use the prompt-writing logic from `zob-owner-pool-drill-writer` as a formatting aid, but it must actively classify scope, size the pool, create/inspect Goal TODOs when appropriate, create/read worker-pool metadata, dispatch actual workers parent-owned through `delegate_task`/`delegate_agent`, monitor runs, synthesize evidence, validate, and request oracle review when needed.
+
+## Non-negotiable invariants
+
+- One bounded slice only. If the intent is broad, narrow it or ask the owner to choose the first slice.
+- Parent-owned dispatch only. Worker-pool metadata does not launch workers.
+- No child-spawns-child. Children may propose splits or owner requests; only the parent applies them.
+- Goal Room is the canonical coordination record for assignments, owner requests, decisions, blockers, and evidence refs.
+- ZPeer/live chat is transient only. Summarize any decision-affecting live clarification as typed Goal Room metadata.
+- No hidden worker-to-worker free chat.
+- Persist no raw bodies in coordination metadata, ledgers, Mission Control artifacts, compute artifacts, or worker-pool records. Use hashes, refs, summaries, and paths.
+- Enforce read-across/write-by-owner: workers may read cited sibling outputs, but only the named owner writes its owned paths.
+- Non-owner changes require a parent-visible `OWNER_CHANGE_REQUEST.v1` or governed request and a parent/owner decision. Approval is not apply/merge.
+- Do not let children directly mutate parent TODOs or mark parent goals complete. Children return evidence/claims; the parent accepts or rejects after review.
+- Reports-only is the default mode.
+- Source-write-gated work requires explicit paths, sandbox/workspace claims, merge queue, rollback metadata, validation, and oracle/human gates. Never auto-apply.
+- Never commit, push, tag, stage, force push, or alter git state from this skill.
+- Never read/write secrets or forbidden paths such as `.env`, keys, `~/.ssh`, `~/.aws`, `node_modules`, `dist`, `build`, or `.git`.
+- Never run destructive commands unless the owner gives explicit approval outside this skill's default workflow.
+- Never count stale/offline peers, append-only logs, or non-live refs as required delivery success.
+- Do not imply fully autonomous production writes, unlimited spawning, or always-on background daemons.
+
+## Intake from the owner prompt
+
+Use the user's plain prompt directly. Do not require a preformatted contract unless safety-critical details are missing.
+
+Extract:
+
+1. `OBJECTIVE`: one sentence.
+2. `SCOPE`: the smallest bounded slice that can produce evidence.
+3. `MODE`: `reports-only` by default, or `source-write-gated` only when explicitly requested.
+4. `READ_PATHS`: explicit source/context paths; ask if absent and required for safety.
+5. `OWNED_PATHS`: per-worker output or sandbox paths; must be repo-relative and non-overlapping for writes.
+6. `FORBIDDEN_PATHS`: include secrets, generated/vendor/build paths, and owner-specified denies.
+7. `VALIDATION`: narrow commands or evidence checks.
+8. `OWNER_DECISIONS_NEEDED`: missing paths, scale approval, source-write permission, merge/apply decisions.
+
+Ask a clarification question instead of launching when the request lacks safety boundaries for source writes, requires secrets/destructive actions, is too broad for one slice, or would require hidden chat, child direct dispatch, direct TODO mutation, auto-apply, or unbounded worker count.
+
+## Scale and compute policy
+
+Choose the smallest useful pool. Worker counts are caps, not targets.
+
+| Workers | Use when | Gates |
+| --- | --- | --- |
+| 2 | Simple compare/review, mapper + oracle/planner | Default for small reports-only tasks |
+| 3 | Normal owner pool: mapper, implementer/planner, oracle | Default for most bounded tasks |
+| 5 | Multiple independent lanes or owned paths plus synthesis/oracle | Requires clear decomposition and non-overlapping write grants |
+| 10 | High-complexity, high-profile workflow with separable lanes | Requires explicit owner consent, compute/budget gates, TODO split, validation/oracle plan |
+| 20 | Exceptional max-scale supervised drill | Requires explicit human approval, strict compute/budget gates, oracle plan, and should normally be plan-only or read-only/report-only |
+
+Rules:
+
+- Default to 2-5 workers.
+- Do not silently select 10 or 20.
+- Use compute preview/resolve when the owner requests auto/high/xhigh/max scale or when 10/20 workers are considered.
+- `max` or 20-worker scale is approval-gated and never bypasses safety, path, sandbox, budget, validation, or oracle gates.
+- If planned work exceeds caps, split into a smaller first run and return a follow-up proposal.
+
+## Safe modes
+
+### Reports-only default
+
+Use for exploration, audits, plans, specs, proposals, prompt/workflow design, and oracle review.
+
+- Workers write only report/proposal artifacts under explicit output paths.
+- Source paths are read-only.
+- Validation may be structural checks, targeted commands, or evidence review.
+- Final output includes exact next owner decisions.
+
+### Source-write-gated
+
+Use only when the owner explicitly asks for code/source changes and provides or approves exact paths.
+
+Required gates:
+
+1. Explicit allowed read/write paths and forbidden paths.
+2. Workspace claim/lease metadata for intended owned write paths.
+3. Sandbox/temp/quarantine workspace for worker edits; no direct main-workspace apply.
+4. Merge queue or diff-candidate metadata owned by the parent.
+5. Changed paths, diff hash, rollback notes, and validation logs.
+6. Oracle review for risky or merge-ready changes.
+7. Human/owner approval before any apply. Approval only makes a candidate eligible; it does not auto-apply.
+
+If any gate is missing, downgrade to reports-only or stop with a blocker.
+
+## Operational runbook
+
+### 1. Load consistency context
+
+When launching a pool, apply these skills as relevant:
+
+- `zob-harness` for harness/orchestrator rules.
+- `zob-delegation-routing` before child dispatch.
+- `zob-goal-todo-tree` when using active goals/TODO-linked work.
+- `zob-compute-profile` when auto/high/xhigh/max or 10/20 worker scale is considered.
+- `zob-coms-safety` for Goal Room, governed requests, no raw-body persistence, and stale/live safety.
+- `zob-sandbox` for source-write-gated work.
+
+### 2. Scope lock
+
+Restate the six-part contract for the pool:
+
+```text
+1. TASK: [bounded objective]
+2. EXPECTED OUTCOME: [observable deliverable/evidence]
+3. REQUIRED TOOLS: [allowed tools only]
+4. MUST DO: [positive constraints, paths, validation, parent-owned coordination]
+5. MUST NOT DO: [hard stops, forbidden paths, no auto-apply/no commits]
+6. CONTEXT: [original owner prompt, assumptions, mode, worker count, TODO/goal refs]
+```
+
+If the scope or write boundaries are unsafe, stop and ask the owner for the missing decision.
+
+### 3. Goal/TODO setup
+
+- If an active goal exists and the work is multi-step, inspect current TODOs first.
+- In `auto` goal mode, create a bounded TODO plan for long/delegated work; in `manual` mode, ask before creating TODOs.
+- Split before parallel writable work: no same-leaf parallel write workers.
+- Use fresh canonical TODO IDs from `get_goal_todos` when linking children; if only a visible path is known, pass `child_goal.todo_path` and let the parent runtime resolve it.
+- Children must return claims; the parent accepts/rejects only after evidence and, when needed, oracle review.
+
+### 4. Worker-pool metadata
+
+Create/read worker-pool metadata with existing ZOB worker-pool tools when available.
+
+Metadata must be body-free and include:
+
+- pool id / goal id / TODO refs;
+- worker roles;
+- owned paths and read paths;
+- output paths;
+- write mode;
+- validation commands;
+- owner request/decision refs;
+- evidence refs/hashes;
+- no-ship blockers.
+
+Remember: worker-pool metadata is coordination only and does not dispatch children, mutate TODOs, or apply changes.
+
+### 5. Worker role templates
+
+Prefer 3 workers unless the scale policy justifies otherwise:
+
+- Mapper: inventory paths, evidence, dependencies, risks, and missing inputs.
+- Planner/Implementer: produce the report, proposal, sandbox diff candidate, or owned slice output.
+- Oracle/QA: review evidence, validation, safety, no-ship status, and completion readiness.
+
+For 5 workers, split into independent lanes such as mapper, lane A, lane B, synthesis, oracle.
+
+For 10/20 workers, require a named lane map, each with a bounded owner, explicit allowed paths, expected output, validation evidence, and no child dispatch.
+
+### 6. Parent-owned dispatch
+
+Dispatch actual work only through parent-owned `delegate_task` or `delegate_agent`.
+
+Before first delegation, use the delegation catalog/routing flow when agent choice or output contract is uncertain. Normally omit child `output_contract`, `required_tools`, and `model` unless a narrower verified choice is required.
+
+Each child contract must include:
+
+- original owner ask when write/edit tools are available;
+- exact `allowed_paths` and `forbidden_paths`;
+- owned/write paths and read-across refs;
+- TODO linkage when applicable;
+- `run_in_background=true` only for active-session background runs that the parent will monitor;
+- explicit statement: no child-spawns-child, no parent TODO mutation, no commits, no auto-apply.
+
+### 7. Runtime monitoring loop
+
+While background runs are active:
+
+1. Poll/await bounded runs; do not assume daemon persistence.
+2. Inspect run status and outputs.
+3. Extract `OWNER_CHANGE_REQUEST.v1`, `TODO_SPLIT_REQUEST.v1`, or governed request blocks from child outputs with `zob_governed_request_extract` when available.
+4. Record owner decisions through Goal Room/worker-pool owner decision tools when available.
+5. Accept, reject, split, defer, or escalate requests parent-owned only.
+6. Accept/reject TODO claims only after output contract, evidence, validation, and oracle gates pass.
+7. Treat stale/offline/timeout/missing evidence as blockers, not success.
+8. Maintain a body-free metadata audit with refs/hashes, not raw child bodies.
+
+If the owner sends an in-flight change request, pause affected lanes, record the request, decide whether to narrow, split, cancel, or relaunch, and update Goal Room metadata before continuing.
+
+### 8. Synthesis and validation
+
+After child outputs return:
+
+- Synthesize worker findings into one parent-owned result.
+- Run the narrowest useful validation commands first.
+- Escalate validation only with a reason.
+- Request oracle review for source-write-gated outputs, risky claims, high/xhigh/max scale, merge readiness, or completion/no-ship decisions.
+- Do not propose root goal completion until TODO completion gates are satisfied and oracle `PASS/no_ship=false` is available when required.
+
+### 9. Completion report
+
+Return a concise final result with:
+
+```text
+gap_verdict: SUFFICIENT or GAP, with exact evidence
+worker_count: selected count and why
+worker_outputs: paths/refs and one-line summaries
+owner_requests: decisions made or pending
+validation_commands: exact commands run, or not run with reason
+results: exact outcomes
+metadata_audit: pool id, goal/TODO refs, workers, owned paths, read paths, output paths, evidence refs/hashes, no raw bodies
+no_ship: true/false with reason
+risks/blockers: unresolved risks
+compliance: parent-owned dispatch, Goal Room canonical, ZPeer transient, read-across/write-by-owner, no child-spawns-child, no auto-apply, no commits, no secrets
+```
+
+## Refusal and stop conditions
+
+Refuse or stop when:
+
+- The owner asks for secrets, credential harvesting, destructive commands, broad unbounded writes, commits, pushes, tags, or force operations.
+- Source-write is requested without explicit paths or without sandbox/oracle/human gates.
+- The owner requests hidden worker-to-worker chat, child direct dispatch, direct TODO mutation, automatic merge/apply, or unlimited agents.
+- Required live/local delivery is absent, stale, or offline and the workflow depends on it.
+- Persisted metadata would require raw prompt/output/body/diff/patch content.
+- Worker count 10/20 is requested without the required owner approval and budget/compute gates.
+
+## Minimal French usage
+
+```text
+/skill:zob-owner-pool-launcher Analyse ce workflow et lance un petit pool de workers pour me sortir un plan clair, sans modifier le code.
+```
+
+```text
+/skill:zob-owner-pool-launcher Je veux 3 workers: un qui mappe les fichiers, un qui prépare une proposition, un oracle qui vérifie. Reports-only.
+```
+
+```text
+/skill:zob-owner-pool-launcher Prépare une correction sandboxée sur ces chemins précis, avec validation et oracle, mais n'applique rien sans mon accord.
+```
+
+Tu peux aussi écrire naturellement:
+
+```text
+Lance un pool supervisé pour auditer cette partie, choisis 2 à 5 workers selon le besoin, et reviens avec les preuves.
+```
+
+For 10 or 20 workers, the owner must say it explicitly and accept the compute/budget/safety gates, for example:
+
+```text
+/skill:zob-owner-pool-launcher Je veux envisager 10 workers pour cette analyse reports-only; demande-moi les validations nécessaires avant de lancer.
+```

package/.pi/skills/zob-project-dna/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: zob-project-dna
+description: "Use when turning a trusted reference project folder into ProjectDNA: a code-first knowledge graph, neutral sample-project plan, pointer capsules, and bounded cited context packs for future ZOB agents."
+---
+# ZOB ProjectDNA Skill
+
+## Purpose
+
+ProjectDNA makes a real project usable as code-first context without treating docs as truth. It is agents-first: ZOB agents own scope, capture goals, safety gates, validation, oracle review, and promotion proposals; deterministic scripts are tools that produce evidence for agents to inspect and cite.
+
+The intended flow is:
+
+```text
+trusted reference project folder
+→ read-only safe scan
+→ deterministic code/architecture facts
+→ Developer DNA synthesis with citations
+→ neutral sample project in quarantine/sandbox
+→ pointer capsules and code knowledge graph
+→ bounded context packs for future agents
+```
+
+The real project code remains the source of truth. The generated sample, graph, and capsules are navigation layers only.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- learn from a project folder they like;
+- create a reusable code knowledge graph from a reference app;
+- generate a neutral sample project that preserves architecture/style;
+- add project-code retrieval inspired by prior wiki/retrieval V2 work;
+- speed up future coding with cited project examples;
+- query “how do we do X in my style?” across reference projects.
+
+## Required starting inputs
+
+Before any scan or generation, collect or confirm:
+
+1. `source_project_path`: absolute or repo-local path explicitly approved by the user.
+2. `source_id`: safe id for the reference project, e.g. `my-reference-app`.
+3. `allowed_paths`: bounded paths the scanner may inspect.
+4. `forbidden_patterns`: at minimum `.env`, `.env.*`, keys, credentials, `node_modules`, `dist`, `build`, coverage, `.git`.
+5. `sample_domain`: neutral domain for the generated sample, e.g. `task-tracker`.
+6. `validation_profile`: install/lint/typecheck/test/build commands or a stated “plan-only” mode.
+7. `compute_profile`: `auto`, `low`, `medium`, `high`, `xhigh`, or `max`; default `auto`.
+8. `compute_caps`: optional hard caps for agents, depth, parallelism, duration, context, budget, and oracle.
+9. `capture_mode`: execution posture: `plan_only`, `read_only_scan`, `sandbox_sample_generation`, or `runtime_query_existing_artifacts`.
+10. `semantic_capture_mode`: knowledge posture: `full_capture`, `architecture_only`, `targeted_capture`, `sample_first`, or `context_only`.
+11. `capture_goal`: concrete pattern/question to capture, e.g. architecture, queues, tests, config, or service boundaries.
+12. `user_note`: optional operator intent/style note; guidance only, never citation evidence.
+13. `promotion_policy`: normally `proposal_only` until oracle and human approval.
+
+If any of these are missing for a real project scan, ask for clarification or produce a plan-only manifest instead of scanning.
+
+## Native ZOB surfaces
+
+- Plan doc: `docs/ZOB_PROJECT_DNA_CODE_KNOWLEDGE_GRAPH_PLAN.md`
+- Factory scaffold: `.pi/factories/project-dna/factory.json`
+- Prompt template: `.pi/prompts/project-dna.md`
+- Scaffold validator: `npm run validate:project-dna`
+- Compute preview smoke: `npm run preview:compute-profile:project-dna-smoke`
+- Compute preview validator: `npm run validate:compute-profile:project-dna-smoke`
+- Read-only scanner smoke: `npm run smoke:project-dna-scan`
+- Scan artifact validator: `npm run validate:project-dna-scan:smoke`
+- Pointer capsule builder smoke: `npm run build:project-dna-capsules:smoke`
+- Neutral sample-spec smoke: `npm run build:project-dna-sample-spec:smoke`
+- Quarantine sample generation smoke: `npm run generate:project-dna-sample:smoke`
+- Quarantine sample validation smoke: `npm run validate:project-dna-sample:smoke`
+- Metadata-only agentic workflow planner smoke: `npm run plan:project-dna-workflow:smoke`
+- Agentic workflow plan validator: `npm run validate:project-dna-workflow:smoke`
+- Metadata-only context query smoke: `npm run query:project-dna:smoke`
+- Runtime readiness/plan/query tools: `zob_project_dna_readiness`, `zob_project_dna_plan_workflow`, `zob_project_dna_query`
+- Runtime P5 proposal-only tools: `zob_project_dna_federated_query`, `zob_project_dna_writeback_proposal`
+- Slash/operator surface: `/project-dna`
+- Deterministic retrieval/sample benchmark: `npm run bench:project-dna:smoke`
+- Structural oracle smoke review: `npm run oracle:project-dna:smoke`
+- Context foundation: existing `zob_context_*` tools for scope/citation/writeback gates.
+
+Current status: ProjectDNA is scaffolded as a safe skill/factory workflow and now includes deterministic read-only scanner, compute-profile preview scripts, validated smoke artifacts, native runtime readiness/query/federated-query tools, `/project-dna`, and hash-only proposal writeback. **No external knowledge backend import**, sync, embed, or write is performed by default, and no autonomous external-project scanning happens without parent-owned allowed paths. Scripts are deterministic tools for agents; they are not a replacement for parent-owned scope, safety, validation, oracle, and promotion decisions.
+
+## 5/5 agents-first contract
+
+A ProjectDNA result is 5/5 only when agents, not scripts, own scope and acceptance:
+
+1. Safety Preflight confirms approved paths, forbidden patterns, source read-only posture, quarantine/report outputs, and proposal-only promotion.
+2. Repo Scout and deterministic scanner produce cited facts; scanner scripts are microscopes, not the control plane.
+3. Ontology Steward maps facts into controlled pattern concepts such as `project_dna.agentic_control_plane`, `project_dna.query_steward_rewrite`, and `project_dna.sample_quarantine_pi_like`.
+4. Query Steward rewrites transient user questions into controlled intent/golden-case expectations without persisting raw query text.
+5. Pattern Miner, Symbol Range Curator, and Test Linker connect source patterns to precise ranges, tests, examples, docs, and gaps.
+6. Sample Architect creates only neutral Pi-like quarantine samples with extension/tool/agent/skill/test shape and `source_files_copied=false`.
+7. Golden Evaluator runs golden cases; every case must return expected citations/files/patterns and no-write safety flags.
+8. ProjectDNA Oracle can PASS only when ontology, golden cases, query steward report, benchmark, sample validation, and source-safe gates are present.
+
+5/5 does **not** mean durable promotion. It remains reports-local/proposal-only until separate oracle and human approval.
+
+## Safe workflow
+
+### 1. Intake and scope
+
+Produce an explicit scope block:
+
+```text
+source_project_path: ...
+source_id: ...
+allowed_paths: ...
+forbidden_patterns: ...
+sample_domain: ...
+execution_mode: plan_only | read_only_scan | sandbox_sample_generation
+capture_mode: plan_only | read_only_scan | sandbox_sample_generation | runtime_query_existing_artifacts
+semantic_capture_mode: full_capture | architecture_only | targeted_capture | sample_first | context_only
+capture_goal: bounded pattern/question to capture
+user_note: optional operator guidance, not evidence
+compute_profile: auto | low | medium | high | xhigh | max
+compute_caps: optional hard caps
+promotion_policy: proposal_only
+```
+
+### 2. Preflight
+
+Must verify:
+
+- user-approved path is bounded;
+- source project is not modified;
+- forbidden paths are excluded;
+- output path is a run directory or sandbox/quarantine;
+- no external knowledge-backend import, sync, embed, or write is implied unless explicitly approved.
+
+### 3. Compute preview before scan when profile is auto
+
+For `compute_profile=auto`, write or inspect metadata-only compute artifacts before choosing workflow depth:
+
+```text
+compute-preview.json
+compute-profile-resolution.json
+```
+
+ProjectDNA profile mapping:
+
+```text
+auto   → metadata-only preview/resolve, then apply the resolved low/medium/high/xhigh/max row
+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, with strict human/budget/oracle approval
+```
+
+Compute profile must not bypass ProjectDNA safety: source projects remain read-only, external knowledge-backend writes remain disabled, quarantine/proposal-only outputs remain enforced, and child dispatch stays parent-owned.
+
+### 3a. Capture mode policy
+
+Use `capture_mode` to pick posture before any tool/script run:
+
+- `plan_only`: produce a manifest/plan from approved docs, `capture_goal`, and `user_note`; do not scan source code.
+- `read_only_scan`: inspect only explicit `allowed_paths`, with forbidden patterns skipped and cited.
+- `sandbox_sample_generation`: use existing facts/specs to write only under approved quarantine/sandbox paths.
+- `runtime_query_existing_artifacts`: return bounded cited context from existing scan artifacts; do not start a new external-project scan.
+
+Use `semantic_capture_mode` to pick knowledge depth:
+
+- `full_capture`: small/medium repo, reusable reference across major domains.
+- `architecture_only`: large repo or user asks to preserve architecture/scaffold only.
+- `targeted_capture`: mine only named domains/features from `capture_goal` or `user_note`.
+- `sample_first`: prioritize a neutral working sample from cited architecture facts.
+- `context_only`: return bounded pointers/context packs without sample generation.
+
+`capture_goal` drives which artifacts/capsules/query cases are in scope. `user_note` may explain intent, constraints, or style preferences, but it is never a citation and must not override scanner facts. For huge repos, default to `architecture_only` or `targeted_capture` unless the user explicitly approves deeper compute.
+
+### 4. Deterministic scan first
+
+Scanner facts should precede LLM synthesis:
+
+```text
+project-fingerprint.json
+dependency-map.json
+file-map.json
+symbol-map.json
+import-graph.json
+route-map.json
+queue-map.json
+config-map.json
+test-map.json
+architecture-map.json
+```
+
+Each fact must cite safe repo-relative or source-relative paths and line ranges when available.
+
+### 5. Developer DNA synthesis
+
+LLM/Ollama may summarize patterns, but only from deterministic facts and citations.
+
+Allowed synthesis outputs:
+
+```text
+developer-dna.json
+code-knowledge-graph.json
+capsules/*.md
+context-pack-smoke.json
+```
+
+Forbidden synthesis behavior:
+
+- invent architecture not supported by scan facts;
+- answer from generic framework docs instead of project evidence;
+- store raw proprietary bodies unnecessarily;
+- copy product-specific logic into the sample.
+
+### 6. Sample generation
+
+Generate only in quarantine/sandbox first:
+
+```text
+reports/factory-runs/<run_id>/quarantine/project-dna-sample/
+```
+
+Promote only if:
+
+- validation commands pass;
+- similarity/leakage checks pass;
+- citations are valid;
+- oracle returns PASS/no_ship=false;
+- human approval is present if writing to durable knowledge/sample locations.
+
+### 7. Runtime context packs
+
+When another ZOB task needs project style context, the Context Steward should return a bounded context pack with:
+
+- answer summary;
+- files to read first;
+- source citations;
+- sample citations if available;
+- observed rules;
+- explicit gaps;
+- token budget;
+- no raw secrets or full-project dumps.
+
+## No-ship rules
+
+Block or stop if any occur:
+
+- `.env`, key, credential, SSH/AWS/cloud secret, or private raw data is read or included;
+- source project is modified;
+- output writes outside the approved run/sandbox/quarantine path;
+- external knowledge-backend import/sync/embed/write is attempted without explicit approval;
+- sample project fails build/test/typecheck where required;
+- generated sample copies product logic too closely;
+- citations or line ranges are missing/invalid;
+- context pack loads the entire project rather than bounded cited excerpts;
+- oracle reports `no_ship=true`.
+
+## Delegation contract template
+
+Use this six-part contract for ProjectDNA child work:
+
+```text
+1. TASK: [scan/synthesize/validate one bounded ProjectDNA artifact]
+2. EXPECTED OUTCOME: [specific artifact or verdict with citations]
+3. REQUIRED TOOLS: read, grep, find, ls only unless sandbox/write is explicitly approved
+4. MUST DO: cite files/line ranges; obey allowed_paths; report skipped forbidden paths
+5. MUST NOT DO: no secrets; no source writes; no external knowledge-backend import/sync/embed/write; no broad corpus load
+6. CONTEXT: source_id, allowed_paths, forbidden_patterns, target artifact, downstream validator/oracle use
+```
+
+## Final response shape
+
+End ProjectDNA work with:
+
+```text
+<result>what was created or validated</result>
+<evidence>file paths, run ids, validation commands</evidence>
+<risks_blockers>remaining gaps/no-ship risks</risks_blockers>
+<compliance>read-only/source-safe/quarantine/proposal-only statement</compliance>
+<deliverable_delivered>yes|no</deliverable_delivered>
+```

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

@@ -0,0 +1,29 @@
+---
+name: zob-sandbox
+description: Use when enabling write-capable agents/factories safely through temp workspaces, diff gates, rollback metadata, and oracle review.
+---
+# ZOB Sandbox Skill
+
+## Write safety ladder
+
+1. Claim intended workspace paths with metadata-only leases before parallel write work.
+2. Work in temp copy/worktree.
+3. Enforce allowed/forbidden paths.
+4. Run minimal validation.
+5. Produce diff hash and changed paths.
+6. Oracle reviews diff.
+7. Apply only after policy/human approval.
+8. Preserve rollback metadata.
+
+## Non-negotiables
+
+- No direct autonomous writes to main workspace.
+- No auto-apply by default.
+- No generated/vendor/secrets paths.
+- Workspace claims/leases are conflict-detection metadata only; they do not grant write permission, apply changes, or bypass parent/oracle gates.
+- In parallel owner pools, a lease/claim identifies the intended owner paths. Plans must keep `write_paths` within `owned_paths`; a worker's own active listed write claim may cover its write intent, while other overlapping active claims remain conflicts. Other workers may read across cited refs but must not edit those paths.
+- Read-across is read-only and does not grant write permission; if read-across overlaps write paths, require a hash-only justification and keep write-by-owner unchanged.
+- Cross-owner edits require a typed owner request with path, reason, risk, evidence, and validation plan; owner requests must name an assignment owner and requested paths must be covered by that owner's owned/write paths when a pool plan exists. Parent/owner decisions are metadata only and never auto-apply.
+- Merge queue candidates/decisions are parent-owned metadata only; approvals mean manual-apply eligible, never auto-applied.
+- Missing isolated validation, diff hash, conflict check, rollback metadata, or oracle/human approval for risky merges is no-ship.
+- Rollback metadata required before scaling writes.

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

@@ -0,0 +1,25 @@
+---
+name: zob-spec
+description: Use when turning product, feature, or factory ideas into testable ZOB specs and clarification gates before planning.
+---
+# ZOB Spec Skill
+
+## When to use
+
+Use for:
+- Product/feature-first asks.
+- Ambiguous requirements needing acceptance criteria.
+- Factory ideas that need a stable input/output contract.
+- Any request where planning would be unsafe without a spec.
+
+## Workflow
+
+1. Run `specifier` with `output_contract: spec.v1`.
+2. If acceptance criteria are missing, contradictory, or not testable, run `clarifier` with `output_contract: clarification.v1`.
+3. Do not proceed to planning when `clarity_score < 70` or `verdict: BLOCKED`.
+4. Preserve original user ask and list assumptions.
+
+## Safety
+
+- Read-only only: `read`, `grep`, `find`, `ls`.
+- No implementation, writes, browser/cloud actions, or secrets.

package/.pi/skills/zob-split-refactor/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: zob-split-refactor
+description: Use when splitting a monolithic ZOB/Pi TypeScript extension into modules without behavior changes. Enforces split-only moves, export compatibility, local AGENTS.md context, and smoke validation.
+---
+# ZOB Split Refactor
+
+## Use when
+
+- Splitting `.pi/extensions/zob-harness/index.ts` or another monolithic ZOB/Pi TypeScript extension.
+- Moving one bounded block into a sidecar module.
+- Verifying exports/imports/circularity after a split-only slice.
+
+## Rules
+
+- Move code; do not rewrite logic.
+- Preserve public exports from `index.ts`.
+- Keep the Pi entrypoint and `default export` stable until an explicit final barrel switch is approved.
+- Use NodeNext relative imports with `.js` suffix, e.g. `./utils/paths.js`.
+- Never import `index.ts` from `src/**`.
+- Do not rename tools, commands, event handlers, sentinels, artifacts, schemas, prompt strings, error messages, or output contract ids.
+- Do not change array order, defaults, validations, sync/async behavior, `Date.now()`, `new Date()`, or `Math.random()` semantics.
+- Read the nearest `AGENTS.md` before editing a folder.
+
+## Slice workflow
+
+1. Read `docs/ZOB_HARNESS_INDEX_REFACTOR_PLAYBOOK.md` once for the phase.
+2. Read the local `AGENTS.md` for the target folder.
+3. Read only the relevant `index.ts` range and already-extracted modules.
+4. Move a bounded block with minimal import/export changes.
+5. Validate with `npm run check -- --pretty false`.
+6. For domain/runtime slices, also run `npm run smoke:harness`.
+7. Ask a read-only oracle to check equivalence before continuing.
+
+## Stop conditions
+
+- A slice requires importing from `src/**` back into `index.ts` without approval.
+- A `src/**` file would import from `index.ts`.
+- Typecheck failure requires behavior changes instead of import/export fixes.
+- Any public export, registration, sentinel, artifact path, schema description, or error string would change.