zob-harness 0.1.0

package/README.md

@@ -0,0 +1,360 @@
+# ZOB Harness
+
+**A governed Pi harness for human-controlled agentic engineering.**
+
+ZOB Harness turns an open-ended coding-agent chat into a governed engineering loop: clear contracts, specialist agents, mode-aware workflows, safety gates, evidence reports, skeptical oracle review, and repeatable software factories.
+
+It is for developers and evaluators who want agents to help with real repository work without losing the plot, touching secrets, silently committing, or declaring victory without proof.
+
+```text
+Human intent
+  -> six-part contract
+  -> scoped mode and tools
+  -> specialist agent or local implementation
+  -> validation evidence
+  -> oracle review / no-ship decision
+  -> reusable workflow when the pattern repeats
+```
+
+ZOB is not an “unleash the agent” project. It is a control plane for making agent work reviewable, bounded, and repeatable.
+
+## Why ZOB exists
+
+Normal coding-agent sessions can be impressive and still fail in predictable ways:
+
+- The agent drifts from the task or expands scope.
+- Research, planning, implementation, and review blur together.
+- Delegated work comes back without enough evidence.
+- Generated artifacts mix with source files.
+- Safety rules live in prose instead of enforceable gates.
+- “Done” is claimed before commands, diffs, and blockers are visible.
+
+ZOB adds an operating layer around Pi so each step has a job, a boundary, and an audit trail.
+
+## What you get
+
+### 1. Contract-first delegation
+
+Every delegated task can be expressed as a six-part contract:
+
+```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]
+```
+
+This keeps child work bounded and makes review easier: what changed, what was verified, what remains risky, and what should stop shipment.
+
+### 2. Mode-aware engineering loops
+
+ZOB separates the work into explicit modes:
+
+- **Explore** — inspect and map facts without editing.
+- **Plan** — turn evidence into a bounded implementation path.
+- **Implement** — change the smallest safe file set and verify it.
+- **Oracle** — review skeptically and surface no-ship blockers.
+- **Factory** — convert repeatable workflows into manifests, checkpoints, sentinels, and smoke gates.
+- **Orchestrator** — coordinate goals, TODO graphs, and specialist handoffs without bypassing safety.
+
+For non-trivial work, the default loop is:
+
+```text
+Explore -> Plan -> Implement -> Oracle
+```
+
+### 3. Specialist agents and domain skills
+
+The repo includes reusable operating assets for focused work:
+
+- [`.pi/agents/`](.pi/agents/) — specialist roles for exploration, planning, implementation, QA, oracle review, synthesis, ProjectDNA, and more.
+- [`.pi/skills/`](.pi/skills/) — domain instructions for commits, coms, factories, sandboxing, ProjectDNA, autonomy checks, goal/TODO trees, oracle review, and harness routing.
+- [`.pi/output-contracts/`](.pi/output-contracts/) — structured completion contracts for child results and other governed outputs.
+- [`.pi/capabilities/`](.pi/capabilities/) — runtime capability registry that maps public tools/commands to modes, skills, docs, and no-ship notes.
+
+The goal is not to make prompts longer. The goal is to route the right instructions only when a task needs them.
+
+### 4. Evidence-gated completion
+
+A ZOB result should make review straightforward. Agents are expected to report:
+
+- exact files changed;
+- exact commands run;
+- command outcomes;
+- evidence references;
+- unresolved risks and blockers;
+- compliance with forbidden paths, commit policy, and scope.
+
+That evidence posture is built into the project instructions in [AGENTS.md](AGENTS.md), the source map in [SOURCE_INDEX.md](SOURCE_INDEX.md), and the validation helpers in [scripts/README.md](scripts/README.md).
+
+### 5. Safety-first local operation
+
+ZOB is deliberately conservative around risky actions:
+
+- no `.env`, private key, SSH, AWS, or credential reads;
+- no destructive shell/git operations without explicit approval;
+- no direct commits, pushes, tags, or force pushes by default;
+- governed commits go through `/zcommit` only when explicitly authorized;
+- generated reports, ledgers, sessions, and local coordination state stay local;
+- autonomy checks are supervised evidence, not a claim of unrestricted autonomy.
+
+The safety posture is backed by [`.pi/damage-control-rules.json`](.pi/damage-control-rules.json), [`.pi/git-policy.json`](.pi/git-policy.json), the child-safety extension, and smoke scripts under [`scripts/`](scripts/README.md).
+
+### 6. Factories for repeatable work
+
+When a workflow repeats, ZOB can turn it into a factory-shaped process: manifest, checkpoints, sentinels, smoke/pilot/batch gates, artifacts, and oracle review. The repository includes safe scaffolds under [`.pi/factories/`](.pi/factories/) and validation commands for public, reproducible workflows.
+
+### 7. Local code knowledge with ProjectDNA
+
+ProjectDNA scaffolding helps turn approved local code scan artifacts into bounded, cited context packs and sample/spec outputs. The public posture is intentionally safe: read-only approved sources, generated artifacts under `reports/`, and no external knowledge-backend import/sync/embed/write unless explicitly approved.
+
+## Quick start
+
+### Requirements
+
+- Node.js **22+**; Node 24 is recommended.
+- npm.
+- Pi installed and available on `PATH`.
+
+### Install from npm for normal Pi use
+
+After the package is published to npm, install the pinned Pi package:
+
+```bash
+pi install npm:zob-harness@0.1.0
+```
+
+Then verify that Pi can load the package extension set and return a deterministic response:
+
+```bash
+pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"
+```
+
+Expected result:
+
+```text
+zob-harness-ok
+```
+
+If `pi install` cannot find the package, confirm the npm release is visible first:
+
+```bash
+npm view zob-harness@0.1.0 version
+```
+
+Expected result:
+
+```text
+0.1.0
+```
+
+Pi package discovery on `pi.dev/packages` is based on the npm `pi-package` keyword and may lag behind npm publication.
+
+### Try from a local checkout before publication
+
+Use this path when developing or validating a release candidate before npm publication:
+
+```bash
+git clone https://github.com/cgarrot/zob-harness.git
+cd zob-harness
+npm install
+npm run check -- --pretty false
+npm run pi:check
+npm run pack:dry-run
+```
+
+Expected results:
+
+- TypeScript completes with exit code 0 and no diagnostics.
+- Pi loads the local configured ZOB extension offline and replies with `zob-harness-ok`.
+- `npm pack --dry-run --json` lists the Pi manifest, extensions, prompts, skills, agents, and validation scripts in the tarball.
+
+### Start Pi with the local harness checkout
+
+```bash
+npm run pi
+```
+
+Inside Pi, try:
+
+```text
+/zmode
+/agents
+/contract
+```
+
+You should see ZOB modes, specialist agents, and the six-part delegation contract helper.
+
+### Public smoke baseline
+
+```bash
+npm run validate:script-surface
+npm run smoke:harness
+npm run check -- --pretty false
+npm run pack:dry-run
+```
+
+These commands verify the public script surface, core path/child-goal smokes, TypeScript baseline, and npm package surface.
+
+## Common workflows
+
+### A safe single-agent implementation loop
+
+```text
+1. Ask for Explore: inspect files and state a gap verdict.
+2. Ask for Plan: name the smallest file set and validation ladder.
+3. Ask for Implement: edit only that slice.
+4. Ask for Oracle: verify evidence and decide whether no-ship remains.
+```
+
+This keeps implementation from starting before the repo facts and stop conditions are clear.
+
+### Delegating work to a specialist
+
+Use `/contract` to create a bounded handoff, then route to an appropriate specialist agent. A good delegated result should come back with changed files, validation commands, evidence refs, risks, and no-ship status for parent/oracle review.
+
+### Goal-linked TODO work
+
+Use `/goal`, `/todo`, and `/goal_gate` when work needs a parent-owned TODO graph. Child agents return claims; the parent decides acceptance. This prevents children from marking parent work done without review.
+
+### Governed commits
+
+ZOB does not encourage invisible git operations. When a user explicitly asks for a commit, agents must use `/zcommit` and follow [`.pi/git-policy.json`](.pi/git-policy.json). Autocommit and autopush are off by default.
+
+### Repeatable factory runs
+
+For recurring tasks, use factory scaffolds rather than ad hoc repetition. Factories should keep manifests, checkpoints, sentinels, generated artifacts, smoke gates, and oracle evidence visible.
+
+### Bounded ProjectDNA context
+
+Use ProjectDNA commands and scripts when a task needs cited local code context. Keep scans approved, artifacts local, and writeback proposal-only unless the parent explicitly authorizes more.
+
+## Command cheat sheet
+
+Inside Pi:
+
+- `/zmode` — switch between `explore`, `plan`, `implement`, `oracle`, `factory`, and `orchestrator`.
+- `/stop` — abort current foreground work and local background activity without shutting down Pi.
+- `/contract` — insert the six-part delegation template.
+- `/agents` — list specialist agents.
+- `/goal`, `/todo`, `/todos`, `/goal_gate` — manage goal-linked TODO work and scope anchors.
+- `/compute` or `/effort` — preview/resolve compute profiles without bypassing safety gates.
+- `/project-dna` — query or operate bounded ProjectDNA context workflows.
+- `/zcompact` — configure proactive context compaction.
+- `/zcommit` — governed commit workflow; no direct git commit/push/tag shortcuts.
+- `/zpeer` — local peer/coms workflow commands where enabled.
+
+From npm/local checkout:
+
+```bash
+npm run pi                         # start Pi with configured harness wiring
+npm run pi:check                   # offline extension load check
+npm run check -- --pretty false    # TypeScript validation baseline
+npm run check:ci                   # CI-style TypeScript check
+npm run validate:script-surface    # package script/file surface validation
+npm run smoke:harness              # path-policy + child-goal-ref smoke
+npm run smoke:git-ops              # governed commit policy smoke
+npm run smoke:worker-pool          # worker-pool static smoke
+npm run smoke:zpeer                # static + local ZPeer smoke
+npm run validate:project-dna       # ProjectDNA scaffold validation
+npm run pack:dry-run               # npm package dry-run surface check
+```
+
+Published package install/check:
+
+```bash
+pi install npm:zob-harness@0.1.0
+pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"
+npm view zob-harness@0.1.0 version
+```
+
+See [scripts/README.md](scripts/README.md) for the script family map.
+
+## Repository map
+
+- [README.md](README.md) — project landing page and quickstart.
+- [AGENTS.md](AGENTS.md) — project-local agent operating rules.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — contributor workflow and validation expectations.
+- [SECURITY.md](SECURITY.md) — security policy.
+- [SOURCE_INDEX.md](SOURCE_INDEX.md) — tracked source and local/generated area map.
+- [package.json](package.json) — package metadata, Pi wiring, and npm scripts.
+- [scripts/README.md](scripts/README.md) — public script surface guide.
+- [`.pi/extensions/zob-harness/`](.pi/extensions/zob-harness/) — main Pi extension.
+- [`.pi/extensions/zob-child-safety/`](.pi/extensions/zob-child-safety/) — child-agent safety extension.
+- [`.pi/agents/`](.pi/agents/) — specialist agent definitions.
+- [`.pi/skills/`](.pi/skills/) — domain-specific operating instructions.
+- [`.pi/prompts/`](.pi/prompts/) — reusable prompt templates.
+- [`.pi/factories/`](.pi/factories/) — safe factory scaffolds.
+- [`.pi/output-contracts/`](.pi/output-contracts/) — structured output contract manifests.
+- [`.pi/capabilities/`](.pi/capabilities/) — public runtime capability registry.
+- [`scripts/`](scripts/README.md) — local validation, smoke, audit, and proof helpers.
+
+Local/generated areas such as `reports/`, `plans/`, `.pi/sessions/`, `.pi/logs/`, `.pi/tmp/`, coms ledgers, workspace claims, worker pools, and merge queues are not part of the normal source surface. See [SOURCE_INDEX.md](SOURCE_INDEX.md) for the current classification.
+
+## Current status and limits
+
+ZOB Harness is an early, conservative, governed harness. The public repo is useful for evaluating the operating model, extension wiring, skills, agents, safety posture, and smoke validations. It should not be described as unrestricted autonomy, a production deployment system, or a benchmark-winning agent framework.
+
+Current limits are intentional:
+
+- explicit scoped tools, paths, and stop conditions by default;
+- human approval for risky writes and commits;
+- no global autonomy claim from dry-run or read-only validation;
+- no public claims based on private benchmark artifacts;
+- generated reports and local runtime ledgers are kept out of source control;
+- advanced runtime moves and broad refactors should be split into reviewed slices.
+
+## Validation standard for changes
+
+For a normal README/docs or harness-surface change, start with:
+
+```bash
+npm run validate:script-surface
+git diff --check
+npm run check -- --pretty false
+```
+
+When relevant, add:
+
+```bash
+npm run smoke:harness
+npm run smoke:git-ops
+npm run smoke:worker-pool
+npm run validate:project-dna
+npm run pack:dry-run
+```
+
+For a public npm release, maintainers should additionally run:
+
+```bash
+npm whoami
+npm view zob-harness@0.1.0 version || true
+npm publish --dry-run
+npm publish
+npm view zob-harness@0.1.0 version
+pi install npm:zob-harness@0.1.0
+pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"
+```
+
+`npm publish` may require npm two-factor authentication in the browser or a one-time password. Do not paste OTPs, tokens, or secrets into issue reports or agent transcripts.
+
+Report exact command outcomes before claiming readiness.
+
+## Contributing
+
+Contributions should preserve the ZOB operating style:
+
+- small, reversible changes;
+- explicit scope and stop conditions;
+- no secret access;
+- no hidden commits or pushes;
+- no unsupported benchmark/autonomy claims;
+- validation evidence attached to every readiness claim.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow.
+
+## License
+
+MIT.

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+ZOB Harness is designed for local-first, safety-gated agentic engineering.
+
+## Supported version
+
+This repository currently publishes the active `main` branch as the supported development line.
+
+## Reporting a vulnerability
+
+Please report security issues privately through GitHub Security Advisories when available, or by opening a minimal issue that avoids posting exploit details or secrets publicly.
+
+When reporting, include:
+
+- affected component or path;
+- expected vs actual safety behavior;
+- reproduction steps that do not expose secrets;
+- whether generated artifacts, sessions, or logs are involved.
+
+## Security expectations
+
+The harness should never require contributors or agents to read or commit:
+
+- `.env` files;
+- private keys;
+- SSH/AWS credential folders;
+- provider API keys;
+- local session transcripts;
+- generated runtime ledgers or reports that may contain private context.
+
+Generated local artifacts such as `reports/`, `.pi/sessions/`, `.pi/agent-sessions/`, `.pi/tmp/`, `.pi/logs/`, coms ledgers, merge queues, and workspace claims are intentionally ignored by default.
+
+## No production-write guarantee
+
+This open-source release does not grant agents unrestricted production write access. Browser, cloud, billing, GitHub write, network, or production mutation workflows require explicit human approval and additional gates.

