# 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/context-discovery/` — adaptive active search backend helpers: `npm run zob:context:doctor`, `npm run zob:context:init`, `npm run zob:context:query`, and `npm run smoke:context-discovery`; starts exploratory/natural-language discovery with ColGREP when installed/ready, gives sessions without native `zob_context_search` a compact wrapper command before `rg`/`grep`, validates grep fallback when absent, and keeps broad grep/find away from `.pi/sessions` / `.pi/agent-sessions`.
- `scripts/git-ops/` — governed `/zcommit` policy smokes.
- `scripts/goal-todo/` — Goal/TODO tree compatibility smokes, including `scripts/goal-todo/handoff-static-smoke.mjs` coverage for the Goal TODO ZPeer/ZTeam handoff script (`npm run smoke:goal-todo-handoff`).
- `scripts/harness-intake/` — natural-language harness setup/session analyzer that produces quarantined ZOB team/factory proposals plus tmux launch support.
- `scripts/intent-classifier/` — optional model intent-classifier fallback and privacy smoke tests.
- `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; canonical helpers are grouped in subfolders with top-level compatibility CLI shims.
- `scripts/release/` — local release-impact preview helpers for Conventional Commit driven CI releases; these never create tags or publish.
- `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`
- `scripts/zagent-static-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 validate:capability-refs
npm run smoke:context-discovery
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 `npm run release:preview` before an authorized `/zcommit push` when you want local visibility into whether the next `main` push should create a `vX.Y.Z` tag and publish to npm after CI passes.

Run `npm run validate:capability-refs` after changing `.pi/capabilities/zob-public-runtime-capabilities.json`, skills, docs, or runtime capability references. It verifies registry doc/skill refs resolve to repo-local files.

Run `npm run smoke:context-discovery` after changing context-discovery docs, skills, config, or helpers. It is expected to pass without ColGREP by proving the grep fallback path.

Run additional domain-specific smokes only when their source files are present and the task requires them.