cowork-harness 0.33.0 → 1.0.0

package/.claude/skills/cowork-harness/SKILL.md

@@ -3,8 +3,8 @@ name: cowork-harness
 description: Test or debug a Claude Code skill/plugin under Claude Cowork's runtime — sandboxed agent, default-deny egress, the can_use_tool permission/question protocol — using the cowork-harness CLI. Use when validating or regression-testing a skill, authoring or debugging a scenario YAML (prompt + scripted answers + assert:), choosing a fidelity tier, scripting AskUserQuestion / tool-permission answers, or asserting artifacts, egress, or sub-agent dispatch. Especially when a harness run no-ops an assertion, fails on an unanswered gate, false-greens, a steered answer never reaches the model, or a web_fetch is unexpectedly denied or gated. NOT for generic unit testing (pytest/vitest of your own scripts) or non-Cowork CI. Covers the skill / run / chat / record / replay / trace / decide / assertions / scaffold commands and the session-vs-scenario split.
 metadata:
   author: cowork-harness
-  version: 0.33.0
-  tracks-harness: cowork-harness 0.33.0 (baseline desktop-1.20186.1)
+  version: 1.0.0
+  tracks-harness: cowork-harness 1.0.0 (baseline desktop-1.20186.1)
 ---
 
 # cowork-harness
@@ -22,7 +22,7 @@ flagged with a loud `::warning::`, not silent — auto-answer a gate, observe an
 allowlist). This skill exists mostly to keep you out of those traps — the Gotchas section below is
 the highest-value part. Read it.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 0.33.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 1.0.0` (baseline
 > `desktop-1.20186.1`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
@@ -39,9 +39,9 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 0.33.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=0.33.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=0.33.0"`. **Pin `@>=0.33.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 1.0.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.0.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.0.0"`. **Pin `@>=0.33.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
 
-  What the ≥ 0.33.0 floor gates, by release:
+  What the ≥ 1.0.0 floor gates, by release:
 
   - **core set (pre-0.21.0 vintage, or mixed):** `assertions --list`, `scaffold <run-id>`, `trace --view dispatches`, `artifact_json` incl. the `in:` operator (passes when the resolved value deep-equals one of the listed members — value ∈ your list, not the reverse), `verify-cassettes` incl. the `--allow-domain`/`--allow-email`/`--allow-patterns-file` allows (`--allow-patterns-file <path>` is a FILE of patterns, one regex per line — not a path to allow, unlike `--allow <regex>`), batch `record <dir>`/`--rerecord-stale`, `record --concurrency <N>`, record-time redaction, multiSelect/`answer:`, `verify-run` answer-coverage, `record --max-artifact-bytes`, live record-time deciders, scenario `skills:` staleness scoping with `COWORK_HARNESS_AGENT_SCOPE=skill`, `chat --plugin`, and `/help` in the REPL.
   - **0.21.0:** `verify-cassettes --allow-path` (`path` — local absolute filesystem paths — is the scanner's 4th class), and `hostloop`'s native host/VM process split with its `allow_host_writes:` consent field.
@@ -51,6 +51,7 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
   - **0.31.0:** the `lint-skill` (static host-loop footgun + `subagent_type` resolution linter) / `analyze-skill` (advisory `/sessions`-path static scan, `--strict`, `analyze-skill: ignore` marker) / `probe-dispatch` (single-dispatch mechanics probe) commands, `status --latest-for` (resolve a scenario's newest run dir by run time, not directory mtime), the `subagent_dispatch_healthy` composite assertion, and the persisted `result.json` fields `verdict`, `subagents[].referencesRead`/`subagents[].reasoning`, plus the `toolCounts`/`toolErrors`/`toolDurations` shape distinction.
   - **0.32.0:** `analyze-skill`'s directory scan now covering a skill/plugin's full contract surface (recursive `agents/`/`references/`/`commands/`, plugin-root-aware, symlink-following) with line/block-scoped `analyze-skill: ignore-next-line`/`ignore-start`/`ignore-end` markers and multi-path/glob input, and `lint-skill`'s provable in-plugin `subagent_type` typo now a WARN that gates under `--strict`.
   - **0.33.0:** the `redacted` marker on display-omitted reasoning — `subagents[].reasoning` and the top-level `thinking[]` now carry `{text:"", redacted:true}` when the model returns a signed-but-empty thought (so "reasoned, text omitted" is distinct from "no thought"), plus the fenced `debug.thinking_display` escape hatch.
+  - **1.0.0:** first stable release — the SPEC §12 compatibility contract takes effect (covered CLI/schema/env/Action surfaces are now stable; breaking changes need a major bump). No new author-facing command; the floor simply tracks the 1.0 release.
 - **Agent binary (sandboxed live tiers — `container`/`microvm`/`hostloop`/`cowork`).** The staged Claude Code agent is **bind-mounted** from a local Claude Desktop install, or point `COWORK_AGENT_BINARY` at a `claude-code-vm/<ver>/claude` ELF. Nothing is bundled. `protocol` (L0) and `replay` need no staged agent; for the sandboxed tiers, no agent → no run; report that, don't skip silently.
 - **Docker / Lima.** Only `--fidelity protocol` (L0) runs without them. `container` / `microvm` / `hostloop` / `cowork` need Docker (Lima for L2). If they're absent, drop to `--fidelity protocol` and **say so** — a green that never exercised the sandbox is not a sandbox pass.
 - **Auth.** `CLAUDE_CODE_OAUTH_TOKEN` (preferred), or `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`, via env or `.env`. Minting an OAuth token needs the **`claude` CLI** (`npm i -g @anthropic-ai/claude-code`, then `claude setup-token`).

package/.claude/skills/cowork-harness/references/ci-recipe.md

@@ -1,6 +1,6 @@
 # CI recipe — replay vs live lanes
 
-Self-contained reference. Tracks `cowork-harness 0.33.0` (baseline `desktop-1.20186.1`).
+Self-contained reference. Tracks `cowork-harness 1.0.0` (baseline `desktop-1.20186.1`).
 
 **Fastest path: the packaged Action.** One step gets you `replay`/`lint`/`verify-cassettes` plus a PR
 job-summary reporter (verdict table, staleness findings, cost/turns when available):
@@ -13,7 +13,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 ```
 
 The Action's `version` input defaults to `latest` — intentional so a copy-pasted recipe tracks the current