package/SOURCE_INDEX.md

@@ -0,0 +1,46 @@
+# ZOB Harness Source Index
+
+This file is the human-facing map of the tracked source surface. It is intentionally small and should stay current when public source folders change.
+
+## Core package files
+
+- `README.md` — project overview and quick start.
+- `AGENTS.md` — project-local operating rules for agents.
+- `CONTRIBUTING.md` — contributor workflow and validation expectations.
+- `SECURITY.md` — security policy.
+- `package.json` — npm scripts, package metadata, Pi extension/prompts/skills wiring.
+- `tsconfig.json` — TypeScript configuration.
+
+## Pi harness source
+
+- `.pi/extensions/zob-harness/` — main Pi extension.
+- `.pi/extensions/zob-child-safety/` — child-agent safety extension.
+- `.pi/capabilities/` — public runtime capabilities registry.
+- `.pi/agents/` — specialist agent definitions.
+- `.pi/skills/` — domain-specific operating instructions.
+- `.pi/prompts/` — prompt templates.
+- `.pi/output-contracts/` — output contract manifests.
+- `.pi/factories/` — reusable factory scaffolds that are safe for source control.
+- `.pi/chains/` — read-only/plan-only chain definitions.
+- `.pi/orchestrations/` — reusable orchestration profiles.
+- `.pi/teams/` — reusable team topology profiles.
+- `.pi/rules/` — rule packs.
+- `.pi/compute-profiles/` — compute profile defaults and risk rules.
+
+## Scripts
+
+See `scripts/README.md` for the script surface map.
+
+## Local/generated areas
+
+These are intentionally local/generated and should not be committed by default:
+
+- `docs/` — legacy/internal docs for now; future curated docs should be recreated intentionally.
+- `plans/` — captured planning artifacts.
+- `reports/` — generated reports and evidence.
+- `.pi/tmp/`, `.pi/logs/`, `.pi/sessions/`, `.pi/agent-sessions/` — runtime local state.
+- `.pi/coms/`, `.pi/context/`, `.pi/goal-rooms/`, `.pi/workspace-claims/`, `.pi/worker-pools/`, `.pi/merge-queue/` — generated ledgers/coordination state.
+
+## Cleanup rule
+
+Before moving, deleting, or committing a local/generated file, classify it first in a report under `reports/zob-cleanup-lanes/` and keep no-ship blockers visible.

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "zob-harness",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A governed, human-controlled Pi harness for contract-driven agentic engineering, safety gates, specialist delegation, and software-factory workflows.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cgarrot/zob-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cgarrot/zob-harness/issues"
+  },
+  "homepage": "https://github.com/cgarrot/zob-harness#readme",
+  "keywords": [
+    "pi-package",
+    "agentic-engineering",
+    "coding-agent",
+    "pi-extension",
+    "software-factory",
+    "safety-gates"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "AGENTS.md",
+    "README.md",
+    "SOURCE_INDEX.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "tsconfig.json",
+    ".pi/adapters/registry.json",
+    ".pi/agents",
+    ".pi/autonomy-policy.json",
+    ".pi/budget-policy.json",
+    ".pi/capabilities",
+    ".pi/chains",
+    ".pi/compute-profiles",
+    ".pi/daemon-policy.json",
+    ".pi/damage-control-rules.json",
+    ".pi/extensions",
+    ".pi/factories/budget-preflight-dry-run",
+    ".pi/factories/code-review-matrix",
+    ".pi/factories/factory-forge",
+    ".pi/factories/opencode-pattern-canonizer",
+    ".pi/factories/project-dna",
+    ".pi/factories/roadmap-smoke-lots",
+    ".pi/git-policy.json",
+    ".pi/mission-control/zob_coms_transport.json",
+    ".pi/model-routing.json",
+    ".pi/orchestrations",
+    ".pi/output-contracts",
+    ".pi/prompts",
+    ".pi/rules",
+    ".pi/settings.json",
+    ".pi/skills",
+    ".pi/teams",
+    "scripts/README.md",
+    "scripts/autonomy",
+    "scripts/compute-profile",
+    "scripts/git-ops",
+    "scripts/goal-todo",
+    "scripts/harness-switch",
+    "scripts/model-catalog",
+    "scripts/package-surface",
+    "scripts/path-policy",
+    "scripts/project-dna",
+    "scripts/worker-pool",
+    "scripts/zpeer-static-smoke.mjs",
+    "scripts/zpeer-local-e2e-smoke.mjs",
+    "scripts/start-pi.sh",
+    ".pi/model-catalog.example.json",
+    ".pi/model-economy.example.json"
+  ],
+  "scripts": {
+    "pi": "pi",
+    "pi:explore": "pi --no-extensions -e ./.pi/extensions/zob-harness/index.ts --tools read,grep,find,ls,delegate_agent --append-system-prompt 'Start in ZOB explore mode.'",
+    "pi:check": "pi --offline --no-session --no-extensions -e ./.pi/extensions/zob-harness/index.ts -p 'Reply exactly: zob-harness-ok'",
+    "check": "tsc --noEmit --pretty false",
+    "check:ci": "npm run check -- --pretty false",
+    "smoke:path-policy": "node scripts/path-policy/validate-smoke.mjs",
+    "smoke:child-goal-ref": "node scripts/goal-todo/child-goal-ref-smoke.mjs",
+    "smoke:git-ops": "node scripts/git-ops/commit-policy-smoke.mjs",
+    "smoke:harness": "npm run smoke:path-policy && npm run smoke:child-goal-ref",
+    "smoke:worker-pool": "node scripts/worker-pool/static-smoke.mjs",
+    "smoke:autonomy-readiness-secret": "node scripts/autonomy/mission-readiness-secret-smoke.mjs",
+    "smoke:zpeer": "node scripts/zpeer-static-smoke.mjs && node scripts/zpeer-local-e2e-smoke.mjs",
+    "validate:script-surface": "node scripts/package-surface/validate-script-refs.mjs",
+    "pack:dry-run": "npm pack --dry-run --json",
+    "validate:compute-profile-policy": "node scripts/compute-profile/validate-policy.mjs",
+    "smoke:compute-profile-regression": "node scripts/compute-profile/regression-smoke.mjs",
+    "validate:project-dna": "node scripts/project-dna/validate-scaffold.mjs",
+    "smoke:project-dna-scan": "node scripts/project-dna/scan.mjs --source-path .pi/factories/project-dna --source-id project-dna-factory --out-dir reports/project-dna-scans/project-dna-factory-smoke",
+    "validate:project-dna-scan:smoke": "node scripts/project-dna/validate-scan-artifacts.mjs --scan-dir reports/project-dna-scans/project-dna-factory-smoke",
+    "plan:project-dna-workflow:smoke": "node scripts/project-dna/plan-workflow.mjs --manifest .pi/factories/project-dna/example-project-dna-manifest-v2.json --scan-dir ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke} --out ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}/agentic-plan.json",
+    "validate:project-dna-workflow:smoke": "node scripts/project-dna/validate-workflow.mjs --plan ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}/agentic-plan.json --manifest .pi/factories/project-dna/example-project-dna-manifest-v2.json",
+    "emit:project-dna-ontology:smoke": "node scripts/project-dna/emit-ontology.mjs --scan-dir ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}",
+    "validate:project-dna-ontology:smoke": "node scripts/project-dna/validate-ontology.mjs --scan-dir ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}",
+    "emit:project-dna-golden-cases:smoke": "node scripts/project-dna/emit-golden-cases.mjs --scan-dir ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}",
+    "validate:project-dna-golden-cases:smoke": "node scripts/project-dna/validate-golden-cases.mjs --scan-dir ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}",
+    "steward:project-dna-query:smoke": "node scripts/project-dna/query-steward.mjs --scan-dir ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke} --query 'How does ProjectDNA keep bounded cited context?' --golden-case-id agentic-control-plane --out ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}/query-steward-smoke.json",
+    "validate:project-dna-5of5:smoke": "node scripts/project-dna/validate-5of5.mjs --scan-dir ${PROJECT_DNA_SCAN_DIR:-reports/project-dna-scans/project-dna-factory-smoke}",
+    "validate:model-catalog": "node scripts/model-catalog/validate.mjs",
+    "validate:model-economy": "node scripts/model-catalog/validate-economy.mjs",
+    "smoke:harness-switch": "node scripts/harness-switch/static-smoke.mjs"
+  },
+  "pi": {
+    "extensions": [
+      ".pi/extensions/zob-switch/index.ts",
+      ".pi/extensions/zob-harness/index.ts"
+    ],
+    "prompts": [
+      ".pi/prompts"
+    ],
+    "skills": [
+      ".pi/skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.75.5",
+    "@earendil-works/pi-coding-agent": "0.75.5",
+    "@earendil-works/pi-tui": "0.75.5",
+    "@types/node": "22.19.19",
+    "typebox": "1.0.66",
+    "typescript": "5.9.3"
+  }
+}

