zob-harness 0.1.0

package/.pi/skills/zob-tool-router/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: zob-tool-router
+description: Use before non-trivial work, uncertain tool selection, orchestration, delegation, context lookup, factory work, autonomous-runtime claims, or evidence-gated completion.
+---
+# ZOB Tool Router Skill
+
+## Purpose
+
+This skill is the compact playbook for deciding which ZOB tool families, modes, and domain skills to use. It is not a runtime dispatcher and not a reason to use every tool. Use it to choose the smallest sufficient tool set, then follow each selected tool family's own safety gates.
+
+## When to use
+
+Use this skill when any of these are true:
+
+- the user ask is non-trivial, multi-step, or evidence-gated;
+- the right mode/tool family is ambiguous;
+- the work may need delegation, orchestration, factory design, context retrieval, ProjectDNA, coms, workspace/merge coordination, autonomous-runtime evidence, or oracle review;
+- you are about to claim completion for broad or risky work.
+
+Do not use this skill for a small factual answer when no tools are needed.
+
+## Core principles
+
+1. Do not use every tool. Use the smallest sufficient set.
+2. The registry is the source of truth for available tool families, mode allowlists, skill refs, docs, and no-ship notes: `.pi/capabilities/zob-public-runtime-capabilities.json`.
+3. This router selects families and domain skills; it does not bypass mode, approval, sandbox, budget, evidence, or oracle gates.
+4. If a family is applicable, either use it, delegate it, or explicitly skip it with a reason.
+5. Prefer evidence-backed progress over autonomy claims.
+
+## Routing loop
+
+1. Classify the request:
+   - trivial answer;
+   - bounded code/doc edit;
+   - multi-step goal;
+   - multi-agent orchestration;
+   - factory/repeated workflow;
+   - context/reference lookup;
+   - validation/oracle;
+   - autonomous-runtime claim.
+2. Identify applicable tool families from the table below.
+3. Load specialized skills for selected families when their behavior matters.
+4. Pick the smallest safe next action: answer directly, inspect, plan, implement, delegate, orchestrate, validate, block, or ask the user.
+5. Attach evidence to TODOs or final reports when work is broad, delegated, or completion-gated.
+6. If a human-decision blocker is already recorded (score >=90, no `nextAgent`, paused goal, visible blocker), report it once, do not repeat/redispatch, and wait for explicit `/goal resume` or `resume_goal`.
+7. Escalate to oracle when no-ship, final completion, security, autonomous, sandbox, or promotion risk is involved.
+
+## Tool family routing table
+
+| Family | Use when | Tools / skills to consider |
+| --- | --- | --- |
+| goal/TODO | Long-running, multi-step, delegated, factory, or evidence-gated work | `create_goal`, `add_goal_todos`, `get_goal_todos`, `resolve_goal_todo`; skill `zob-goal-todo-tree` |
+| delegation | Specialist review, parallel discovery, implementation handoff, independent QA, or uncertain broad work | `zob_delegation_catalog`, `delegate_task`, `delegate_agent`; skill `zob-delegation-routing` |
+| orchestration | Lead/Worker lanes, Chief Vision coordination, parent-owned dispatch, multi-agent workgraph | `/zmode orchestrator`, `orchestrate_run`, `chain_run`, goal/TODO tools |
+| compute | Complexity, budget, model class, max profile, or multi-agent sizing matters | `zob_compute_preview`, `zob_compute_resolve_profile`, `zob_compute_plan_workflow`, `zob_compute_validate_profile`; skill `zob-compute-profile` |
+| context / ProjectDNA | Need bounded repo/reference context, scan artifacts, cited context packs, or writeback proposals | `zob_context_validate_scope`, `zob_context_readiness`, `zob_project_dna_query`, `zob_project_dna_federated_query`, `zob_project_dna_readiness`; skill `zob-project-dna` |
+| factory | Repeated workflow, smoke/pilot/batch gates, manifests, checkpoints, sentinels | `factory_run`, factory quarantine tools, autonomous factory read-only smokes; skill `zob-factory` |
+| coms / goal-room | Parent-visible coordination, live required-local handoff, blockers, TODO claims, status refs | `zob_goal_room_*`, `zob_coms_*`; skills `zob-coms-v2-live`, `zob-coms-safety` |
+| workspace / merge queue | Parallel write intent, sandbox diff review, parent-owned manual apply decisions | `zob_workspace_claim`, `zob_workspace_release`, `zob_merge_candidate_submit`, `zob_merge_queue_decide`; skill `zob-sandbox` |
+| worker-pool | Parent-owned same-type/read-only or write-by-owner pool planning, path ownership/read-across coordination, owner requests/decisions | `zob_worker_pool_plan`, `zob_worker_pool_status`, `zob_worker_pool_owner_request`, `zob_worker_pool_owner_decision`; skills `zob-harness`, `zob-delegation-routing`, `zob-coms-safety` |
+| autonomous runtime | Dry-run, readonly smoke, validation evidence, or any autonomy readiness claim | `zob_autonomous_*`; skill `zob-autonomous-runtime` |
+| Mission Control | Dashboard snapshots, readiness, pause/resume/replan/request-oracle proposals | `zob_mission_control_*`, `zob_coms_readiness`; skill `zob-mission-control-coms` |
+| oracle | Final readiness, no-ship, safety/security, release, sandbox apply, or autonomous enablement | oracle agent/review, `propose_goal_completion`, `record_goal_oracle`; skill `zob-oracle` |
+
+## Anti-over-orchestration rules
+
+- Do not create a runtime goal for a simple question or tiny one-shot answer.
+- Do not delegate if direct answer or local inspection is enough.
+- Do not run compute profiling for a small obvious edit.
+- Do not use coms/goal-room when no other agent/run is involved.
+- Do not invoke factory tooling unless the workflow is repeatable or explicitly factory-shaped.
+- Do not treat dry-run, readonly smoke, plan-only orchestration, or mocked dispatch as final autonomous production readiness.
+- Do not use workspace/merge queue for single-agent non-overlapping edits unless sandbox governance is required.
+- Do not bypass oracle when completion, no-ship, sandbox promotion, autonomous enablement, or security risk is in scope.
+
+## Routing verdict format
+
+For non-trivial or ambiguous work, produce a compact internal or visible verdict before the first substantive action when useful:
+
+```text
+TOOL ROUTING VERDICT
+- complexity: trivial | small | non-trivial | high-risk
+- selected mode: explore | plan | implement | oracle | factory | orchestrator
+- applicable families:
+  - goal/TODO: use | delegate | skip — reason
+  - delegation: use | delegate | skip — reason
+  - orchestration: use | delegate | skip — reason
+  - compute: use | delegate | skip — reason
+  - context/ProjectDNA: use | delegate | skip — reason
+  - factory: use | delegate | skip — reason
+  - coms/goal-room: use | delegate | skip — reason
+  - workspace/merge: use | delegate | skip — reason
+  - worker-pool: use | delegate | skip — reason
+  - autonomous: use | delegate | skip — reason
+  - oracle: use | delegate | skip — reason
+- selected skills:
+- smallest sufficient next action:
+```
+
+Keep the verdict short. For routine small work, summarize only the selected next action instead of printing the full matrix.
+
+## Completion reminder
+
+Before claiming broad work complete, verify evidence, required TODO closure, validation commands, and oracle/no-ship requirements. If evidence is missing, continue, block, or ask the user instead of claiming success.

