cowork-harness 0.33.0 → 1.0.1

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.1
+  tracks-harness: cowork-harness 1.0.1 (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.1` (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.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.0.1" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.0.1"`. **Pin `@>=1.0.1`, 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.1 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.1` (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.1"`) 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.1"
 - 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.1"
       - 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.1"
       - 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.1` (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.1`
 (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

@@ -2,10 +2,65 @@
 
 All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The project uses
-[Semantic Versioning](https://semver.org/); pre-1.0 minor versions may include breaking changes.
+[Semantic Versioning](https://semver.org/); as of 1.0.0, a backwards-incompatible change to a covered surface ([SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)) requires a major bump.
 
 ## [Unreleased]
 
+## [1.0.1] — 2026-07-14
+
+Patch: Action Marketplace branding + a release-tooling fix. No runtime/API change.
+
+### Added
+
+- `action.yml` now declares Marketplace `branding` (`shield` / `orange`) so the packaged GitHub Action
+  can be listed on the GitHub Actions Marketplace. No change to the Action's inputs, outputs, or runtime.
+
+### Fixed
+
+- `npm run bump` now rewrites the bare `` `Pin `@>=X`` `` floor in `SKILL.md` — it previously bumped only
+  the `cowork-harness@>=`-prefixed floors, so that one line stayed stale (it had drifted since `0.33.0`
+  and shipped stale in `1.0.0`). A new `check:versions` invariant (5b) fails on any `@>=X` in `SKILL.md`
+  that doesn't match the floor, and a regression test covers the bump path.
+
+### Changed
+
+- `RELEASING.md` documents maintaining the moving `v1` / `v1.0` tags on each release, so
+  `uses: yaniv-golan/cowork-harness@v1` resolves to the latest 1.x.
+- Pruned stale pre-1.0 versioning language now that the compatibility contract is in force
+  (README, `SPEC.md`, `RELEASING.md`, `docs/maintenance.md`, this file); `SECURITY.md` now states
+  that only the latest published release is supported.
+
+## [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.1"`), 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.1"`.
 
 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.1"` (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.1"` — 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.1` 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):
 
@@ -821,7 +821,7 @@ From `1.0.0` this project follows [semver](https://semver.org/). What that cover
 exit codes, the scenario/session/baseline/`RunResult`/cassette/protocol schemas, the documented
 `COWORK_HARNESS_*` (+ `COWORK_AGENT_BINARY`/`COWORK_AGENT_IMAGE`) env vars, and the packaged Action's
 inputs/outputs. Human-readable terminal text is explicitly **not** part of the contract — parse the
-`--output-format json` envelope, not stdout. Pre-1.0, minor versions may still break any surface.
+`--output-format json` envelope, not stdout. As of 1.0.0, a backwards-incompatible change to a covered surface is a major bump.
 
 ## Status
 

package/RELEASING.md

@@ -64,19 +64,52 @@ 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.
 
-## Versioning (semver, pre-1.0)
-
-Pre-1.0: **minor** (`0.N+1.0`) = new features and/or behavior changes; **patch** (`0.N.M+1`) =
-backwards-compatible bug fixes only. New commands/flags, or changes to existing behavior (e.g. a
-stricter privacy gate, a changed cassette/staleness hash), are a **minor**.
-
-From `1.0.0`, semver is enforced against the **covered surfaces enumerated in
+**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)
+
+As of `1.0.0`, semver is enforced against the **covered surfaces enumerated in
 [SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)** (CLI + exit codes, the
 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.
+packaged Action's inputs/outputs): a backwards-incompatible change to a covered surface is a
+**major**; a new command/flag or other additive change is a **minor**; a backwards-compatible bug
+fix is a **patch**. 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 +125,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 +135,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,12 +169,22 @@ 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')
       ```
 - [ ] **Clean up**: `git push origin --delete release/X.Y.Z && git branch -d release/X.Y.Z`
+- [ ] **Move the major/minor tags** (so `uses: yaniv-golan/cowork-harness@v1` and `@v1.0` resolve to
+      this release — the packaged Action's Marketplace consumers pin those):
+      ```
+      git tag -f vX vX.Y.Z && git tag -f vX.Y vX.Y.Z   # e.g. v1 and v1.0 → v1.2.3
+      git push -f origin vX vX.Y
+      ```
+      (Force-moving these ALIAS tags is expected; never force-move the immutable `vX.Y.Z` release tag.)
 - [ ] Smoke the published artifact: `npx cowork-harness@X.Y.Z --version` and
       `npx cowork-harness@X.Y.Z doctor --tier protocol`.
 

package/SECURITY.md

@@ -60,4 +60,4 @@ following are enforced:
 
 ## Supported versions
 
-Pre-1.0: only the latest `main` is supported. Pin a commit for reproducibility.
+Only the latest published release is supported. Pin an exact version for reproducibility.

package/SPEC.md

@@ -678,8 +678,8 @@ entries (CB-5), adding major European, Asian, and Latin American ccTLDs
 
 From `1.0.0` the project follows [semver](https://semver.org/). The surfaces below are the **covered
 contract**: a backwards-incompatible change to any of them is a MAJOR bump. Everything else — most
-importantly human-readable text — is explicitly NOT covered and may change in any release. (Pre-1.0,
-nothing here is guaranteed; minor versions may break any surface — see [RELEASING.md](./RELEASING.md).)
+importantly human-readable text — is explicitly NOT covered and may change in any release.
+Covered-surface changes follow semver as of `1.0.0` — see [RELEASING.md](./RELEASING.md).
 
 **Covered (semver-guaranteed):**
 

package/docs/maintenance.md

@@ -182,8 +182,8 @@ The sync extractor currently targets macOS paths (`~/Library/Application Support
 > locations, the branch → PR → tag → publish flow, the checklist) lives in [RELEASING.md](../RELEASING.md).
 > The notes here only cover how a *parity sync* relates to versioning.
 
-Versioning follows [SemVer](https://semver.org/); pre-1.0 minor bumps may include breaking changes
-(baseline-schema or CLI-contract changes count as breaking). A parity-baseline *content* update (a new
+Versioning follows [SemVer](https://semver.org/); as of 1.0.0 a backwards-incompatible change to a
+covered surface (baseline-schema or CLI-contract changes count) is a major bump. A parity-baseline *content* update (a new
 Desktop release) is **not** a package version bump on its own — it ships in a normal patch/minor.
 
 Release flow — CD via `.github/workflows/release.yml`, published with **npm Trusted Publishing (OIDC)**

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.1"`. (`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.1",
   "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"