# scripts/

Utility scripts for OwlCoda development and release.

## release-smoke.ts — Release smoke runner

Run all fixture cases:

```
npm run release:smoke
```

Run a single case:

```
npx tsx scripts/release-smoke.ts --case=readonly-review
npx tsx scripts/release-smoke.ts --case=deck-12p
```

Output structured JSON (useful for CI gate):

```
npx tsx scripts/release-smoke.ts --json
```

Exit 0 = all cases passed. Exit 1 = any case failed.

`prepublishOnly` invokes `npm run release:smoke`, so normal installs are not
slowed down, but `npm publish` is blocked if this binary-level behavior gate
does not exit 0. Keep this gate even after OTel/instrumentation work lands.

To add a trajectory, add `mockResponseSequence` to its entry in `src/benchmark/fixtures.ts`.

## eval-packet.ts — Clean prompt + external eval hooks

Generate the next production-eval packet without mixing runtime observation
instructions into the model prompt:

```
npx tsx scripts/eval-packet.ts --case=deck-46p --workspace=/tmp/owlcoda-eval
```

The JSON output intentionally separates:

- `taskPrompt`: send this to the model.
- `evalHooks`: keep this in the wrapper/audit layer, including exact artifact
  paths, timeout/keepalive policy, expected audit fields, and long-deck section
  policy.

## Write-target provenance gate — dogfood telemetry helpers

The write-target-provenance gate (shadow by default, opt-in enforcement via
`OWLCODA_GATE_PROVENANCE=1`) writes per-event JSONL to:

```
~/.owlcoda/telemetry/gate-events-YYYY-MM-DD.jsonl
```

Each line is a single event with a `kind` field. The provenance gate emits:

| kind                                  | meaning                                                                |
| ------------------------------------- | ---------------------------------------------------------------------- |
| `path_provenance_admit_evidence`      | A write was admitted; `authorizingKind` records which evidence applied |
| `path_provenance_parent_admit`        | Write admitted because parent dir was listed (Bash ls / Glob / etc)    |
| `path_provenance_would_block`         | Shadow mode: write would have been blocked under flag                  |
| `path_provenance_block`               | Flag-on: write blocked, tool did not execute                           |
| `path_provenance_deny_block`          | Explicit user/rule deny blocked the write                              |
| `path_provenance_bash_unparseable`    | Bash extractor could not parse a command; fail-open with telemetry     |
| `path_provenance_probe_override`      | Read/Glob/Grep against a denied path was allowed for inspection        |
| `path_provenance_rule_warning`        | A settings.json permission rule had a parse/applicability warning      |

Quick filters (dogfood):

```bash
# Today's full event stream
rg '"kind":"path_provenance_' ~/.owlcoda/telemetry/gate-events-$(date +%F).jsonl

# Count would-block hits today (Article-class hallucinations caught)
grep '"path_provenance_would_block"' ~/.owlcoda/telemetry/gate-events-$(date +%F).jsonl | wc -l

# Tally admit evidence by authorizingKind
grep '"path_provenance_admit_evidence"' ~/.owlcoda/telemetry/gate-events-$(date +%F).jsonl \
  | jq -r '.authorizingKind' | sort | uniq -c

# All real blocks since the gate was enabled
rg '"path_provenance_block"' ~/.owlcoda/telemetry/gate-events-*.jsonl
```

`path_provenance_deny_observed` / `_revoked` / `_pattern_skipped` are defined but
not yet emitted (state derivation runs many times per task; dedup is unbuilt).
Behavior is correct; only observability for those branches is incomplete.