package/scripts/README.md

@@ -0,0 +1,57 @@
+# ZOB Harness Scripts
+
+This folder contains local validation, smoke, audit, and proof helpers.
+
+## Public/reproducible script families
+
+These script families are intended to be part of the normal tracked repo workflow:
+
+- `scripts/autonomy/` — static/read-only autonomy readiness smokes.
+- `scripts/compute-profile/` — compute profile policy and regression checks.
+- `scripts/git-ops/` — governed `/zcommit` policy smokes.
+- `scripts/goal-todo/` — Goal/TODO tree compatibility smokes.
+- `scripts/model-catalog/` — local model catalog/economy validators.
+- `scripts/package-surface/` — package.json script/file surface validation.
+- `scripts/path-policy/` — path safety smoke checks.
+- `scripts/project-dna/` — ProjectDNA scaffold/scan/query smoke helpers.
+- `scripts/worker-pool/` — worker-pool metadata/static checks.
+- `scripts/start-pi.sh` — local Pi startup helper.
+
+## Root smoke helpers
+
+Some root-level `*.mjs` files are one-off or transitional smoke helpers. Root-level scripts are ignored by default unless explicitly unignored/tracked.
+
+Public root-level helpers currently referenced by `package.json` are exact-file allowlisted in `.gitignore` and included in `package.json.files`:
+
+- `scripts/zpeer-static-smoke.mjs`
+- `scripts/zpeer-local-e2e-smoke.mjs`
+
+Deferred/local root helpers (for example, transitional delegation proof scripts) stay out of the public npm script surface until they are intentionally promoted.
+
+If a future `package.json` script references a root-level helper, that helper must either be tracked/unignored and added to `package.json.files`, or the npm script must be marked local-only/removed.
+
+## Local-only / private benchmark scripts
+
+The private benchmark scaffold is intentionally local-only and ignored:
+
+- `scripts/coding-agent-benchmark/`
+
+Do not expose these helpers through public `package.json` scripts or package files. Local benchmark operators can run private commands directly from their local checkout, but public/fresh-clone validation must not depend on this ignored scaffold unless the benchmark is sanitized and committed intentionally.
+
+## Generated outputs
+
+Scripts may write reports under `reports/`. Those outputs are generated evidence and are ignored by git.
+
+## Validation baseline
+
+Common safe checks:
+
+```bash
+npm run validate:script-surface
+npm run check -- --pretty false
+npm run smoke:harness
+```
+
+Run `npm run validate:script-surface` after changing `package.json` scripts, adding/removing script helper files, or changing `package.json.files`. It verifies package script file references exist, are not ignored, are tracked or visible as pending adds in the current patch, and are included in the package file surface.
+
+Run additional domain-specific smokes only when their source files are present and the task requires them.