package/.pi/teams/zob-core.json

@@ -0,0 +1,122 @@
+{
+  "name": "zob-core",
+  "version": "0.1.0",
+  "description": "Default ZOB supervised Orchestrator -> Lead -> Worker topology. Parent Pi keeps preflight, dispatch, output gates, and ledger ownership.",
+  "orchestrator": {
+    "id": "zob-orchestrator",
+    "agent": "planner",
+    "description": "Parent-owned orchestrator that expands goals into lead and worker contracts without executing them in plan_only mode.",
+    "requiredTools": [
+      "read",
+      "grep",
+      "find",
+      "ls"
+    ],
+    "outputContract": "plan.v1",
+    "responsibilities": [
+      "Preserve ORIGINAL_USER_ASK and active goal.",
+      "Perform preflight before any child dispatch.",
+      "Keep parent-owned ledger and completion gates."
+    ]
+  },
+  "leads": [
+    {
+      "id": "discovery-lead",
+      "agent": "planner",
+      "description": "Plans discovery lanes and proposes bounded worker contracts.",
+      "requiredTools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "outputContract": "plan.v1",
+      "workerIds": [
+        "explore-worker",
+        "research-worker"
+      ],
+      "responsibilities": [
+        "Split the goal into read-only discovery tasks.",
+        "Identify missing evidence before implementation."
+      ]
+    },
+    {
+      "id": "verification-lead",
+      "agent": "oracle-merge",
+      "description": "Plans QA/oracle lanes and no-ship validation criteria.",
+      "requiredTools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "outputContract": "oracle-merge.v1",
+      "workerIds": [
+        "qa-worker",
+        "oracle-worker"
+      ],
+      "responsibilities": [
+        "Define PASS/FAIL/WARN validation lanes.",
+        "Protect no-ship decisions when evidence is insufficient."
+      ]
+    }
+  ],
+  "workers": [
+    {
+      "id": "explore-worker",
+      "leadId": "discovery-lead",
+      "agent": "explore",
+      "description": "Read-only mapper for relevant files, APIs, and gaps.",
+      "requiredTools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "outputContract": "explore.v1",
+      "taskTemplate": "Explore the repo for goal: {goal}. Return files, answer, gaps, next_steps, evidence, risks/blockers, compliance, and deliverable_delivered. Run id: {run.id}."
+    },
+    {
+      "id": "research-worker",
+      "leadId": "discovery-lead",
+      "agent": "librarian",
+      "description": "Researches local/official context and labels uncertainty.",
+      "requiredTools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "outputContract": "research.v1",
+      "taskTemplate": "Research local and provided context for goal: {goal}. Prefer official/local sources; state unknowns and safer wording. Run id: {run.id}."
+    },
+    {
+      "id": "qa-worker",
+      "leadId": "verification-lead",
+      "agent": "qa",
+      "description": "Plans or performs targeted verification when explicitly dispatched later.",
+      "requiredTools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "outputContract": "qa.v1",
+      "taskTemplate": "Plan targeted QA evidence for goal: {goal}. Identify smallest safe commands and sentinel/artifact checks. Run id: {run.id}."
+    },
+    {
+      "id": "oracle-worker",
+      "leadId": "verification-lead",
+      "agent": "oracle",
+      "description": "Defines skeptical review lane and blocking evidence requirements.",
+      "requiredTools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "outputContract": "oracle.v1",
+      "taskTemplate": "Review acceptance and no-ship criteria for goal: {goal}. Return PASS/FAIL/WARN criteria, evidence needs, blockers, and compliance. Run id: {run.id}."
+    }
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,89 @@
+# ZOB Harness v1 — Project Instructions
+
+This repo is a project-local Pi harness, not an application product. Optimize for agentic engineering: reusable workflows, specialist delegation, safety gates, and verified outputs.
+
+## Operating loop
+
+For non-trivial work use: Explore -> Plan -> Implement -> Oracle.
+
+1. Restate the task, allowed tools, MUST DO, MUST NOT, and expected outcome before tool use.
+2. Gather live context before editing. Do not rely on filename guesses or stale memory.
+3. Prefer small, reversible changes. Use `edit` for existing files and avoid broad rewrites.
+4. Verify with concrete evidence before claiming success.
+5. Finish with: result, evidence, risks/blockers, compliance line.
+
+## Delegation contract
+
+Use this six-part contract for specialist agents:
+
+```text
+1. TASK: [atomic goal]
+2. EXPECTED OUTCOME: [observable deliverable/verdict]
+3. REQUIRED TOOLS: [allowed tools only]
+4. MUST DO: [positive constraints]
+5. MUST NOT DO: [hard stops]
+6. CONTEXT: [paths, prior evidence, downstream use]
+```
+
+## Safety
+
+- Never read or write secrets (`.env`, keys, `~/.ssh`, `~/.aws`). Ask the user if a value is required.
+- Never run destructive commands (`rm -rf`, `git reset --hard`, `git clean`, broad process kills) without explicit user approval.
+- Never commit unless explicitly asked or governed autocommit is explicitly policy-authorized for the current task.
+- Commit/push/tag operations must go through governed `/zcommit` or the agent-executable `zob_zcommit_run` tool when the user explicitly asks the agent to commit/push; direct `git commit`, `git push`, `git tag`, force push, `git add .`, and `git add -A` are blocked.
+- Avoid touching generated/vendor folders: `node_modules`, `dist`, `build`.
+
+## Pi harness specifics
+
+- Runtime capability registry: `.pi/capabilities/zob-public-runtime-capabilities.json` is the first stop for public tool/command family, mode, skill, doc, and no-ship routing.
+- Extension: `.pi/extensions/zob-harness/index.ts`
+- Specialist agents: `.pi/agents/*.md`
+- Prompt templates: `.pi/prompts/*.md`
+- Synthesis agents: `.pi/agents/synthesis.md`, `.pi/agents/oracle-merge.md`
+- Damage rules: `.pi/damage-control-rules.json`
+
+## Tool-family router
+
+Use the registry plus the domain skill instead of copying tool docs into prompts:
+
+- Delegation/catalog: `zob_delegation_catalog`, `delegate_agent`, `delegate_task` -> `.pi/skills/zob-delegation-routing/SKILL.md` and `.pi/skills/zob-harness/SKILL.md`; call the catalog before first delegation when agent/contract/tool routing is uncertain, normally omit `delegate_task.output_contract` and `delegate_task.required_tools`, and never invent contract IDs or agent tools.
+- Live coms: `zob_coms_*` -> `.pi/skills/zob-coms-v2-live/SKILL.md` and `.pi/skills/zob-coms-safety/SKILL.md`; required-local delivery must be live, never append-only success.
+- Mission Control: `zob_mission_control_*` / readiness -> `.pi/skills/zob-mission-control-coms/SKILL.md`; command writes are proposals only.
+- Context: `zob_context_*` -> registry no-ship notes plus `.pi/skills/zob-harness/SKILL.md` / `.pi/skills/zob-spec/SKILL.md` as applicable.
+- Compute profile / effort routing: `zob_compute_*`, `npm run preview:compute-profile:project-dna-smoke`, `npm run validate:compute-profile:project-dna-smoke` -> `.pi/skills/zob-compute-profile/SKILL.md`; preview/resolve/report tools are metadata-only and never bypass safety, budget, oracle, sandbox, or parent-owned dispatch gates.
+- Autonomy: `zob_autonomous_*` -> `.pi/skills/zob-autonomous-runtime/SKILL.md`; dry-run/readonly smoke/validation are supervised evidence only, not global autonomy completion.
+- Factory quarantine/run: `factory_quarantine_*`, `factory_run` -> `.pi/skills/zob-factory/SKILL.md` and `.pi/skills/zob-sandbox/SKILL.md`.
+- Goal TODOs: `/goal`, `/todo`, `*_goal_todo*` -> `.pi/skills/zob-goal-todo-tree/SKILL.md`.
+- ProjectDNA/code knowledge graph: `/project-dna`, `zob_project_dna_*`, `.pi/factories/project-dna/*`, `npm run validate:project-dna`, `npm run smoke:project-dna-scan`, `npm run validate:project-dna-scan:smoke`, `npm run build:project-dna-capsules:smoke`, `npm run build:project-dna-sample-spec:smoke`, `npm run generate:project-dna-sample:smoke`, `npm run validate:project-dna-sample:smoke`, `npm run query:project-dna:smoke`, `npm run bench:project-dna:smoke`, `npm run oracle:project-dna:smoke` -> `.pi/skills/zob-project-dna/SKILL.md`; keep reference projects read-only, outputs quarantined/proposal-only, and never run external knowledge-backend import/sync/embed/write without explicit approval.
+
+Useful commands inside Pi:
+
+- `/zmode` — switch mode (`explore`, `plan`, `implement`, `oracle`, `factory`)
+- `/zcommit` / `zob_zcommit_run` — governed commit workflow (`status`/`plan`, `commit`, `push`, `commit_and_push`, `autocommit on|off`, `autopush on|off`); no aliases, defaults off, load `.pi/skills/zob-commit/SKILL.md` and `.pi/git-policy.json`; use `zob_zcommit_run` when the user explicitly asks the agent to commit/push
+- `/contract` — insert the six-part delegation template
+- `/agents` — list specialist agents
+- `/goal_gate` — set active goal/scope anchor
+- `/compute` / `/effort` — preview and resolve compute profile (`auto`, `low`, `medium`, `high`, `xhigh`, `max`) for a target path/task without child dispatch
+- `delegate_task` tool — strict single-task child Pi delegation with preflight/gates
+- `delegate_agent` tool — single, parallel, or chain child Pi agents
+- `factory_run` tool — deterministic manifest/checkpoint/sentinel software factory runner
+- `/project-dna` — query/audit ProjectDNA scan artifacts or start the ProjectDNA workflow for code-first reference-project context
+- `zob_project_dna_query` / `zob_project_dna_federated_query` — return bounded cited context from existing scan artifacts without external scans/backend writes
+- `npm run preview:compute-profile:project-dna-smoke` — write metadata-only compute preview/resolution artifacts for the safe ProjectDNA smoke target
+- `npm run validate:compute-profile:project-dna-smoke` — validate compute preview/resolution safety posture and profile fields
+- `npm run plan:compute-workflow:project-dna-smoke` — build metadata-only workflow-shape lanes from the resolved compute profile
+- `npm run validate:compute-workflow:project-dna-smoke` — validate workflow-shape parent-owned/no-dispatch posture
+- `npm run validate:compute-profile-policy` — validate repository compute profile defaults/overrides/risk rules
+- `npm run smoke:compute-profile-regression` — verify profile caps/gates across low/medium/high/xhigh/max
+- `npm run snapshot:compute-profile:project-dna-smoke` — write body-free Mission Control-compatible compute summary metadata
+- `npm run validate:project-dna` — validate the ProjectDNA scaffold without scanning external projects
+- `npm run smoke:project-dna-scan` — run a bounded read-only ProjectDNA scanner smoke against `.pi/factories/project-dna`
+- `npm run validate:project-dna-scan:smoke` — validate ProjectDNA scan artifacts, line refs, and no-write posture
+- `npm run build:project-dna-capsules:smoke` — build pointer capsules from ProjectDNA scanner smoke metadata only
+- `npm run build:project-dna-sample-spec:smoke` — build a neutral sample-project spec without generating code
+- `npm run generate:project-dna-sample:smoke` — generate a dependency-free ProjectDNA sample under reports quarantine
+- `npm run validate:project-dna-sample:smoke` — validate the quarantine sample with local Node checks/tests
+- `npm run query:project-dna:smoke` — build a bounded cited ProjectDNA query result from scan metadata
+- `npm run bench:project-dna:smoke` — run deterministic ProjectDNA retrieval/sample smoke benchmark
+- `npm run oracle:project-dna:smoke` — write structural oracle review for ProjectDNA smoke artifacts
+- `npm run smoke:harness` — non-destructive P0/P1/P2 gate/policy smoke tests

package/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to ZOB Harness
+
+Thanks for helping improve ZOB Harness.
+
+This project is a safety-first Pi harness. Contributions should preserve the operating model: explicit contracts, bounded changes, validation evidence, and no hidden side effects.
+
+## Development setup
+
+```bash
+npm install
+npm run check -- --pretty false
+```
+
+
+For a quick map of the tracked source surface, read `SOURCE_INDEX.md`. For validation/script ownership, read `scripts/README.md`.
+
+Start the harness locally:
+
+```bash
+npm run pi
+```
+
+## Contribution rules
+
+- Keep changes small and reversible.
+- Do not read or commit secrets, `.env` files, private keys, SSH/AWS material, or local credentials.
+- Do not commit generated runtime artifacts from `reports/`, `.pi/sessions/`, `.pi/tmp/`, `.pi/logs/`, or local ledgers.
+- Do not use direct `git commit`, `git push`, `git tag`, force push, `git add .`, or `git add -A` from agent workflows; use governed `/zcommit` only when explicitly requested or policy-authorized.
+- Preserve public tool names, command names, output contract ids, sentinel names, artifact paths, and safety defaults unless the change explicitly targets those surfaces.
+- For refactors, prefer split-only moves and prove no behavior drift.
+- Include validation commands and results in the pull request.
+
+## Recommended workflow
+
+1. Explore the current behavior.
+2. Plan the smallest safe change.
+3. Implement only the bounded slice.
+4. Run validation.
+5. If a commit is authorized, load `.pi/skills/zob-commit/SKILL.md` and `.pi/git-policy.json`, run `/zcommit status` then `/zcommit plan`, and commit only owned files with a Conventional Commit message.
+6. Document evidence and remaining risks.
+
+Minimum validation before opening a PR:
+
+```bash
+npm run check -- --pretty false
+```
+
+For runtime, safety, delegation, factory, or output-contract changes, also run the relevant smoke/audit script when possible.
+
+## Pull request checklist
+
+- [ ] The change is scoped and explained.
+- [ ] No generated reports, sessions, logs, private benchmark data, or local-only docs were committed.
+- [ ] No secrets or credentials were read or committed.
+- [ ] Validation commands and results are included.
+- [ ] Any no-ship risk or incomplete evidence is called out clearly.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZOB Harness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.