cowork-harness 1.12.0 → 1.13.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. Also when iterating or hardening a skill across fixes, or grounding a skill's self-critique against its own run evidence — including a document-analysis skill (cap table, deck, financial model, transcript) that needs an uploaded file attached to be critiqued at all. 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: 1.12.0
-  tracks-harness: cowork-harness 1.12.0 (baseline desktop-1.24012.9)
+  version: 1.13.0
+  tracks-harness: cowork-harness 1.13.0 (baseline desktop-1.24012.9)
 ---
 
 # 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 1.12.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 1.13.0` (baseline
 > `desktop-1.24012.9`). 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,7 +39,7 @@ 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 **≥ 1.12.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.12.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.12.0"`. **Pin `@>=1.12.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.13.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.13.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.13.0"`. **Pin `@>=1.13.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.
 
   This skill documents the CURRENT surface, not release history. If `cowork-harness --version` is
   OLDER than the floor, the per-release record of what you are missing is [CHANGELOG.md](https://github.com/yaniv-golan/cowork-harness/blob/main/CHANGELOG.md)
@@ -70,7 +70,7 @@ reproducible regression (Part II), and **debug** a run that misbehaved or greene
   then `verify-run` to re-check a suspect assertion — all token-free, no Docker, no re-record. This is
   the loop 0.32.0's observability is built for; the *Triage* and *Inspecting a run's observability
   output* sections in **Part III — Debug** are the detail (the fuller human-facing map lives in
-  `docs/debugging.md` — repo-only, not shipped with the installed skill).
+  [`docs/debugging.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/debugging.md) — repo-only, not shipped with the installed skill).
 - **Multi-turn / interactive reproduction** → `cowork-harness chat` (interactive; gates answered at the
   TTY, **not** an asserted test — see *Debugging with `chat`* in **Part III — Debug**).
 
@@ -363,7 +363,7 @@ cassette — has its own recipe:
    skillHash keys the whole MOUNTED plugin, so on a multi-skill plugin the hash alone cross-pairs
    critiques of DIFFERENT skills — pair by the report's `(gradedSkillHash, gradedSkill)` pair. **On a pre-1.5.0 CLI the `skill` lane emits no `fingerprint.skillHash` at all**, so a
    pairing step there silently groups on an absent key instead of erroring — check the field is present, or
-   require ≥ 1.5.0. See `docs/debugging.md`
+   require ≥ 1.5.0. See [`docs/debugging.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/debugging.md)
    (repo-only) for the full loop.
 
 #### Interpreting verdict signals
@@ -416,7 +416,7 @@ Recognize these before "fixing" a non-bug:
   pass or a defect — assert `no_delete_in_outputs` / `transcript_no_host_path` to hard-fail on it instead.
 
 The full 14-code signal table (severity + per-signal opt-out) is in
-[`references/scenario-schema.md`](./references/scenario-schema.md); `docs/scenario.md` (repo-only) carries
+[`references/scenario-schema.md`](./references/scenario-schema.md); [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md) (repo-only) carries
 the fuller narrative.
 
 ### Checking whether a background run is alive
@@ -434,7 +434,7 @@ checkable regardless of PID namespace. The harness prints `[status] <outDir>` to
 run starts, so capture stderr to get the exact directory — but `<dir>` also accepts the run-dir root
 passed to `--run-dir` (a directory without its own `status.json`): it scans up to two levels down for the
 newest session's `status.json` and reads that. `--follow` fails loud on a timeout/staleness
-rather than hanging forever. (Fuller recipe in `docs/run-status.md` — repo-only, not in the installed
+rather than hanging forever. (Fuller recipe in [`docs/run-status.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/run-status.md) — repo-only, not in the installed
 payload; `cowork-harness status --help` has the flags.)
 
 **A multi-minute `record`/`run` outlives a short-lived wrapper.** Don't launch a long record from a
@@ -457,6 +457,11 @@ afterthought: the run already wrote its evidence, so you **localize the failure
 re-run and hope. Start at the triage below, then use the observability output and, when you need to
 reproduce interactively, `chat`.
 
+> **"Evidence" below means the run's own record** — events, trace, transcript; what `trace` / `inspect` /
+> `diff` / `verify-run` / `replay --explain` read. `critique`'s **evaluator** grades against a separate,
+> narrower record — `critique-evidence-package.txt`, what a grade was actually computed against — none of
+> the five tools above surface it; see `references/critique.md`.
+
 ### Triage — a run misbehaved, or a green looks wrong
 
 <!-- BEGIN triage-canonical -->
@@ -479,7 +484,7 @@ already does.
 **deliberate fidelity gap** — the harness intentionally does *not* reproduce a few real-Cowork behaviors,
 so a "bug" you see here that real Cowork also has isn't yours to fix. The tier semantics are in
 `references/fidelity-and-answers.md` (shipped); the specific deltas vs. real Cowork and the sandbox
-boundary model live in `docs/fidelity-gaps.md` / `docs/boundary.md` (repo-only, not in the installed
+boundary model live in [`docs/fidelity-gaps.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/fidelity-gaps.md) / [`docs/boundary.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/boundary.md) (repo-only, not in the installed
 payload). If the behavior is on that gap list, it's expected — stop debugging your skill.
 
 ### Inspecting a run's observability output
@@ -749,7 +754,7 @@ repeats the assertion/replay-relevant ones alongside the schema (a scoped subset
     `resolved-tier` finding (re-record — the recording now exercises the wrong tier); a cassette with no
     `effectiveFidelity` at all, or an unloadable pinned `baseline:`, reports `unverifiable-tier` instead
     (couldn't check — also re-record). Both are `fidelity: cowork`-only; an explicit-tier scenario never
-    produces them. (Details: `docs/cassette.md` § tier staleness — repo-only.)
+    produces them. (Details: [`docs/cassette.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/cassette.md) § tier staleness — repo-only.)
 
 22. **`lint` floods CI with INFO advisories that don't apply to you.** *Why:* two rules —
     `manifest-needs-snapshot` and `gate-needs-controlout` — fire on the mere presence of manifest/gate
@@ -785,5 +790,5 @@ assertion/replay-relevant ones).
   no-silent-false-green invariants (both usable as CI steps), and `resolve-agent-types <plugin-dir>`
   (validates a pinned `subagent_type` against the plugin's own `plugin.json` + `agents/*.md`).
 - Checking a background run's status without `ps aux` — covered in *Checking whether a background run is
-  alive* (Part II) above; the fuller recipe is in `docs/run-status.md` (repo-only, not shipped with the
+  alive* (Part II) above; the fuller recipe is in [`docs/run-status.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/run-status.md) (repo-only, not shipped with the
   installed skill).

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 1.12.0` (baseline `desktop-1.24012.9`).
+Self-contained reference. Tracks `cowork-harness 1.13.0` (baseline `desktop-1.24012.9`).
 
 **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: "1.12.0"`) for reproducible CI.
+release; pin an exact version (e.g. `version: "1.13.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
@@ -30,13 +30,14 @@ jobs:
     runs-on: [self-hosted, linux, arm64]   # needs Docker + this staged ELF; not a stock GitHub-hosted runner
     steps:
       - uses: actions/checkout@v4
-      - name: Stage the agent binary (official channel, sha256-verified — see docs/maintenance.md)
+      - name: Stage the agent binary (official channel, sha256-verified — see https://github.com/yaniv-golan/cowork-harness/blob/main/docs/maintenance.md)
         run: |
           V=2.1.219   # match your scenario's pinned baseline's agentVersion
           curl -fSL "https://downloads.claude.ai/claude-code-releases/$V/linux-arm64/claude" -o "$RUNNER_TEMP/claude-$V"
           chmod +x "$RUNNER_TEMP/claude-$V"
           # verify against the committed baseline's sha256 (baselines/desktop-*.json → agentBinary.sha256)
-          # before trusting it — see docs/maintenance.md's "Agent-binary provenance" section.
+          # before trusting it — see the "Agent-binary provenance" section of
+          # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/maintenance.md
           echo "COWORK_AGENT_BINARY=$RUNNER_TEMP/claude-$V" >> "$GITHUB_ENV"
       - uses: yaniv-golan/cowork-harness@main
         with:
@@ -48,7 +49,7 @@ jobs:
 Why this is a step *you* write, not an Action input the harness provides for you: pulling Anthropic's
 binary is a call about your own relationship with their distribution terms — keeping it in your own
 version-controlled workflow keeps that decision and its execution yours, auditable, and outside any
-third-party action's code. The agent-binary provenance runbook (`docs/maintenance.md` in the repo —
+third-party action's code. The agent-binary provenance runbook ([`docs/maintenance.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/maintenance.md) in the repo —
 not shipped with the installed skill) has the full recovery/verification story (including why
 `COWORK_AGENT_BINARY` substitutions are
 sha256-*checked* but not hard-blocking on mismatch — it's advisory for an intentional substitution).
@@ -57,7 +58,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@>=1.12.0"
+- run: npm i -g "cowork-harness@>=1.13.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
@@ -103,7 +104,7 @@ The split is not just about tokens — it decides **where each lane can run**:
   `allow_stall` (no-op passes); plus the gate keys `question_asked` / `questions_count_max` /
   `gate_answers_delivered` **if** the cassette has `controlOut`). Filesystem/egress assertions are
   skipped on this token-free lane — loudly: replay emits an `::warning::` annotation whenever it drops
-  one (see docs/cassette.md). This is your **always-on PR gate**. With `--output-format json`, read each
+  one (see [docs/cassette.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/cassette.md)). This is your **always-on PR gate**. With `--output-format json`, read each
   `results[].verdict.{pass,signals}` for **per-cassette** pass/fail and the reason (the top-level `ok`
   collapses the whole batch) — e.g. a `stalled` signal fails a cassette whose assertions all passed.
   The PR gate evaluates the assertions **frozen in the cassette**; to re-check against an edited on-disk
@@ -221,7 +222,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@>=1.12.0"
+      - run: npm i -g "cowork-harness@>=1.13.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
@@ -250,7 +251,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=1.12.0"
+        run: npm i -g "cowork-harness@>=1.13.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

package/.claude/skills/cowork-harness/references/critique.md

@@ -0,0 +1,72 @@
+# Critique — the facts a plugin install can't otherwise reach
+
+Tracks `cowork-harness 1.13.0` (baseline `desktop-1.24012.9`). This is **not** a trim of the full
+[`docs/critique.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/critique.md) (repo-only —
+flags, cost, reproduction discipline, known limitations all live there). This file covers exactly what a
+plugin install cannot otherwise discover: the run-dir artifact a harvester actually reads, the report's
+real field names, and what the evaluator was and was not shown. See **Recipe 5** in `task-recipes.md` for
+the harvest → reproduce → fix loop this feeds.
+
+## The run-dir artifact a harvester reads
+
+Beyond `critique-report.json` (the machine-readable report), a critique writes **`critique-evidence-package.txt`**
+at the run-dir root whenever the evaluator ran — the **armored** corpus the evaluator was actually graded
+against. Re-grade a disputed finding **offline** against this exact file instead of re-running the skill: a
+finding's `evidence` excerpt must resolve verbatim against this package, or it landed in `DROPPED`.
+
+| File | When | What |
+|---|---|---|
+| `critique-report.json` | always | the report a harvester parses |
+| `critique-evidence-package.txt` | evaluator ran | the exact armored corpus graded — re-gradeable offline |
+| `critique-salvage.json` | exit 2 only | raw pre-parse evaluator replies, for salvage without console-scraping |
+
+## Cost across critiques — the index, not the reports
+
+A critique is FOUR model workloads but only TWO produce a run, so only two produce index rows; the
+evaluator passes produce none. Each critique therefore appends a **roll-up row** (`critiqueRole:"rollup"`)
+carrying `critiqueTotalUsd` — the whole four-workload spend. Its own `costUsd` is the **evaluator passes
+only**, so `sum(costUsd)` over every row is exactly true spend with nothing double-counted or missed. The
+turn rows carry `critiqueRole:"task"` / `"reflection"`.
+
+Two things a harvester needs: roll-ups are excluded from `stats` aggregation (they carry no verdict —
+counting them adds a phantom run and drags `passRate` toward 1), so **filter them out of any pass-rate
+computed over raw rows**; and a roll-up with `result:"error"` had an unpriced workload, so its totals
+UNDERCOUNT. The index is the only cost record that survives run-dir pruning.
+
+## The report's item shape — no `title`, no `summary`
+
+Each `items[]` entry's prose fields are **`idea`** and **`recommendedAction`** — there is no `title` field
+and no `summary` field. A consumer that parses for either gets silently blank output instead of an error.
+Full required set: `source` (`evaluator`|`self-report`), `idea`, `classification`, `evidence` (the cited
+excerpt, verbatim-checked against the evidence package), `recommendedAction`. The optional
+`findingFingerprint` hashes `idea`+`classification`+`recommendedAction` — high-precision, low-recall: a
+match proves the same finding recurred; a mismatch does NOT prove it didn't (the same finding reworded
+fingerprints differently).
+
+## What the evaluator was actually shown — `evidenceBudget`
+
+Skill-authored content (`SKILL.md`, every `references/**` file, `agents/<skill>.md`) ships **WHOLE, not
+rationed** — up to a **512 KiB combined ceiling** across all three together. A breach cuts **loudly**: the
+named file and byte counts are reported, never silent, never refused. The **transcript** is bounded
+separately at **128 KiB**, cut **head+tail with an elided middle**, so a run's setup and its conclusion
+both survive a cut instead of just one end.
+
+The report's `evidenceBudget` object says exactly what was shown — read it instead of inferring budgets
+from `dist/` source:
+
+| Field | What |
+|---|---|
+| `corpusBytes` | total skill-content bytes found, BEFORE any cut |
+| `corpusCeiling` | the 512 KiB combined ceiling |
+| `corpusCuts` | per-file cut record — empty on every real skill; non-empty only once the ceiling is actually breached |
+| `corpusExcluded` | skill files present on the host but never delivered to the agent (see below) |
+| `trimRecord` | which section the transcript trim shaved, and by how much |
+| `packageTruncated` | `true` if ANY section was cut — check this, not `corpusCuts`, for "was anything trimmed": a transcript-only cut leaves `corpusCuts` empty and would otherwise read as "nothing cut" |
+
+## An untracked skill file is not graded
+
+Staging delivers **git-tracked files only** (same rule as a marketplace plugin install) — an untracked
+file under the skill folder was never in the agent's mount, so grading against it would manufacture a
+false `already-covered` verdict. It is named in `corpusExcluded` instead, and an untracked `SKILL.md`
+specifically reports `skillMdStatus: "untracked"`, forcing the mechanical `already-covered` →
+`not-adjudicable` downgrade. `git add` it (or commit before critiquing) if it should count as evidence.

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

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 1.12.0` (baseline `desktop-1.24012.9`).
+Self-contained reference. Tracks `cowork-harness 1.13.0` (baseline `desktop-1.24012.9`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 
@@ -131,7 +131,7 @@ So a helper keys its answer on `questions[N].question`, enumerates choices from
 The `reply_with` field is a literal fill-in template for the reply shape (array placeholder when
 multiSelect). Notes: `options` is *optional* — a free-text / header-only gate arrives with no
 `options`; key off `question` (falling back to `header`). This is the shared wire model for both
-channels — `docs/decider-dir.md` shows the same shape, and the Python `serve_decider(fn)` adapter
+channels — [`docs/decider-dir.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/decider-dir.md) shows the same shape, and the Python `serve_decider(fn)` adapter
 hands `fn` exactly this dict.
 
 ### `--on-unanswered` accepted values (precise)
@@ -207,7 +207,7 @@ up often enough to spell out:
   Everything else that *is* evaluated is checked against the **recording**, not fresh behavior — a
   green replay says the skill produced these events when it was recorded, not that it still does
   (`staleness[]` flags skill/baseline drift as a hint; only a live `run` re-confirms current
-  behavior). See `docs/cassette.md` § "Still skipped on replay" and `docs/scenario.md` § "Which
+  behavior). See [`docs/cassette.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/cassette.md) § "Still skipped on replay" and [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md) § "Which
   assertions survive replay."
 - **Container-only assertions can't verify off the `container` tier.** `no_scratchpad_leak` and
   `present_files_called` check the `present_files` delivery path, which is served **only** on
@@ -222,7 +222,7 @@ up often enough to spell out:
   class of Cowork bug (a client-side write-back to a relative URL that resolves-but-fails against
   Cowork's own origin, or a broken blob-download fallback) is invisible to any live run, however
   faithfully sandboxed, because it only manifests in a rendered DOM a human is driving. See
-  `docs/fidelity-gaps.md` § "Browser↔webview↔human-interaction boundary."
+  [`docs/fidelity-gaps.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/fidelity-gaps.md) § "Browser↔webview↔human-interaction boundary."
 
 ## Relevant environment variables
 

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

@@ -1,8 +1,8 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.12.0`
-(baseline `desktop-1.24012.9`). If your checkout is newer, prefer the live `docs/scenario.md`,
-`docs/session.md`, and `SPEC.md`.
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.13.0`
+(baseline `desktop-1.24012.9`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
+[`docs/session.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md), and `SPEC.md`.
 
 **Minimal scenario** — `prompt` is the only required field:
 
@@ -94,10 +94,12 @@ session = your setup.**
 # model & reasoning
 model: claude-opus-4-8           # omit for the agent default
 account_name: my-account         # OPTIONAL — display name rendered into {{accountName}} / the prompt's
-                                    # "User name:" line; NOT a credential/identity selector (see src/prompt.ts, docs/session.md)
+                                    # "User name:" line; NOT a credential/identity selector (see src/prompt.ts,
+                                    # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md)
 effort: high                     # low | medium | high | xhigh | max (+ extra, normalized to xhigh); validated against
-                                  # the resolved model's offered levels (docs/session.md); omit for Cowork's medium
-                                  # fallback — real Cowork always emits --effort, never omits it
+                                  # the resolved model's offered levels
+                                  # (https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md);
+                                  # omit for Cowork's medium fallback — real Cowork always emits --effort, never omits it
 extended_thinking: true          # real Cowork on/off toggle; default true (ON) -> --max-thinking-tokens 31999,
                                   # or --thinking disabled when false (no arbitrary budget in real Cowork)
 agent_max_turns: 500              # optional turn ceiling -> agent --max-turns; omit for the agent default

package/.claude/skills/cowork-harness/references/task-recipes.md

@@ -2,7 +2,7 @@
 
 Each recipe composes facts that live scattered across SKILL.md and the other references into one
 decision path. Every one answers a question a real fleet owner had to work out the hard way.
-Tracks `cowork-harness 1.12.0` (baseline `desktop-1.24012.9`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 1.13.0` (baseline `desktop-1.24012.9`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
 Recipe 3's `init-redact` shipped in 0.24.0 and are part of the current feature set — no version gate
 needed if your CLI meets SKILL.md's version floor.
 
@@ -178,13 +178,14 @@ Hardening a skill is a loop: run → read what it did → fix → run again. Two
    `--resume` (both pin one run dir) and `--decider-cmd`/`--decider-dir` (a driving agent x N is not a
    measurement).
    The full loop (harvest -> reproduce -> fix -> prove freshness -> compare) is written out end-to-end in
-   docs/debugging.md under "The whole loop, end to end". The harness now SHIPS a grader — `cowork-harness critique <skill-folder> --prompt "<probe>"` runs the
+   [docs/debugging.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/debugging.md) under "The whole loop, end to end". The harness now SHIPS a grader — `cowork-harness critique <skill-folder> --prompt "<probe>"` runs the
    skill, asks the agent what confused it, and grades that self-report against a frozen record of the run
    (blinded evaluator + mechanical citation checking). **Critiquing a document-analysis skill?** The probe
    attaches nothing on its own — pass `--upload <path>` (repeatable) or `--folder <dir>` exactly as you
    would to `skill`, or the graded run has no file and "there was no file attached" is the correct finding,
    not a skill defect. Source flags reach both spawned turns automatically — see SKILL.md's
-   floor list. See docs/critique.md for the full flag table, cost and limits. If you
+   floor list. See [docs/critique.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/critique.md) for the full flag table, cost and limits (or the shipped
+   [`references/critique.md`](./critique.md) for the report/evidence-package shapes without leaving the plugin payload). If you
    prefer to build your own grader, the substrate is still here:
    - `result.json` → `finalMessage` (the skill's own answer/critique) + `toolResults[]` (tool outputs).
    - `cowork-harness trace <run-dir> --output-format json` → the tool-call stream. Add `--full-results` so

package/.claude/skills/cowork-harness/scripts/scenario.py

@@ -1400,7 +1400,11 @@ def main(argv=None):
     )
     # The wrapper (`cowork-harness lint`) sets COWORK_HARNESS_PROG so usage/error lines name a command the
     # user can actually run. Default = the script's own basename, because scenario.py is ALSO documented as
-    # directly runnable (SKILL.md, docs/gotchas.md, docs/plugin-root.md, docs/subagents.md) — hardcoding
+    # directly runnable (SKILL.md;
+    # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/gotchas.md,
+    # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/plugin-root.md,
+    # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/subagents.md — repo-only, not
+    # shipped with the installed skill) — hardcoding
     # "cowork-harness lint" would lie on that path.
     prog = os.environ.get("COWORK_HARNESS_PROG")
     sub = ap.add_subparsers(dest="command", required=True)
@@ -1505,6 +1509,15 @@ def main(argv=None):
     args, extras = ap.parse_known_args(argv)
     if extras:
         target = sub.choices.get(getattr(args, "command", "") or "")
+        # `--min-severity` is `lint`-only (it filters lint's severity-classed findings; `lint-skill`'s two
+        # footgun checks have no severity ladder to filter). Passing it to `lint-skill` used to fall through
+        # to the bare "unrecognized arguments" message below and leave the user hunting for a flag that DOES
+        # exist, just on the sibling command — name it explicitly, same as the `--output-format` translation
+        # `runLintLike` (src/run/scenario-tool.ts) already does for the other lint/lint-skill flag mismatch.
+        if getattr(args, "command", None) == "lint-skill" and any(
+            e == "--min-severity" or e.startswith("--min-severity=") for e in extras
+        ):
+            (target or ap).error("unrecognized arguments: " + " ".join(extras) + " (--min-severity is a `lint` flag, not `lint-skill` — rerun with `cowork-harness lint` instead)")
         (target or ap).error("unrecognized arguments: " + " ".join(extras))
     return args.func(args)
 

package/AGENTS.md

@@ -136,7 +136,12 @@ the narrow case of advancing a branch nobody has checked out — it just cannot
 `main` itself, so the base can still move under an in-flight rebase. Separate worktrees fix that half.
 
 **Two one-time costs per worktree**, both benign: no `./.env` (use `--dotenv <primary>/.env` — `doctor`
-detects this and prints the remedy, see `docs/gotchas.md`), and no `node_modules` (`npm ci` before tests).
+detects this and prints the remedy, see `docs/gotchas.md`), and no `node_modules` — run **`npm ci`**.
+
+**Do NOT symlink `node_modules` from the primary** to skip that install. `.gitignore`'s first line is
+`node_modules/` — with a trailing slash, so it matches a *directory* only. A symlink is not a directory to
+git, so it shows up as `?? node_modules` and breaks every clean-tree gate, `npm run preflight` included.
+Verified both ways: a real `node_modules/` directory is correctly ignored; a symlink is not.
 
 **Structural safety, not just etiquette:** git refuses to check out `main` in a second worktree
 (`fatal: 'main' is already used by worktree at …`), so the integration branch cannot be double-held by

package/CHANGELOG.md

@@ -6,6 +6,162 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.13.0] — 2026-07-28
+
+**Upgrade notes.**
+
+- **`critique` verdicts are not comparable across this release — but the counts still are, and that
+  distinction decides what to do with your history.** The evaluator now sees materially more of your skill,
+  so a *per-item* verdict may flip for reasons that have nothing to do with your edits: do not diff
+  individual findings across the boundary, and re-baseline anything that tracks a skill's progress
+  report-to-report. **Do NOT discard your pre-upgrade reports.** Aggregate counts — above all the
+  `not-adjudicable` count on identical prompts — remain the right way to measure what this release did,
+  and your archived reports are the only "before" that exists. Pair that with the
+  `citationResolved:false` (DROPPED) rate, which is the guard in the other direction: a much larger corpus
+  could make the evaluator's citations sloppier, and nothing else would show it.
+- **`skillMdTruncated` is gone from `critique-report.json`**, replaced by `evidenceBudget`
+  (`corpusBytes` / `corpusCeiling` / `corpusCuts` / `corpusExcluded` / `trimRecord`). A harvester reading
+  the old boolean should read `evidenceBudget.corpusCuts` instead — it is empty on every real skill.
+- **An untracked skill file is no longer graded**, and the two cases behave differently — do not read one
+  as the other:
+  - **Untracked `references/**` or `agents/<skill>.md`** are simply excluded, named in
+    `evidenceBudget.corpusExcluded`, and announced with a `::warning::`. **This does NOT force
+    `not-adjudicable`** — and it should not: the agent never received those files either, so the
+    evaluator's view now MATCHES the agent's. A finding like "the skill never explains X" against an
+    excluded reference is correctly `grounded`; before this release the evaluator could see the file the
+    agent never got and mark that true finding `already-covered`.
+  - **An untracked `SKILL.md`** previously had its content **graded** (the packager read the host directory
+    raw). It now reports `skillMdStatus: "untracked"`, withholds the content, and **does** force the same
+    `not-adjudicable` downgrade as an unreadable one — coverage claims cannot be judged with no skill source
+    at all.
+  Either way, `git add` before critiquing to grade as-published.
+
+### Fixed
+
+- **Every `docs/*.md` pointer in the shipped skill was dead for a plugin install.** A plugin install
+  materializes only `.claude/skills/<name>/**`; `docs/` ships in the npm tarball and not in that payload.
+  The skill referenced `docs/` pages **25 times across 13 targets** anyway, so a consumer following one
+  found nothing. This cost real time: `critique-evidence-package.txt` — the corpus the evaluator actually
+  graded — was documented only in `docs/critique.md` and named nowhere a plugin user could see, so its
+  behaviour got reverse-engineered from compiled `dist/` instead. All 25 are now repo permalinks that
+  resolve for tarball and plugin users alike, a trimmed `references/critique.md` ships inside the payload
+  covering what a plugin install cannot otherwise reach, and **`npm run check:skill-doc-links` fails CI on
+  any new dangling reference** — the durable half, without which the next release re-creates them.
+  Reported by a consumer.
+- **`lint-skill --min-severity` exited 2 with no explanation.** The flag belongs to `lint`; the error now
+  names the sibling command instead of leaving you to diff two help texts.
+- **`index.jsonl` under-reported a critique's cost by ~39%.** A critique is four model workloads, but only
+  the two graded turns produce a run and therefore a row — the two evaluator passes are direct API calls
+  that produce neither. Anything summing the index missed them entirely (measured: $10.17 indexed against
+  $16.67 actual across three runs), and the index is the only cost record that survives run-dir pruning, so
+  spend trends built from it were systematically light. Each critique now writes one roll-up row carrying
+  `critiqueTotalUsd`, and `--reindex` reconstructs it from the run dir's `critique-report.json` so a lost
+  index recovers critique costs too. The roll-up's own `costUsd` is the **evaluator passes only**, so
+  `sum(costUsd)` across all rows is exactly true spend — neither double-counted nor short. Roll-ups are
+  excluded from `stats` aggregation, where they would otherwise add a phantom run and inflate `passRate`.
+  Reported by a consumer.
+
+  **Sharing a runs root across CLI versions:** an *older* CLI's `--reindex` deletes these roll-up rows —
+  its supersede clause drops any prior row without a `turn`, which a roll-up is. Re-run `--reindex` with a
+  current CLI to restore them from the run dirs.
+- **A critique was indistinguishable from a plain `skill` run in the index**, which recorded the *inner*
+  command for both turns and carried no `skill` field despite `--skill`. With three concurrent critiques of
+  three skills against one plugin, every row read `scenario: skill-<plugin>` and the only way to tell them
+  apart was opening each run dir. Rows now carry `critiqueRole` (`task` / `reflection` / `rollup`) and the roll-up carries
+  `skill`. These are **additive-optional fields, not a new `command` value**: the row validator hard-codes
+  the command allowlist, so widening it would make an older CLI quarantine every critique row and drop it
+  from `stats`. The role derives from critique's own session-id shape, so `--reindex` marks rebuilt rows too.
+- **`critique`'s task-turn timeout was 10 minutes**, which a sub-agent-dispatching skill routinely exceeds.
+  The turn is killed *after* its model spend, so the consumer paid for a graded run and received an
+  instrument failure instead of a critique — a reported case burned $11.05 that way. Raised to 30 minutes,
+  matching the evaluator transport; `--timeout` still raises it further, and the byte cap and process-group
+  kill remain the real runaway guards.
+
+
+- **`critique` graded skills against a fraction of their own references.** The evidence package shared one
+  8 KiB budget across ALL `references/**` files, filled in filename-sort order — so the alphabetically
+  first file took what it needed and every later file was dropped whole. Measured across nine real runs on
+  a six-skill plugin: the same first file was the sole survivor in 9 of 9, and **11 of 13 distinct
+  reference files had never reached an evaluator in any run**, including a scoring rubric a sub-agent had
+  opened in order to do the scoring. Skill-authored content (SKILL.md, every `references/**` file,
+  `agents/<skill>.md`) now ships **whole** — bounded only by a **512 KiB sanity ceiling across all three
+  combined**, which no real skill approaches (the largest measured is ~164 KB, about a third of it). A skill
+  that does breach it is cut **loudly and by name** in `evidenceBudget.corpusCuts` — never silently, and
+  never by refusing the run. The transcript is bounded separately at 128 KiB. Reported by a consumer.
+- **The evidence corpus could contain files the agent never received.** Staging delivers git-tracked files
+  only, but the packager read the host directory directly — so an uncommitted reference was absent from
+  the mount and present in the evaluator's evidence. An agent saying "the skill never explains X" could be
+  marked `already-covered` against a file it was never given. The packager now applies staging's own
+  tracked-set filter and reports what it excluded.
+- **`references/**` traversal was neither recursive nor symlink-aware**, so nested and symlinked reference
+  files were dropped silently, with no omission marker.
+- **The overall package trim did not converge.** It shaved a section by exactly the overflow and then
+  appended a truncation marker, leaving the package marker-length over; it then shaved the next section by
+  that amount and re-added the same marker, cascading through every section and exiting still over cap
+  with the whole document mangled. It remains a belt-and-suspenders path that should never fire — the
+  per-section budgets still sum under the cap, now pinned by a test — which is exactly why it had to be
+  correct: nothing exercises it until something else has already gone wrong.
+- **The overall trim destroyed the run record first.** It shaved from the last section backwards, which is
+  the transcript — so a breach caused by oversized *skill* content was paid for by deleting *run*
+  evidence. Trim priority is now explicit and independent of render order.
+- **`writeSync` short writes and `EAGAIN` were unhandled at every stdout/stderr sink.** `verify-cassettes … | tail`
+  died with `EAGAIN` instead of printing its verdict, and a short write on a pipe silently dropped the
+  remainder of a JSON envelope. Every `writeSync` output site in `src/` now goes through `writeAllSync`, including critique's own JSON report — the largest single payload the tool emits, and the one its own code comment already flagged as at risk when piped to `jq`. (Sites already using async `process.stderr.write`, and two dev-only sinks under `scripts/`, are unchanged — the failure was specific to the synchronous idiom.)
+
+### Documentation
+
+- **`turn` vs `turns` in `index.jsonl` is now explained.** The names invite reading `turn: 2, turns: 1` as
+  "turn 2 of 1". They are unrelated: `turn` is the position within a resumed session, `turns` is the count
+  of agent turns *inside* that one run, and neither bounds the other. A critique roll-up carries neither,
+  since it accounts for workloads that are not runs. Documented rather than renamed — a rename breaks
+  `stats` and would need a schema version bump for no behavioural gain. Reported by a consumer.
+
+**Cost note.** Sending the whole corpus costs more per critique, not less: roughly **+5% to +18%** on a
+~$5.60 run, scaling with how much of your skill was previously being cut (a skill whose SKILL.md sat under
+the old 64 KiB cap and had few references sees almost nothing; one that was heavily truncated sees the top
+of the range). Evidence input was only ~14% of an evaluator pass's cost to begin with, which is why the old
+caps were rationing the cheap term — but it is an increase, and a batch budget should carry it.
+
+### Added
+
+- **`session.json` now identifies its own run.** The resume manifest (written for `--session-id`/`--resume`
+  runs) held only opaque ids, so the file whose name makes it the first thing you open in a run dir
+  answered nothing — with several concurrent runs against one plugin there was no way to tell which was
+  which without opening each turn's `result.json`. It now also carries `scenario` and `prompt`. These are
+  **additive-optional**: nothing validates them, and a manifest written before this still resumes.
+  `result.json` remains authoritative for identity; this is a signpost, not a second source of truth.
+  Reported by a consumer.
+- **`critique` reports progress.** Four `::notice::` lines on stderr at the phase boundaries (task turn →
+  reflection turn → evaluator pass 1 → evaluator pass 2). Previously four model calls over 10–20 minutes
+  produced no output at all until the finished report appeared, so a working run and a hung one were
+  indistinguishable. stdout remains the machine channel.
+- **`costUsd` now reports the evaluator passes' token split** (`evaluatorPass1Tokens` /
+  `evaluatorPass2Tokens`, each `{input, output, cacheRead}`). The transport always handed the harness the
+  full usage object and it was summed to a dollar figure and discarded — so the report said what a pass
+  COST and never why, and "is this money evidence or thinking?" was unanswerable from any artifact the tool
+  produced. That is the question that decides whether sending more evidence is cheap, which makes it the
+  number to check first when budgeting a batch under the whole-corpus change above.
+- **`evidenceBudget` in `critique-report.json`** — what the evaluator was actually shown, so the budgets
+  are discoverable without reading compiled source. Includes `packageTruncated`, which is what carries the
+  transcript's head+tail elision: that elision is what adds the evaluator's truncation caveat, and without
+  the flag an elided package was indistinguishable from a clean one (`corpusCuts` is empty in that case and
+  would otherwise imply nothing had been cut).
+- **A no-reads signal** (`noSkillFilesRead`). When the graded turn Read no `references/` or `scripts/`
+  file at all — neither the main agent nor any sub-agent — the report says so. Worded observationally on
+  purpose: the underlying predicate counts the `Read` tool only, so `Grep` or `assets/` use produces an
+  empty set having demonstrably reached the material, and calling that "progressive disclosure never
+  fired" would be a false accusation about someone's skill.
+
+### Changed
+
+- **The overall evidence-package cap is 144 KiB → 768 KiB** (`critique --help` reports it). It stays a
+  belt-and-suspenders bound: the per-section budgets deliberately sum under it, pinned by a test.
+- **The transcript bound is 32 KiB → 128 KiB and now keeps head *and* tail** with an elided middle.
+  A tail-only cut is the worst shape for a procedural skill, which puts its workflow steps last.
+- **`critique`'s evaluator passes get a 30-minute transport timeout** (was the decider's 600 s default).
+  That timeout is enforced with SIGKILL and no retry, so a kill during pass 1 discarded the whole critique
+  *after* the graded turns had already been paid for.
+
 ## [1.12.0] — 2026-07-25
 
 **Upgrade notes.**

package/CONTRIBUTING.md

@@ -27,7 +27,7 @@ Extra prerequisites for specific stages:
 - **Lima (`limactl`, macOS arm64)** — required only for the **L2 `microvm`** tier and the `vm` commands; the guest runs on Apple Virtualization.framework (`vmType: vz`). `microvm` does **not** use Docker. (`cowork-harness doctor --tier microvm` checks for Lima, not Docker.)
 
 CI Stage 1 (the `build` job in `.github/workflows/ci.yml`) does **not** invoke `npm run ci`. It runs the
-gate steps individually — e.g. `check:versions`, `format:check`, `typecheck`, `build`, a CLI smoke
+gate steps individually — e.g. `check:versions`, `check:skill-doc-links`, `format:check`, `typecheck`, `build`, a CLI smoke
 (`node dist/cli.js list`), three token-free `replay` gate fixtures, `verify-cassettes`, `lint`, and
 source-guard checks — while the unit suite runs separately as the 4-shard `test` job (see `ci.yml` for
 the authoritative list). Only `release.yml` calls `npm run ci`. For a copy-paste GitHub Actions setup,