-release; pin an exact version (e.g. `version: "0.33.0"`) for reproducible CI.
+release; pin an exact version (e.g. `version: "1.0.0"`) for reproducible CI.
 
 Reach for the manual multi-step form below only when you need per-step control the Action's inputs don't
 cover (a custom flag combination, a different runner matrix per step, or `lint`/`verify-cassettes` gated
@@ -57,7 +57,7 @@ sha256-*checked* but not hard-blocking on mismatch — it's advisory for an inte
 GitHub-hosted runners, no token/Docker/agent:
 
 ```yaml
-- run: npm i -g "cowork-harness@>=0.33.0"
+- run: npm i -g "cowork-harness@>=1.0.0"
 - run: cowork-harness lint scenarios/*.yaml          # no silent false-greens
 - run: cowork-harness verify-cassettes cassettes/    # privacy + staleness
 - run: cowork-harness replay cassettes/              # token-free content/structure
@@ -197,7 +197,7 @@ jobs:
         with: { node-version: '20' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@>=0.33.0"
+      - run: npm i -g "cowork-harness@>=1.0.0"
       - run: cowork-harness lint scenarios/*.yaml                              # no-silent-false-green (needs python3; PyYAML bundled)
       - run: cowork-harness verify-cassettes cassettes/ --output-format json   # privacy + staleness gate
       - run: cowork-harness replay cassettes/ --output-format json             # token-free content/structure
@@ -226,7 +226,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=0.33.0"
+        run: npm i -g "cowork-harness@>=1.0.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

package/.claude/skills/cowork-harness/references/fidelity-and-answers.md

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 0.33.0` (baseline `desktop-1.20186.1`).
+Self-contained reference. Tracks `cowork-harness 1.0.0` (baseline `desktop-1.20186.1`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 

package/.claude/skills/cowork-harness/references/scenario-schema.md

@@ -1,6 +1,6 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 0.33.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.0.0`
 (baseline `desktop-1.20186.1`). If your checkout is newer, prefer the live `docs/scenario.md`,
 `docs/session.md`, and `SPEC.md`.
 

package/CHANGELOG.md

@@ -6,6 +6,37 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.0.0] — 2026-07-13
+
+**First stable release.** The compatibility contract in
+[SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract) is now in force: the covered
+surfaces — the CLI commands + exit codes, the scenario / session / baseline / run-result / cassette /
+protocol schemas, the documented environment variables, and the packaged Action's inputs/outputs — are
+stable, and a breaking change to any of them requires a major version bump. Human-readable text output
+is explicitly not covered. There is **no runtime behavior change from `0.33.0`** — `1.0.0` blesses that
+runtime as stable and adds the release-engineering guards below.
+
+### Added
+
+- **Surface-contract guard** (`test/surface-contract.test.ts`, `npm run gen:surface` /
+  `npm run check:surface`) — snapshots the structured §12 surfaces (every `schema/*.json`'s field paths
+  and enums including exit codes, `action.yml` inputs/outputs, and the documented `COWORK_*` env-var
+  set) into `test/fixtures/surface-baseline.json`; CI reds on undocumented drift so a covered-surface
+  change can't ship silently. The CLI/exit-code-semantics/`PlatformBaseline` surfaces are frozen via a
+  manual review step in `RELEASING.md`.
+- **`npm run bump -- X.Y.Z --write`** — rewrites every version location via targeted patterns (dry-run
+  by default), leaving historical release notes, the baseline pin, and the `V=` agent pins untouched;
+  self-checks `check:versions`.
+- **`npm run preflight`** — a local pre-release gate (`check:versions`, CHANGELOG heading, unused tag,
+  clean tree, live-key reminder); `--for-tag` additionally asserts `HEAD == origin/main` and a green
+  push-event CI run for `HEAD`, mechanically preventing a tag on the wrong commit.
+
+### Changed
+
+- CI marks a skipped live scenario suite with a loud "NOT live-validated" job-summary banner; the
+  release docs (`RELEASING.md`, `release.yml`) now state that a release tag must go on the merge commit
+  (the SHA with a push-event CI run), with recovery steps.
+
 ## [0.33.0] — 2026-07-13
 
 ### Fixed

package/README.md

@@ -91,7 +91,7 @@ node dist/cli.js replay examples/replays/example-pdf-skill.cassette.json
 
 > **Installed globally instead?** Once linked/installed, the same command is `cowork-harness replay
 > <cassette>` — but the relative path above only resolves from a source checkout's `examples/replays/`.
-> From a global install (`npm i -g "cowork-harness@>=0.33.0"`), point at the package root instead:
+> From a global install (`npm i -g "cowork-harness@>=1.0.0"`), point at the package root instead:
 > `cowork-harness replay "$(npm root -g)/cowork-harness/examples/replays/example-pdf-skill.cassette.json"`
 > (or copy the cassette into your own project and pass that path).
 
@@ -101,7 +101,7 @@ Live `run`/`skill` need the prerequisites in the next section — note the `prot
 > - **Replay only (zero setup):** `cowork-harness replay <cassette>` — no token, no Docker, no agent. The command above.
 > - **`protocol` (real model, no Docker):** needs only the auth token (item 3 below).
 > - **Live `container` / `microvm` / `hostloop` / `cowork`:** needs Docker (or Lima for `microvm`), a staged agent, and the token — run `cowork-harness doctor` first.
-> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@>=0.33.0"`.
+> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@>=1.0.0"`.
 
 Two more worked examples worth knowing about: `examples/scenarios/protocol-smoke.yaml` (zero-Docker smoke
 test) and `examples/scenarios/skill-loads.yaml` (container-tier acceptance check) — see
@@ -126,7 +126,7 @@ claude plugin marketplace add yaniv-golan/cowork-harness
 claude plugin install cowork-harness@cowork-harness
 ```
 
-The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@>=0.33.0"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
+The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@>=1.0.0"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
 
 It also follows the open [Agent Skills](https://agentskills.io) spec, so it installs cross-editor (Cursor, Codex, OpenCode, …) via [`npx skills`](https://github.com/vercel-labs/skills) (Vercel Labs' CLI implementation of that spec):
 
@@ -147,7 +147,7 @@ A global install is enough for CI `lint`, reading the teaching skill, and replay
 To `run` the worked examples live or copy them as a starting point, use a source checkout. (The marketplace
 skill install itself only pulls `.claude/skills/cowork-harness/` — SKILL.md + `references/` + `scenario.py`/
 assertion keys, per `.claude-plugin/marketplace.json`'s `source` — not the rest of this table; the full set
-above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@>=0.33.0"` — see
+above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@>=1.0.0"` — see
 [above](#drive-it-from-claude-code-companion-skill) — which pulls the same npm package as the global-install row.)
 
 ### Prerequisites for anything above `protocol` fidelity
@@ -665,7 +665,7 @@ jobs:
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `@>=0.33.0` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any advisory finding); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). See [`action.yml`](./action.yml) for the full input reference.
+Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `cowork-harness@>=1.0.0` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any advisory finding); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). See [`action.yml`](./action.yml) for the full input reference.
 
 The provided [GitHub Actions workflow](.github/workflows/ci.yml) runs a **six-stage pipeline**. The **unit** stage is the token-free gate you can copy into your skill repo; the `action-self-test`, `python`, `boundary`, `scenarios`, and `parity-drift` stages are this repo's own fidelity self-tests and are not directly portable (they build the harness's Docker image and run harness-specific e2e scenarios — see [`ci-recipe.md`](./.claude/skills/cowork-harness/references/ci-recipe.md) for the skill-repo template):
 

package/RELEASING.md

@@ -64,6 +64,21 @@ Never push the tag before CI is green for the exact commit you intend to tag. Th
 enforces this (`Require ci.yml success for this commit` step), but don't rely on it — tag a green
 SHA.
 
+**Tag the MERGE COMMIT (main HEAD after the merge), never the release-branch head — and here's why.**
+The publish gate (`require-ci-success`) queries `ci.yml` runs with `--event push` for the tagged SHA.
+`ci.yml` only triggers `on: push` for **`main`** (plus `pull_request` / `workflow_dispatch`), so a
+release-branch/PR head has *only* a `pull_request` run — which the `--event push` filter ignores.
+Tagging that SHA makes the gate poll ~30 min and then FAIL. Only the merge commit (produced by
+`gh pr merge`, then `git pull`ed onto `main`) has a push-event `ci.yml` run. This is why Phase 3 tags
+`main` HEAD after the merge — do **not** "optimize" by tagging the branch commit whose PR CI you just
+watched go green.
+
+When you query runs by SHA, use the **full 40-char SHA** (`git rev-parse HEAD`) —
+`gh run list --commit <short-sha>` silently returns empty. If you mis-tag: `git push origin
+:refs/tags/vX.Y.Z && git tag -d vX.Y.Z`, re-tag on `main` HEAD, re-push, and cancel the misfired
+release run. Running `npm run preflight -- --for-tag` right before the tag push mechanically catches
+this (it asserts `HEAD == origin/main` and that a push-event `ci.yml` run succeeded for `HEAD`).
+
 ## Versioning (semver, pre-1.0)
 
 Pre-1.0: **minor** (`0.N+1.0`) = new features and/or behavior changes; **patch** (`0.N.M+1`) =
@@ -75,8 +90,28 @@ From `1.0.0`, semver is enforced against the **covered surfaces enumerated in
 scenario/session/baseline/run-result/cassette/protocol schemas, the documented env vars, and the
 packaged Action's inputs/outputs). Human-readable text output is explicitly NOT covered.
 
+**Surface drift is partly automated.** `test/surface-contract.test.ts` snapshots the *structured*
+surfaces — every `schema/*.json` (field paths + enums, including exit-code enums), `action.yml`
+inputs/outputs, and the documented `COWORK_*` env-var set — into `test/fixtures/surface-baseline.json`.
+Any change to those reds CI until you regenerate (`npm run gen:surface`) and review the diff; at `1.0.0`
+a *removal or type/enum change* means a **major** bump. `npm run check:surface` prints the
+added/removed/changed breakdown.
+
+**1.0.0 surface-freeze review (one-time, MANUAL — the surfaces the snapshot can't cover).** Before
+tagging `1.0.0`, deliberately review and freeze the surfaces with no machine-readable source:
+- **CLI command + flag surface** — walk `cowork-harness --help` per command; confirm no command/flag is
+  removed or repurposed vs `0.x` intent. (No structured source exists — `cli-structural-guard`'s `CASES`
+  and `cli-help`'s pinned strings are hand-maintained.)
+- **Per-command exit-code semantics** (SPEC §11) — confirm the documented meanings are the ones you
+  intend to hold stable.
+- **The `PlatformBaseline` shape** (Zod in `src/types.ts`; no `schema/*.json`).
+
 ## Version locations — bump ALL of these to the same `X.Y.Z`
 
+> **`npm run bump -- X.Y.Z --write` automates this whole section** (targeted patterns + lockfile +
+> `check:versions`). The list below documents *what it touches* — keep it accurate if you add a new
+> version-bearing string, and add that string to `scripts/bump-version.ts` too.
+
 1. `package.json` → `"version"` (then run `npm install` to update `package-lock.json`).
 2. `.claude-plugin/marketplace.json` → `plugins[0].version`.
 3. `.claude/skills/cowork-harness/.claude-plugin/plugin.json` → `"version"`.
@@ -92,8 +127,9 @@ packaged Action's inputs/outputs). Human-readable text output is explicitly NOT
 8. `.claude/skills/cowork-harness/references/ci-recipe.md` → all `npm i -g "cowork-harness@>=X.Y.Z"` floors
    (currently 3 occurrences).
 9. `examples/replays/README.md` → the `npm i -g "cowork-harness@>=X.Y.Z"` floor.
-10. `README.md` → the three `npx "cowork-harness@>=X.Y.Z"` bootstrap-fallback floors. The
-    `check:versions` lockstep guard enforces these match the SKILL.md floor and will red CI otherwise.
+10. `README.md` → every `cowork-harness@>=X.Y.Z` floor (the bootstrap-fallback `npx`/`npm i -g` lines
+    plus the Action-inputs "companion skill's floor guidance" mention). The `check:versions` lockstep
+    guard enforces these match the SKILL.md floor and will red CI otherwise.
 
 ## Checklist
 
@@ -101,7 +137,14 @@ packaged Action's inputs/outputs). Human-readable text output is explicitly NOT
 - [ ] **CHANGELOG.md** — move everything under `## [Unreleased]` into a new
       `## [X.Y.Z] — YYYY-MM-DD` section; leave an empty `## [Unreleased]` on top. Include any
       **upgrade notes** (e.g. "re-record cassettes after the staleness-hash change").
-- [ ] Bump every version location listed above (items 1–10). `npm install` after bumping `package.json`.
+- [ ] Bump every version location (items 1–10) with **`npm run bump -- X.Y.Z --write`** — it rewrites all
+      of them via targeted patterns and updates the lockfile + self-checks `check:versions` (run without
+      `--write` first to preview the diff; dry-run is the default). It deliberately does **not** touch the
+      CHANGELOG or add the SKILL.md `- **X.Y.Z:**` release-note bullet — do the CHANGELOG move (above) and
+      add that bullet by hand.
+- [ ] `npm run preflight` — local pre-release gate (`check:versions`, CHANGELOG heading present + non-empty,
+      tag `vX.Y.Z` not already used, clean tree; warns if the `ANTHROPIC_API_KEY` repo secret is missing so
+      the push-to-main live suite would need the `SKIP_LIVE_SCENARIOS` override — see §9).
 - [ ] `npm run format:check` — fix any issues (`npx prettier --write "src/**/*.ts" "test/**/*.ts"`).
       A format failure is the most common first-pass CI red.
 - [ ] `npx tsc -p tsconfig.test.json --noEmit` — typecheck including tests.
@@ -128,8 +171,11 @@ packaged Action's inputs/outputs). Human-readable text output is explicitly NOT
       git checkout main && git pull origin main
       git push origin main
       ```
-- [ ] **Phase 3 — tag and publish**:
+- [ ] **Phase 3 — tag and publish** (tag the MERGE COMMIT = current `main` HEAD, per the "why" above):
       ```
+      git checkout main && git pull origin main
+      npm run preflight -- --for-tag   # asserts HEAD==origin/main AND a green push-event ci.yml run for HEAD
+      git tag vX.Y.Z                   # on main HEAD (the merge commit)
       git push origin vX.Y.Z
       gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')
       ```

package/examples/replays/README.md

@@ -16,7 +16,7 @@ DOES exercise a real gate exchange, see `example-multiselect-gate.cassette.json`
 
 Run it with:
 
-> Assumes the `cowork-harness` CLI is available — from a source checkout run `npm ci && npm run build && npm link` first, or `npm i -g "cowork-harness@>=0.33.0"`. (`replay` itself needs nothing else — no token, no Docker.)
+> Assumes the `cowork-harness` CLI is available — from a source checkout run `npm ci && npm run build && npm link` first, or `npm i -g "cowork-harness@>=1.0.0"`. (`replay` itself needs nothing else — no token, no Docker.)
 
 ```sh
 cowork-harness replay examples/replays/example-pdf-skill.cassette.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-harness",
-  "version": "0.33.0",
+  "version": "1.0.0",
   "description": "Scriptable, CI-friendly harness for Claude Cowork's runtime contract for testing skills across scenarios — same agent, mounts, egress allowlist, permission protocol, and sandbox limitations.",
   "license": "MIT",
   "type": "module",
@@ -91,6 +91,10 @@
     "prepack": "find .claude/skills/cowork-harness/scripts/_vendor -name __pycache__ -type d -prune -exec rm -rf {} + 2>/dev/null || true",
     "prepublishOnly": "npm run ci",
     "check:versions": "tsx scripts/check-versions.ts",
+    "bump": "tsx scripts/bump-version.ts",
+    "preflight": "tsx scripts/release-preflight.ts",
+    "gen:surface": "tsx scripts/gen-surface.ts",
+    "check:surface": "tsx scripts/check-surface.ts",
     "eval-gate": "tsx scripts/eval-gate.ts",
     "skill-critique": "tsx scripts/skill-critique.ts",
     "skill-critique-acceptance": "tsx scripts/skill-critique-acceptance.ts"

package/scripts/bump-version.ts

@@ -0,0 +1,274 @@
+// Bumps every hand-maintained "cowork-harness X.Y.Z" version mention across the repo via targeted,
+// pattern-based edits — NOT a blind old->new string replace, which would corrupt historical
+// release-note bullets ("- **0.33.0:** the redacted marker…") and prose ("the loop 0.33.0's
+// observability…"). Dry-run is the DEFAULT; --write is required to modify files.
+//
+//   tsx scripts/bump-version.ts <X.Y.Z>            # dry-run: print the diff summary, write nothing
+//   tsx scripts/bump-version.ts <X.Y.Z> --write    # write files, sync lockfile, self-verify
+//
+// (Deliberately no --dry-run flag: `npm run bump X --dry-run` would silently drop the flag — npm
+// eats it unless forwarded via `--` — and do a REAL bump. Default-safe avoids that trap.)
+//
+// This script intentionally does NOT touch: SKILL.md's `- **X.Y.Z:** …` release-note bullets, the
+// "the loop X.Y.Z's observability" prose, CHANGELOG.md per-release headings, anything under
+// baselines/, or the `V=X.Y.Z` agent-binary pins (those track the baseline agentVersion, not the
+// harness version — see check-versions.ts invariant 8). The CHANGELOG `[Unreleased]` -> `[X] — DATE`
+// move and the new SKILL.md release-note bullet are also NOT automated here — both are content, not
+// mechanical substitution; main() prints a reminder.
+//
+// See docs/internal/2026-07-13-release-process-improvements-plan.md (P3) for the design and the
+// adversarial-review fixes folded in (dry-run-by-default, the README bare `@>=X` floor, the
+// current-version-bullet-survives test).
+
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { checkVersions } from "./check-versions.js";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const r = (p: string) => readFileSync(join(REPO_ROOT, p), "utf8");
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+// ---------------------------------------------------------------------------
+// Pattern-level rewrites. Each is scoped to the exact surrounding context it targets so a bare
+// version number in unrelated prose (a release-note bullet, a baseline pin, a Node-version mention)
+// never matches.
+// ---------------------------------------------------------------------------
+
+/** Every `cowork-harness@>=X.Y.Z` floor. */
+function bumpHarnessFloors(content: string, newVersion: string): string {
+  return content.replace(/cowork-harness@>=\d+\.\d+\.\d+/g, `cowork-harness@>=${newVersion}`);
+}
+
+/** A bare, backtick-delimited `` `@>=X.Y.Z` `` floor with no `cowork-harness` prefix (README.md only). */
+function bumpBareFloors(content: string, newVersion: string): string {
+  return content.replace(/`@>=\d+\.\d+\.\d+`/g, `\`@>=${newVersion}\``);
+}
+
+/** The single `"version": "X.Y.Z"` JSON field in a file that carries exactly one such key. */
+function bumpJsonVersionField(content: string, newVersion: string): string {
+  return content.replace(/"version":\s*"\d+\.\d+\.\d+"/, `"version": "${newVersion}"`);
+}
+
+/** SKILL.md frontmatter `version:` line. */
+function bumpFrontmatterVersion(content: string, newVersion: string): string {
+  return content.replace(/^(\s*version:\s*)\d+\.\d+\.\d+(\s*)$/m, `$1${newVersion}$2`);
+}
+
+/**
+ * SKILL.md `tracks-harness: cowork-harness X.Y.Z (baseline desktop-A.B.C)` line — bumps only the
+ * harness-version token immediately after `cowork-harness `, leaving the `(baseline …)` suffix
+ * completely untouched.
+ */
+function bumpTracksHarnessLine(content: string, newVersion: string): string {
+  return content.replace(/(tracks-harness:\s*cowork-harness\s+)\d+\.\d+\.\d+/, `$1${newVersion}`);
+}
+
+/** SKILL.md `**Version note:** … track \`cowork-harness X.Y.Z\`` line. */
+function bumpVersionNoteLine(content: string, newVersion: string): string {
+  return content.replace(/(track `cowork-harness )\d+\.\d+\.\d+(`)/, `$1${newVersion}$2`);
+}
+
+/** SKILL.md `needs **≥ X.Y.Z**` sentence. */
+function bumpNeedsFloor(content: string, newVersion: string): string {
+  return content.replace(/(needs \*\*≥ )\d+\.\d+\.\d+(\*\*)/, `$1${newVersion}$2`);
+}
+
+/** SKILL.md `What the ≥ X.Y.Z floor gates` heading. */
+function bumpFloorGatesHeading(content: string, newVersion: string): string {
+  return content.replace(/(What the ≥ )\d+\.\d+\.\d+( floor gates)/, `$1${newVersion}$2`);
+}
+
+/** references/*.md `` Tracks `cowork-harness X.Y.Z` `` stamp. */
+function bumpTracksStamp(content: string, newVersion: string): string {
+  return content.replace(/Tracks `cowork-harness \d+\.\d+\.\d+`/g, `Tracks \`cowork-harness ${newVersion}\``);
+}
+
+/** ci-recipe.md's `` e.g. `version: "X.Y.Z"` `` example. */
+function bumpCiRecipeExample(content: string, newVersion: string): string {
+  return content.replace(/(e\.g\. `version: ")\d+\.\d+\.\d+(")/, `$1${newVersion}$2`);
+}
+
+// ---------------------------------------------------------------------------
+// Per-file composition. Each target file gets exactly the pattern set the release-process plan
+// (P3) specifies for it — never a blanket regex applied to every file, which would corrupt
+// unrelated version-shaped mentions the plan explicitly calls out (README.md's `Node ≥ 20` and
+// `≥1.14271.0` baseline mentions, for example).
+// ---------------------------------------------------------------------------
+
+const SKILL_MD = ".claude/skills/cowork-harness/SKILL.md";
+const CI_RECIPE_MD = ".claude/skills/cowork-harness/references/ci-recipe.md";
+const SCENARIO_SCHEMA_MD = ".claude/skills/cowork-harness/references/scenario-schema.md";
+const FIDELITY_AND_ANSWERS_MD = ".claude/skills/cowork-harness/references/fidelity-and-answers.md";
+const PLUGIN_JSON = ".claude/skills/cowork-harness/.claude-plugin/plugin.json";
+const MARKETPLACE_JSON = ".claude-plugin/marketplace.json";
+const REPLAYS_README = "examples/replays/README.md";
+
+/** Files this script knows how to edit, in the order they're reported. */
+export const TARGET_FILES: readonly string[] = [
+  "package.json",
+  MARKETPLACE_JSON,
+  PLUGIN_JSON,
+  SKILL_MD,
+  SCENARIO_SCHEMA_MD,
+  FIDELITY_AND_ANSWERS_MD,
+  CI_RECIPE_MD,
+  REPLAYS_README,
+  "README.md",
+];
+
+/**
+ * Pure: computes the new content for one file. Never reads or writes anything itself, so it can be
+ * exercised directly on fixture strings in tests without touching the repo.
+ */
+export function rewriteFileContent(relPath: string, content: string, newVersion: string): string {
+  switch (relPath) {
+    case "package.json":
+    case MARKETPLACE_JSON:
+    case PLUGIN_JSON:
+      return bumpJsonVersionField(content, newVersion);
+
+    case SKILL_MD: {
+      let next = content;
+      next = bumpFrontmatterVersion(next, newVersion);
+      next = bumpTracksHarnessLine(next, newVersion);
+      next = bumpVersionNoteLine(next, newVersion);
+      next = bumpNeedsFloor(next, newVersion);
+      next = bumpFloorGatesHeading(next, newVersion);
+      next = bumpHarnessFloors(next, newVersion);
+      return next;
+    }
+
+    case SCENARIO_SCHEMA_MD:
+    case FIDELITY_AND_ANSWERS_MD:
+      return bumpTracksStamp(content, newVersion);
+
+    case CI_RECIPE_MD: {
+      let next = content;
+      next = bumpTracksStamp(next, newVersion);
+      next = bumpCiRecipeExample(next, newVersion);
+      next = bumpHarnessFloors(next, newVersion);
+      return next;
+    }
+
+    case REPLAYS_README:
+      return bumpHarnessFloors(content, newVersion);
+
+    case "README.md": {
+      let next = content;
+      next = bumpHarnessFloors(next, newVersion);
+      next = bumpBareFloors(next, newVersion);
+      return next;
+    }
+
+    default:
+      throw new Error(`bump-version: no rewrite rule registered for "${relPath}"`);
+  }
+}
+
+export interface FileEdit {
+  file: string;
+  before: string;
+  after: string;
+  changed: boolean;
+}
+
+/** Reads every target file off disk and computes its planned edit. Read-only — no writes. */
+export function planEdits(newVersion: string): FileEdit[] {
+  return TARGET_FILES.map((file) => {
+    const before = r(file);
+    const after = rewriteFileContent(file, before, newVersion);
+    return { file, before, after, changed: before !== after };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+export function parseArgs(argv: string[]): { version: string; write: boolean } {
+  const write = argv.includes("--write");
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  const version = positional[0];
+  if (!version || !SEMVER.test(version)) {
+    throw new Error(
+      `expected an X.Y.Z version as the first argument, got ${JSON.stringify(version ?? "")}. ` +
+        `Usage: tsx scripts/bump-version.ts <X.Y.Z> [--write]`,
+    );
+  }
+  return { version, write };
+}
+
+/** Rough per-file line-diff count for the human-readable summary — not used for correctness. */
+function countChangedLines(before: string, after: string): number {
+  const b = before.split("\n");
+  const a = after.split("\n");
+  let n = 0;
+  const max = Math.max(b.length, a.length);
+  for (let i = 0; i < max; i++) if (b[i] !== a[i]) n++;
+  return n;
+}
+
+function main(): void {
+  let version: string;
+  let write: boolean;
+  try {
+    ({ version, write } = parseArgs(process.argv.slice(2)));
+  } catch (err) {
+    process.stderr.write(`::error::bump-version: ${(err as Error).message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const edits = planEdits(version);
+  const changed = edits.filter((e) => e.changed);
+
+  process.stdout.write(`bump-version — target ${version} (${write ? "--write" : "dry-run; pass --write to modify files"})\n\n`);
+  for (const e of edits) {
+    if (e.changed) {
+      process.stdout.write(`~ ${e.file} — ${countChangedLines(e.before, e.after)} line(s) changed\n`);
+    } else {
+      process.stdout.write(`= ${e.file} — unchanged\n`);
+    }
+  }
+
+  if (changed.length === 0) {
+    process.stdout.write("\nNo files need changes — already at target version, or no matching patterns found.\n");
+    if (!write) return;
+  }
+
+  if (!write) {
+    process.stdout.write("\nDry run only — no files written. Re-run with --write to apply.\n");
+    return;
+  }
+
+  for (const e of changed) {
+    writeFileSync(join(REPO_ROOT, e.file), e.after, "utf8");
+  }
+  process.stdout.write(`\nWrote ${changed.length} file(s).\n`);
+
+  process.stdout.write("\nSyncing lockfile (npm install --package-lock-only)...\n");
+  execSync("npm install --package-lock-only", { cwd: REPO_ROOT, stdio: "inherit" });
+
+  process.stdout.write("\nSelf-verifying with check:versions...\n");
+  const { ok, errors, values } = checkVersions();
+  process.stdout.write(`version lockstep: ${JSON.stringify(values)}\n`);
+  if (!ok) {
+    for (const e of errors) process.stderr.write(`::error::${e}\n`);
+    process.stderr.write("::error::bump-version: check:versions failed after writing — see errors above.\n");
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write("✓ all version strings are aligned\n");
+
+  process.stdout.write(
+    "\nReminder — these are MANUAL, not done by this script:\n" +
+      `  - Move CHANGELOG.md's [Unreleased] section to "## [${version}] — <DATE>".\n` +
+      `  - Add a new SKILL.md release-note bullet: "- **${version}:** …".\n`,
+  );
+}
+
+// Run only when invoked directly (so a test can import the pure functions without side effects).
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main();

package/scripts/check-surface.ts

@@ -0,0 +1,95 @@
+// Compares the current structured surface (schema/*.json, action.yml IO, documented COWORK_* env
+// vars — see scripts/lib/surface.ts) against the committed test/fixtures/surface-baseline.json and
+// categorizes the diff into additions / removals / changes.
+//
+//   npx tsx scripts/check-surface.ts
+//
+// Pre-1.0, drift detection lives in test/surface-contract.test.ts as a plain snapshot-sync assertion
+// — ANY diff (including a pure addition) fails that test, forcing a conscious `npm run gen:surface`
+// regen + review before it ships. This script/module is the FUTURE 1.0 upgrade path: at 1.0, switch
+// the test to call checkSurface() and hard-fail only on `removed`/`changed` — a pure `added` result
+// is fine without a major bump, since additions aren't a compatibility break.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { computeSurface } from "./lib/surface.js";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const BASELINE_PATH = join(REPO_ROOT, "test/fixtures/surface-baseline.json");
+
+export interface SurfaceDiff {
+  ok: boolean;
+  added: string[];
+  removed: string[];
+  changed: string[];
+}
+
+/** Flatten an arbitrarily-nested JSON-able value into dotted/bracketed leaf paths -> a stable string
+ *  value, so two surfaces can be diffed key-by-key regardless of nesting shape. */
+function flatten(value: unknown, prefix: string, out: Map<string, string>): void {
+  if (value === null || typeof value !== "object") {
+    out.set(prefix, JSON.stringify(value));
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      out.set(prefix, "[]");
+      return;
+    }
+    value.forEach((item, i) => flatten(item, `${prefix}[${i}]`, out));
+    return;
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj);
+  if (keys.length === 0) {
+    out.set(prefix, "{}");
+    return;
+  }
+  for (const key of keys) flatten(obj[key], prefix ? `${prefix}.${key}` : key, out);
+}
+
+/** Compare computeSurface() against the committed baseline. `added` (a new leaf path) is fine at
+ *  1.0; `removed` and `changed` are breaking and, at 1.0, must gate a release without a major bump. */
+export function checkSurface(): SurfaceDiff {
+  const baseline = JSON.parse(readFileSync(BASELINE_PATH, "utf8")) as unknown;
+  const current = computeSurface() as unknown;
+
+  const baseFlat = new Map<string, string>();
+  const curFlat = new Map<string, string>();
+  flatten(baseline, "", baseFlat);
+  flatten(current, "", curFlat);
+
+  const added: string[] = [];
+  const removed: string[] = [];
+  const changed: string[] = [];
+
+  for (const [path, curVal] of curFlat) {
+    if (!baseFlat.has(path)) added.push(path);
+    else if (baseFlat.get(path) !== curVal) changed.push(path);
+  }
+  for (const path of baseFlat.keys()) {
+    if (!curFlat.has(path)) removed.push(path);
+  }
+
+  added.sort();
+  removed.sort();
+  changed.sort();
+
+  return { ok: removed.length === 0 && changed.length === 0, added, removed, changed };
+}
+
+function main(): void {
+  const { ok, added, removed, changed } = checkSurface();
+  process.stdout.write(`surface diff: +${added.length} -${removed.length} ~${changed.length}\n`);
+  if (added.length) process.stdout.write(`  added:   ${added.join(", ")}\n`);
+  if (removed.length) process.stderr.write(`::error::removed: ${removed.join(", ")}\n`);
+  if (changed.length) process.stderr.write(`::error::changed: ${changed.join(", ")}\n`);
+  if (ok) {
+    process.stdout.write("✓ no breaking surface changes\n");
+    return;
+  }
+  process.exitCode = 1;
+}
+
+// Run only when invoked directly (so a test can import checkSurface without side effects).
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main();

package/scripts/gen-surface.ts

@@ -0,0 +1,28 @@
+// Regenerates the committed structured-surface snapshot.
+//
+//   npm run gen:surface
+//
+// Writes test/fixtures/surface-baseline.json from the CURRENT repo state: schema/*.json field
+// paths/enums, action.yml's inputs + outputs, and the documented COWORK_* env-var set (see
+// scripts/lib/surface.ts for exactly what's covered and what's deliberately not).
+//
+// Run this whenever one of those surfaces changes intentionally, then review the diff — especially
+// any removal or type/enum change, which pre-1.0 is still allowed to ship but must be a conscious
+// decision, not silent drift. test/surface-contract.test.ts fails until the snapshot is regenerated
+// to match the live surface.
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { computeSurface } from "./lib/surface.js";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const BASELINE_PATH = join(REPO_ROOT, "test/fixtures/surface-baseline.json");
+
+function main(): void {
+  const surface = computeSurface();
+  writeFileSync(BASELINE_PATH, JSON.stringify(surface, null, 2) + "\n");
+  process.stdout.write("wrote test/fixtures/surface-baseline.json\n");
+}
+
+// Run only when invoked directly (so a test can import computeSurface/BASELINE_PATH without side effects).
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main();

package/scripts/lib/env-scrape.ts

@@ -0,0 +1,35 @@
+// Scrapes every COWORK_* env-var name referenced anywhere in src/, across all three shapes the
+// codebase actually reads env vars in:
+//   1. `process.env.COWORK_X` dot-access
+//   2. a quoted literal (helper-read families like envPositiveNumber("COWORK_X"), or an env-name
+//      constant assigned once and dot-accessed elsewhere)
+//   3. `env.COWORK_X` — a destructured/aliased env object read
+// Dot-access alone misses (2) and (3) entirely, so all three patterns are required for a complete
+// scrape. Extracted from test/docs-index-sync.test.ts (its original home) so the documented-env-var
+// surface can be computed once and shared by that anti-drift test and scripts/lib/surface.ts's
+// structured-surface snapshot, instead of drifting as two copies.
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function tsFilesUnder(dir: string): string[] {
+  return readdirSync(dir, { recursive: true, encoding: "utf8" })
+    .filter((f) => f.endsWith(".ts"))
+    .map((f) => join(dir, f));
+}
+
+const ENV_SCRAPE_PATTERNS = [/process\.env\.(COWORK[A-Z0-9_]+)/g, /["'](COWORK[A-Z0-9_]+)["']/g, /\benv\.(COWORK[A-Z0-9_]+)/g];
+
+/** Every COWORK_* env-var name read anywhere under src/, unioned across all three read shapes. */
+export function scrapeCoworkEnvVars(): Set<string> {
+  const srcText = tsFilesUnder(join(REPO_ROOT, "src"))
+    .map((f) => readFileSync(f, "utf8"))
+    .join("\n");
+  const names = new Set<string>();
+  for (const re of ENV_SCRAPE_PATTERNS) {
+    for (const m of srcText.matchAll(re)) names.add(m[1]);
+  }
+  return names;
+}

package/scripts/lib/surface.ts

@@ -0,0 +1,157 @@
+// Computes a deterministic snapshot of the harness's structured, machine-checkable public surfaces:
+// the JSON Schemas under schema/*.json (property paths + enum/const values, including the exit-code
+// enums), action.yml's inputs + outputs, and the documented COWORK_* env-var set.
+//
+// Read by scripts/gen-surface.ts (writes the committed baseline) and scripts/check-surface.ts /
+// test/surface-contract.test.ts (compare the live repo against it).
+//
+// This is deliberately a PARTIAL surface. Not covered (stays a manual release-checklist item):
+//   - the CLI command/flag surface — no machine-readable source exists; cli-structural-guard drives
+//     a hand-maintained CASES list and cli-help greps pinned strings, and --help text is explicitly
+//     non-contractual.
+//   - per-command exit-code SEMANTICS — the exit-code *values* are schema-expressible (and ARE
+//     covered, e.g. verdict.exitCode / verify-cassettes' ok/coverage shape) but their meaning isn't.
+//   - the PlatformBaseline shape — Zod-only in src/types.ts, no schema/*.json emitted for it.
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { scrapeCoworkEnvVars } from "./env-scrape.js";
+
+export { scrapeCoworkEnvVars } from "./env-scrape.js";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SCHEMA_DIR = join(REPO_ROOT, "schema");
+
+interface SchemaLeaf {
+  type?: unknown;
+  enum?: unknown[];
+  const?: unknown;
+  ref?: string;
+  required?: true;
+  /** additionalProperties === false at this path — narrowing this later (adding it) is breaking. */
+  closed?: true;
+}
+
+/** Walk one JSON Schema node, recording a leaf at `path` for anything meaningful (type/enum/const/
+ *  $ref/closed/required), then recursing into properties, array items, additionalProperties' value
+ *  schema, and oneOf/anyOf/allOf branches. `$ref` targets are recorded as a pointer string, not
+ *  inlined — the referenced definition is walked separately as its own `definitions.<Name>` root, so
+ *  nothing is lost and there's no risk of infinite recursion on a self-referential schema. */
+function walkSchemaNode(node: unknown, path: string, requiredHere: boolean, out: Map<string, SchemaLeaf>): void {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) return;
+  const n = node as Record<string, unknown>;
+
+  const leaf: SchemaLeaf = {};
+  if ("type" in n) leaf.type = n.type;
+  if (Array.isArray(n.enum)) leaf.enum = n.enum;
+  if ("const" in n) leaf.const = n.const;
+  if (typeof n.$ref === "string") leaf.ref = n.$ref;
+  if (n.additionalProperties === false) leaf.closed = true;
+  if (requiredHere) leaf.required = true;
+  if (Object.keys(leaf).length > 0) {
+    out.set(path, { ...(out.get(path) ?? {}), ...leaf });
+  }
+
+  const requiredSet = new Set(Array.isArray(n.required) ? (n.required as string[]) : []);
+  const props = n.properties;
+  if (props && typeof props === "object" && !Array.isArray(props)) {
+    for (const key of Object.keys(props as Record<string, unknown>).sort()) {
+      walkSchemaNode((props as Record<string, unknown>)[key], `${path}.${key}`, requiredSet.has(key), out);
+    }
+  }
+  if ("items" in n) {
+    const items = n.items;
+    if (Array.isArray(items)) {
+      items.forEach((item, i) => walkSchemaNode(item, `${path}[${i}]`, false, out));
+    } else {
+      walkSchemaNode(items, `${path}[]`, false, out);
+    }
+  }
+  if (n.additionalProperties && typeof n.additionalProperties === "object") {
+    walkSchemaNode(n.additionalProperties, `${path}{}`, false, out);
+  }
+  for (const kind of ["oneOf", "anyOf", "allOf"] as const) {
+    const branches = n[kind];
+    if (Array.isArray(branches)) {
+      branches.forEach((sub, i) => walkSchemaNode(sub, `${path}<${kind}:${i}>`, false, out));
+    }
+  }
+}
+
+/** Property-path surface of one JSON Schema document (root paths, plus each `definitions`/`$defs`
+ *  entry as its own `definitions.<Name>` root), sorted by path for a stable diff. */
+export function surfaceForSchemaDoc(doc: Record<string, unknown>): Record<string, SchemaLeaf> {
+  const out = new Map<string, SchemaLeaf>();
+  walkSchemaNode(doc, "", false, out);
+  const defs = (doc.definitions ?? doc.$defs) as Record<string, unknown> | undefined;
+  if (defs && typeof defs === "object") {
+    for (const name of Object.keys(defs).sort()) {
+      walkSchemaNode(defs[name], `definitions.${name}`, false, out);
+    }
+  }
+  const sorted = [...out.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return Object.fromEntries(sorted);
+}
+
+/** Every schema/*.json file, each reduced to its property-path/enum surface. */
+export function computeSchemaSurface(): Record<string, Record<string, SchemaLeaf>> {
+  const files = readdirSync(SCHEMA_DIR)
+    .filter((f) => f.endsWith(".json"))
+    .sort();
+  const out: Record<string, Record<string, SchemaLeaf>> = {};
+  for (const f of files) {
+    const doc = JSON.parse(readFileSync(join(SCHEMA_DIR, f), "utf8")) as Record<string, unknown>;
+    out[f] = surfaceForSchemaDoc(doc);
+  }
+  return out;
+}
+
+interface ActionInputSurface {
+  required: boolean;
+  /** `null` when the input has no `default:` key at all (distinct from an explicit empty default). */
+  default: string | null;
+}
+
+interface ActionSurface {
+  inputs: Record<string, ActionInputSurface>;
+  outputs: string[];
+}
+
+/** action.yml's caller-facing contract: input names + required/default, and output names. Input/
+ *  output `description:` prose and each output's internal `value:` step-output expression are
+ *  excluded on purpose — they're not part of the caller-facing surface (rewording a description, or
+ *  renaming the internal step id an output reads from, isn't a breaking change for a consumer). */
+export function computeActionSurface(): ActionSurface {
+  const doc = parseYaml(readFileSync(join(REPO_ROOT, "action.yml"), "utf8")) as {
+    inputs?: Record<string, { required?: boolean; default?: unknown }>;
+    outputs?: Record<string, unknown>;
+  };
+  const inputs: Record<string, ActionInputSurface> = {};
+  for (const name of Object.keys(doc.inputs ?? {}).sort()) {
+    const spec = doc.inputs![name];
+    inputs[name] = {
+      required: spec.required === true,
+      default: "default" in spec ? String(spec.default) : null,
+    };
+  }
+  const outputs = Object.keys(doc.outputs ?? {}).sort();
+  return { inputs, outputs };
+}
+
+export interface Surface {
+  schemas: Record<string, Record<string, SchemaLeaf>>;
+  action: ActionSurface;
+  env: { coworkVars: string[] };
+}
+
+/** The full v1 structured-surface snapshot: schema/*.json field paths + enums, action.yml IO, and
+ *  the documented COWORK_* env-var set. Pure and deterministic — file reads only, sorted keys, no
+ *  timestamps or unsorted Set/Map iteration reaching the output. */
+export function computeSurface(): Surface {
+  return {
+    schemas: computeSchemaSurface(),
+    action: computeActionSurface(),
+    env: { coworkVars: [...scrapeCoworkEnvVars()].sort() },
+  };
+}

package/scripts/release-preflight.ts

@@ -0,0 +1,311 @@
+// Run the checks that today only fail AFTER a tag is pushed — locally, before the tag exists.
+// All checks are read-only (no writes, no push, no publish).
+//
+//   npx tsx scripts/release-preflight.ts             # pre-flight for the release branch/PR
+//   npx tsx scripts/release-preflight.ts --for-tag    # ALSO run the tag-time HEAD/CI check (hard fail)
+//
+// Checks 1-4 mirror (and check 2 tightens) the gates release.yml enforces after the tag push:
+//   1. check:versions passes (scripts/check-versions.ts).
+//   2. CHANGELOG.md has a "## [<package.json version>]" heading (release.yml:54-59's regex) AND —
+//      stricter than release.yml — the section body is non-empty.
+//   3. The tag `v<version>` does not already exist, locally or on origin.
+//   4. The working tree is clean (`git status --porcelain` empty).
+//   5. Best-effort, WARN-only: nudge about the ANTHROPIC_API_KEY repo secret (live-suite gate).
+//   6. --for-tag only, HARD fail: HEAD == origin/main HEAD, and a successful push-event ci.yml run
+//      exists for HEAD — the exact check that would have caught the 0.33.0 mis-tag (tagging a
+//      release-branch head instead of the merge commit).
+//
+// See docs/internal/2026-07-13-release-process-improvements-plan.md (P4 / P4b) for the design.
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { checkVersions } from "./check-versions.js";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const r = (p: string) => readFileSync(join(REPO_ROOT, p), "utf8");
+const json = (p: string) => JSON.parse(r(p)) as Record<string, any>;
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+/** Same shape as check-versions.ts's SEMVER check — kept local so this file has no side-effecting import. */
+export function isValidSemver(v: string): boolean {
+  return SEMVER.test(v);
+}
+
+/**
+ * Mirrors release.yml's "Verify CHANGELOG has a heading for this version" step (a literal
+ * `^## \[<version>\]` match, dots escaped) — plus a stricter, preflight-only requirement that the
+ * section body (everything between this heading and the next `## [`) is non-empty. release.yml itself
+ * does NOT require a non-empty body (its release-notes extraction step has its own fallback for that);
+ * this function is intentionally stricter so an accidentally-empty section is caught before the tag.
+ */
+export function changelogHasVersionSection(changelogText: string, version: string): boolean {
+  const escaped = version.replace(/\./g, "\\.");
+  const headingRe = new RegExp(`^## \\[${escaped}\\]`, "m");
+  if (!headingRe.test(changelogText)) return false;
+
+  const headingPrefix = `## [${version}]`;
+  const lines = changelogText.split("\n");
+  let inSection = false;
+  const body: string[] = [];
+  for (const line of lines) {
+    if (!inSection) {
+      if (line.startsWith(headingPrefix)) inSection = true;
+      continue;
+    }
+    if (line.startsWith("## [")) break;
+    body.push(line);
+  }
+  return body.some((line) => line.trim().length > 0);
+}
+
+/**
+ * Whether tag `v<version>` already exists, either locally (`git tag -l` output, one tag per entry) or
+ * on origin (`git ls-remote --tags origin` output, raw lines of the form `<sha>\trefs/tags/vX.Y.Z`,
+ * possibly with a trailing `^{}` for the dereferenced annotated-tag entry).
+ */
+export function tagExists(localTags: string[], remoteRefLines: string[], version: string): boolean {
+  const tagName = `v${version}`;
+  if (localTags.includes(tagName)) return true;
+  const suffixRe = new RegExp(`refs/tags/${tagName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\^\\{\\})?$`);
+  return remoteRefLines.some((line) => suffixRe.test(line.trim()));
+}
+
+type CheckStatus = "PASS" | "FAIL" | "WARN" | "SKIP";
+interface CheckResult {
+  name: string;
+  status: CheckStatus;
+  detail: string;
+}
+
+function run(cmd: string, args: string[]): { ok: boolean; status: number | null; stdout: string; stderr: string } {
+  const res = spawnSync(cmd, args, { encoding: "utf8", cwd: REPO_ROOT });
+  if (res.error) return { ok: false, status: null, stdout: "", stderr: String(res.error.message ?? res.error) };
+  return { ok: res.status === 0, status: res.status, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+function checkCheckVersions(): CheckResult {
+  const { ok, errors, values } = checkVersions();
+  return {
+    name: "check:versions",
+    status: ok ? "PASS" : "FAIL",
+    detail: ok ? `version lockstep OK (package.json=${values.pkg})` : errors.join("; "),
+  };
+}
+
+function checkChangelog(version: string): CheckResult {
+  const text = r("CHANGELOG.md");
+  const ok = changelogHasVersionSection(text, version);
+  return {
+    name: "CHANGELOG.md heading + non-empty section",
+    status: ok ? "PASS" : "FAIL",
+    detail: ok ? `found non-empty "## [${version}]" section` : `missing, or empty, "## [${version}]" section in CHANGELOG.md`,
+  };
+}
+
+function checkTagDoesNotExist(version: string): CheckResult {
+  const local = run("git", ["tag", "-l"]);
+  const localTags = local.stdout.split("\n").filter((l) => l.trim().length > 0);
+  const remote = run("git", ["ls-remote", "--tags", "origin"]);
+  if (!remote.ok) {
+    return {
+      name: `tag v${version} does not already exist`,
+      status: "FAIL",
+      detail: `could not query origin tags: ${remote.stderr || remote.stdout}`,
+    };
+  }
+  const remoteLines = remote.stdout.split("\n").filter((l) => l.trim().length > 0);
+  const exists = tagExists(localTags, remoteLines, version);
+  return {
+    name: `tag v${version} does not already exist`,
+    status: exists ? "FAIL" : "PASS",
+    detail: exists ? `v${version} already exists (local and/or origin)` : `v${version} is unused`,
+  };
+}
+
+function checkWorkingTreeClean(): CheckResult {
+  const status = run("git", ["status", "--porcelain"]);
+  const clean = status.ok && status.stdout.trim().length === 0;
+  return {
+    name: "working tree clean",
+    status: clean ? "PASS" : "FAIL",
+    detail: clean ? "no uncommitted changes" : `uncommitted changes present:\n${status.stdout}`,
+  };
+}
+
+/**
+ * Best-effort, WARN-only. `gh secret list` sees ONLY repo-level Actions secrets — an org- or
+ * environment-level ANTHROPIC_API_KEY would false-warn here, and the call itself needs admin scope on
+ * the repo. If `gh` is unavailable or unauthenticated, print the reminder unconditionally rather than
+ * silently skipping — RELEASING.md §9 documents the SKIP_LIVE_SCENARIOS override.
+ */
+function checkLiveSuiteKeyReminder(): CheckResult {
+  const REMINDER =
+    "if ANTHROPIC_API_KEY is not set as a repo secret, push-to-main ci will hard-fail the live scenario " +
+    "suite — set the secret or plan the SKIP_LIVE_SCENARIOS override (RELEASING.md §9). Note: `gh secret " +
+    "list` only sees repo-level Actions secrets — an org/environment secret would false-warn here, and the " +
+    "call needs admin scope.";
+
+  const ghVersion = run("gh", ["--version"]);
+  if (!ghVersion.ok) {
+    return { name: "live-suite key reminder", status: "WARN", detail: `gh not available — ${REMINDER}` };
+  }
+  const secrets = run("gh", ["secret", "list"]);
+  if (!secrets.ok) {
+    return {
+      name: "live-suite key reminder",
+      status: "WARN",
+      detail: `gh secret list failed (unauthenticated or insufficient scope) — ${REMINDER}`,
+    };
+  }
+  const hasKey = /^ANTHROPIC_API_KEY\b/m.test(secrets.stdout);
+  return {
+    name: "live-suite key reminder",
+    status: hasKey ? "PASS" : "WARN",
+    detail: hasKey ? "ANTHROPIC_API_KEY found among repo secrets" : `no repo-level ANTHROPIC_API_KEY — ${REMINDER}`,
+  };
+}
+
+/**
+ * [P4b] The check that directly prevents the 0.33.0 mis-tag: tagging a release-branch/PR head instead
+ * of the merge commit. Only meaningful right before the tag push, so it is gated behind --for-tag and,
+ * unlike checks 1-4, is a HARD failure there (tagging is near-irreversible).
+ */
+function checkForTag(): CheckResult {
+  const fetch = run("git", ["fetch", "origin", "main"]);
+  if (!fetch.ok) {
+    return {
+      name: "HEAD == origin/main, with a green push-event ci run",
+      status: "FAIL",
+      detail: `git fetch origin main failed: ${fetch.stderr || fetch.stdout}`,
+    };
+  }
+  const head = run("git", ["rev-parse", "HEAD"]);
+  const originMain = run("git", ["rev-parse", "origin/main"]);
+  if (!head.ok || !originMain.ok) {
+    return {
+      name: "HEAD == origin/main, with a green push-event ci run",
+      status: "FAIL",
+      detail: "could not resolve HEAD or origin/main",
+    };
+  }
+  const headSha = head.stdout.trim();
+  const originSha = originMain.stdout.trim();
+  if (headSha !== originSha) {
+    return {
+      name: "HEAD == origin/main, with a green push-event ci run",
+      status: "FAIL",
+      detail:
+        `HEAD (${headSha}) != origin/main (${originSha}) — you are about to tag a branch/PR head, not the ` +
+        `merge commit. Merge to main first (gh pr merge <n> --merge), then git checkout main && git pull.`,
+    };
+  }
+
+  const ghVersion = run("gh", ["--version"]);
+  if (!ghVersion.ok) {
+    return {
+      name: "HEAD == origin/main, with a green push-event ci run",
+      status: "FAIL",
+      detail: "HEAD == origin/main, but `gh` is unavailable — cannot verify a push-event ci.yml run for HEAD",
+    };
+  }
+
+  const runList = run("gh", [
+    "run",
+    "list",
+    "--workflow=ci.yml",
+    `--commit=${headSha}`,
+    "--event",
+    "push",
+    "-L1",
+    "--json",
+    "status,conclusion",
+  ]);
+  if (!runList.ok) {
+    return {
+      name: "HEAD == origin/main, with a green push-event ci run",
+      status: "FAIL",
+      detail: `gh run list failed: ${runList.stderr || runList.stdout}`,
+    };
+  }
+  let runs: Array<{ status: string; conclusion: string | null }>;
+  try {
+    runs = JSON.parse(runList.stdout);
+  } catch {
+    return {
+      name: "HEAD == origin/main, with a green push-event ci run",
+      status: "FAIL",
+      detail: `could not parse gh run list output: ${runList.stdout}`,
+    };
+  }
+  if (runs.length === 0) {
+    return {
+      name: "HEAD == origin/main, with a green push-event ci run",
+      status: "FAIL",
+      detail: `no push-event ci.yml run found for HEAD (${headSha}) — full 40-char SHA required, a short SHA returns empty`,
+    };
+  }
+  const [run0] = runs;
+  const ok = run0.status === "completed" && run0.conclusion === "success";
+  return {
+    name: "HEAD == origin/main, with a green push-event ci run",
+    status: ok ? "PASS" : "FAIL",
+    detail: ok
+      ? `HEAD == origin/main (${headSha}), push-event ci.yml: completed/success`
+      : `push-event ci.yml for HEAD (${headSha}) is status=${run0.status} conclusion=${run0.conclusion}`,
+  };
+}
+
+function printResult(res: CheckResult): void {
+  const icon = res.status === "PASS" ? "✓" : res.status === "WARN" ? "⚠" : res.status === "SKIP" ? "–" : "✗";
+  process.stdout.write(`${icon} [${res.status}] ${res.name}\n`);
+  if (res.status !== "PASS") process.stdout.write(`    ${res.detail.replace(/\n/g, "\n    ")}\n`);
+}
+
+function main(): void {
+  const forTag = process.argv.includes("--for-tag");
+  const pkg = json("package.json");
+  const version = pkg.version as string;
+  if (!isValidSemver(version)) {
+    process.stderr.write(`::error::package.json version "${version}" is not X.Y.Z\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write(`release preflight — version ${version}${forTag ? " (--for-tag)" : ""}\n\n`);
+
+  const hardResults: CheckResult[] = [
+    checkCheckVersions(),
+    checkChangelog(version),
+    checkTagDoesNotExist(version),
+    checkWorkingTreeClean(),
+  ];
+  const warnResult = checkLiveSuiteKeyReminder();
+
+  for (const res of hardResults) printResult(res);
+  printResult(warnResult);
+
+  let forTagResult: CheckResult | undefined;
+  if (forTag) {
+    forTagResult = checkForTag();
+    printResult(forTagResult);
+  }
+
+  const hardFailed = hardResults.some((r) => r.status === "FAIL") || forTagResult?.status === "FAIL";
+
+  process.stdout.write("\n");
+  if (hardFailed) {
+    process.stdout.write("✗ release preflight FAILED — fix the above before tagging.\n");
+    process.exitCode = 1;
+  } else {
+    process.stdout.write("✓ release preflight PASSED.\n");
+    if (forTag) {
+      process.stdout.write(`\nNext:\n  git tag v${version}\n  git push origin v${version}\n`);
+    }
+  }
+}
+
+// Run only when invoked directly (so a test can import the pure helpers without side effects).
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main();