cowork-harness 1.13.0 → 1.13.2

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.13.0
-  tracks-harness: cowork-harness 1.13.0 (baseline desktop-1.24012.9)
+  version: 1.13.2
+  tracks-harness: cowork-harness 1.13.2 (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.13.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 1.13.2` (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.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.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 1.13.2**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.13.2" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.13.2"`. **Pin `@>=1.13.2`, 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)
@@ -63,6 +63,12 @@ reproducible regression (Part II), and **debug** a run that misbehaved or greene
 - **Regression-test your skill's ANSWER quality** (not just its behavior — does its guidance still lead to
   correct answers after you edit it?) → author `semantic_matches` scenarios and gate on the per-claim
   profile. See **Recipe 5** in `references/task-recipes.md` (validity, N≥3, discrimination — the traps).
+- **"What is WRONG with this skill?"** (a graded critique, not a pass/fail) → `cowork-harness critique
+  <folder> --prompt "<probe>"`. Four model workloads and 10–20 minutes; budget from
+  `report.costUsd.totalUsd`. Reach for it when you want **findings**. **For "what does this skill
+  **DO**" — routing, artifact location, narration — use `skill` instead**: no evaluator, a fraction of
+  the cost, and it answers that question directly. Report and evidence-package shapes:
+  `references/critique.md`.
 - **A run failed — or greened and you don't trust it** (the debugging loop) → don't re-run and hope.
   The run already wrote its evidence to a **kept run dir** (`~/.cowork-harness/runs/…`; `--keep` prints
   the path, `trace <run-id>` finds it). **Localize the failure post-hoc** from that evidence:
@@ -71,6 +77,9 @@ reproducible regression (Part II), and **debug** a run that misbehaved or greene
   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`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/debugging.md) — repo-only, not shipped with the installed skill).
+  **"Evidence" here means the RUN's own record** — events, trace, transcript. `critique`'s evaluator
+  grades against a different artifact, `critique-evidence-package.txt`, which none of these tools
+  surface; see `references/critique.md`.
 - **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**).
 
@@ -515,7 +524,7 @@ decide which assertions from *Assertions: two orthogonal axes* are worth adding)
   `outputTruncated` on a matched tool result). Three separately-shaped rollups, easy to conflate in a
   `jq` recipe: `toolCounts` is a flat `{tool: number}` call-count map, `toolErrors` is
   `{tool: {calls, errors}}`, and `toolDurations` is `{tool: {calls, totalMs, maxMs}}`. (Full per-field
-  semantics: the README's "Observability fields" section — repo-only; `schema/run-result.json` is the
+  semantics: the README's "Observability fields" section — repo-only; [`schema/run-result.json`](https://github.com/yaniv-golan/cowork-harness/blob/main/schema/run-result.json) is the
   machine source.)
 - **Opaque failure?** A failed run also records **`errorSource`** (where the failure originated) and
   **`stderrLogPath`** (the captured agent stderr) — read those and `trace <run-dir>` *before* re-running;

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.13.0` (baseline `desktop-1.24012.9`).
+Self-contained reference. Tracks `cowork-harness 1.13.2` (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.13.0"`) for reproducible CI.
+release; pin an exact version (e.g. `version: "1.13.2"`) 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
@@ -58,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.13.0"
+- run: npm i -g "cowork-harness@>=1.13.2"
 - 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
@@ -222,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.13.0"
+      - run: npm i -g "cowork-harness@>=1.13.2"
       - 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
@@ -251,7 +251,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=1.13.0"
+        run: npm i -g "cowork-harness@>=1.13.2"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:
@@ -280,7 +280,7 @@ JSON.
 
 `verify-cassettes` emits its **own** envelope (`{command, ok, coverage, results[]}` with per-file
 `findings`/`staleness`/`unverifiable`/`notes`/`version`/`error`), published as
-`schema/verify-cassettes.json` in the npm package. `ok:false` doesn't say *why* — read the buckets, or
+`schema/verify-cassettes.json` in the npm package. `ok:false` doesn't say *why* — read the buckets, or <!-- npm-only-ok -->
 the exit code (`1` = `findings`/`staleness`/`scenarioDrift` populated, a real problem verified & found;
 `3` = `unverifiable`/`version`/`error` populated, verification could not complete; a real finding wins
 `1` if both are present). Both envelope schemas are covered 1.0 contract surfaces (SPEC §12) — parse the

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

@@ -1,6 +1,6 @@
 # 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
+Tracks `cowork-harness 1.13.2` (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
@@ -51,6 +51,14 @@ named file and byte counts are reported, never silent, never refused. The **tran
 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.
 
+You do not need a paid run to find out where you stand: **`cowork-harness lint-skill <skill-dir>` sizes
+your corpus against the same ceiling**, reporting `skill-corpus-near-evidence-ceiling` (INFO) from 80%
+and `skill-corpus-over-evidence-ceiling` (WARN, so it fails `--strict`) past it. It counts the three
+classes the ceiling governs — `SKILL.md`, every file under `references/` (**any extension**: the packager
+applies no extension filter, so JSON schemas and rule packs count toward your total), and a plugin
+skill's `agents/<name>.md`. It does not apply staging's git-tracked filter, so an untracked reference
+inflates the figure; `corpusCuts` below stays the authority.
+
 The report's `evidenceBudget` object says exactly what was shown — read it instead of inferring budgets
 from `dist/` source:
 
@@ -70,3 +78,17 @@ file under the skill folder was never in the agent's mount, so grading against i
 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.
+
+## `referencesRead` is main-agent-only — `noSkillFilesRead` is not
+
+`result.json`'s top-level `referencesRead` lists **main-agent Reads only**. A dispatcher-style skill does
+its reading one level down, and those Reads live under `subagents[].referencesRead` — so an empty
+top-level list on a sub-agent-heavy run is not evidence the material went unread. The critique report's
+**`noSkillFilesRead`** unions both, which is why it is the signal to read.
+
+It is stated **observationally** and must be rendered that way: the predicate matches `references/` and
+`scripts/` only — never `assets/`, never `SKILL.md` (delivered whole, never Read as a file) — and keys on
+the `Read` **tool**. A skill that reached its material with `Grep`, or kept it under `assets/`, reports
+`true` having demonstrably done the work. `undefined` has **two** causes and neither means "nothing was read": a degraded turn-1 result
+(genuinely unknown), or a skill that ships no `references/` and no `scripts/` at all — there is nothing
+for the signal to be about, so emitting it would be noise about material that does not exist.

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.13.0` (baseline `desktop-1.24012.9`).
+Self-contained reference. Tracks `cowork-harness 1.13.2` (baseline `desktop-1.24012.9`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 
@@ -171,10 +171,12 @@ catch a non-matching regex or a wire-protocol bug before twelve minutes of live
 cowork-harness decide \
   --question "Which output format do you want?" \
   --option Markdown --option PDF \
-  --answer-policy examples/answer-policies/demo.yaml
+  --answer-policy ./answer-policy.yaml
 # ✓ rule matched: "Which output format do you want?" → "Markdown"
 ```
 
+A ready-made sample to copy: [`examples/answer-policies/demo.yaml`](https://github.com/yaniv-golan/cowork-harness/blob/main/examples/answer-policies/demo.yaml).
+
 It works with `--answer`/`--answer-policy` (reports which rule matched, or exits non-zero if none),
 `--decider-cmd` (shows the exact request + answer), or `--decider-llm` (a live model answers).
 Caveat: `decide` only builds a **single-select** sample (set choices with `--option`; there is no

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 1.13.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.13.2`
 (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`.
 

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.13.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.2` (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.
 
@@ -48,7 +48,7 @@ what production would do. Two layers of defense:
 
 ### Cassette anatomy (what you're looking at when you open one)
 
-Top-level fields of a `*.cassette.json` (schema `schema/cassette.v10.json`):
+Top-level fields of a `*.cassette.json` (schema [`schema/cassette.v10.json`](https://github.com/yaniv-golan/cowork-harness/blob/main/schema/cassette.v10.json)):
 
 | Field | What it is |
 |---|---|

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

@@ -1197,6 +1197,75 @@ def _resolve_skill_targets(arg):
     return None, []
 
 
+# Mirrors SKILL_CORPUS_CEILING in the packager (src/critique/package-evidence.ts). A cross-language
+# test pins the two together, so change both or the test fails.
+_EVIDENCE_CORPUS_CEILING = 512 * 1024
+# Warn well before the valve: a corpus this close is one reference file away from being cut mid-grade.
+_EVIDENCE_CORPUS_NOTICE_RATIO = 0.8
+
+
+def _lint_skill_corpus_size(md_path):
+    """Total skill-authored bytes against the critique evidence ceiling.
+
+    Counts the SAME THREE CLASSES the ceiling governs: SKILL.md, every file under references/ (any
+    extension -- the packager applies no extension filter, so JSON schemas and rule packs count), and,
+    for a skill inside a multi-skill plugin, the invoked skill's <root>/agents/<name>.md.
+
+    Omitting the agents md is not a rounding error: a plugin whose SKILL.md + references sit in the INFO
+    band while the agents md carries the corpus past the ceiling reported INFO and PASSED --strict on
+    content the packager would cut. A proximity check that greens a corpus destined to be cut is worse
+    than no check.
+
+    Still approximate in ONE direction only, and it now over- rather than under-counts: the packager
+    applies staging's git-tracked filter, so an untracked reference inflates this figure. That errs
+    toward warning early. The report's corpusCuts stays the authority."""
+    skill_dir = Path(md_path).parent
+    total = 0
+    files = [Path(md_path)]
+    refs = skill_dir / "references"
+    if refs.is_dir():
+        files.extend(p for p in sorted(refs.rglob("*")) if p.is_file())
+    # Multi-skill plugin layout: skillDir is <root>/skills/<name> and the invoked skill's sub-agent
+    # system prompt is <root>/agents/<name>.md -- the same resolution the critique command performs.
+    # A standalone skill (no `skills/` parent) has no agents md and is unaffected.
+    if skill_dir.parent.name == "skills":
+        agents_md = skill_dir.parent.parent / "agents" / f"{skill_dir.name}.md"
+        if agents_md.is_file():
+            files.append(agents_md)
+    for p in files:
+        try:
+            total += p.stat().st_size
+        except OSError:
+            continue  # unreadable file: same posture as the packager's per-file degrade
+    pct = total * 100.0 / _EVIDENCE_CORPUS_CEILING
+    if total > _EVIDENCE_CORPUS_CEILING:
+        return [
+            Finding(
+                "WARN",
+                "skill-corpus-over-evidence-ceiling",
+                f"skill content is {total:,} B ({pct:.0f}% of the {_EVIDENCE_CORPUS_CEILING:,} B critique "
+                f"evidence ceiling) — a critique will cut it before grading.",
+                "Split or trim the largest references/ files. This counts SKILL.md + references/** + "
+                "agents/<skill>.md, the same three classes the ceiling governs; it does not apply "
+                "staging's git-tracked filter, so an untracked reference inflates it. The critique "
+                "report's corpusCuts names exactly which files lose bytes.",
+                str(skill_dir),
+            )
+        ]
+    if total >= _EVIDENCE_CORPUS_CEILING * _EVIDENCE_CORPUS_NOTICE_RATIO:
+        return [
+            Finding(
+                "INFO",
+                "skill-corpus-near-evidence-ceiling",
+                f"skill content is {total:,} B ({pct:.0f}% of the {_EVIDENCE_CORPUS_CEILING:,} B critique "
+                f"evidence ceiling).",
+                "No action needed yet; adding a large reference file would push a critique into cutting content.",
+                str(skill_dir),
+            )
+        ]
+    return []
+
+
 def cmd_lint_skill(args):
     all_findings = []
     n_files = 0
@@ -1218,6 +1287,7 @@ def cmd_lint_skill(args):
             md_lines = Path(md).read_text(encoding="utf-8").splitlines()
             all_findings.extend(_lint_skill_text(md, md_lines))
             all_findings.extend(_lint_subagent_types(md, md_lines))
+            all_findings.extend(_lint_skill_corpus_size(md))
         for hp in hooks:
             n_files += 1
             all_findings.extend(

package/CHANGELOG.md

@@ -6,6 +6,88 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.13.2] — 2026-07-28
+
+### Fixed
+
+- **`lint-skill`'s corpus check sized a smaller set than the ceiling it warns about, and could pass
+  `--strict` on a corpus a critique would cut.** The evidence ceiling governs `SKILL.md` + `references/**`
+  + `agents/<skill>.md` **combined**; the check summed only the first two. A multi-skill plugin whose
+  SKILL.md and references sat in the INFO band while its `agents/<name>.md` carried the total past the
+  ceiling reported INFO and **exited 0 under `--strict`** — a green gate on content that was already
+  destined to be cut. The check now counts all three classes, resolving `<root>/agents/<name>.md` the same
+  way `critique --skill <name>` does; a standalone skill (no `skills/` parent) is unaffected.
+
+  Two clarifications that follow, because both were understated: every file under `references/` counts
+  regardless of extension — the packager applies **no** extension filter, so JSON schemas and rule packs
+  are part of your corpus — and the remaining approximation now errs in one direction only. The check
+  skips staging's git-tracked filter, so an untracked reference inflates the figure and warns early
+  rather than late. `corpusCuts` in the report remains the authority.
+
+  Reported by a consumer, who caught it by measuring their own plugin against the new check on upgrade.
+
+## [1.13.1] — 2026-07-28
+
+### Fixed
+
+- **A misplaced global flag written as `--dotenv=<path>` / `--run-dir=<path>` keeps its exact-fix hint.**
+  The pre-dispatch guard matches the spaced form by exact token — deliberately, so a per-command value
+  like `--answer "--dotenv=x=foo"` is never hijacked — which left the equals form to surface as a bare
+  `unknown flag`, dropping the one thing the caller needed: where to put it instead. The hint is derived
+  where usage errors are rendered, and `run` additionally rejects a stray global ahead of its scenario
+  path — that ordering previously absorbed the flag as the target and reported the user's *correct* path
+  as the unexpected argument. The trigger is anchored on the two message shapes that mean "parsed as an
+  unrecognized flag": a broader match fires on errors about a *correctly-placed* leading flag
+  (`--dotenv file not found`, `--dotenv requires a path`) and on a flag name inside a quoted value,
+  telling the user to move a flag that is already in the right place.
+
+  Coverage is most of the CLI, not all of it. A command that never reaches that rendering point
+  (`critique`, `chat`, `prune`, `migrate-run-dir`) or whose usage message is shaped differently (`vm`, a
+  bare `assertions`, and `lint`/`lint-skill`, which forward the token to Python argparse) keeps its own
+  bare `unknown flag` message.
+
+- **The shipped-skill pointer guard covers `schema/` and `examples/`, not `docs/` alone.** A plugin
+  install materializes only `.claude/skills/<name>/**`, so a bare pointer to any other repo directory
+  dangles the same way — including the one naming the machine-readable schema a consumer needs to read
+  field semantics. Four live pointers rewritten to permalinks or made runnable. `scripts/`, `cassettes/`
+  and `src/` stay out of scope: the first resolves inside the payload, the second names the reader's own
+  directory in a recipe, the third is provenance. A line whose sentence already qualifies a pointer as
+  npm-only opts out with an explicit `<!-- npm-only-ok -->` marker.
+
+- **Pointer-guard and hint boundary cases.** The guard matched a path segment that was only the tail of
+  a longer word (`mydocs/x.md`), reported a wrong target for an extension outside its set (`docs/x.mdx`
+  as `docs/x.md`), missed an upper-case extension, and rejected any absolute URL that was not a GitHub
+  *blob* permalink — so an equally-resolvable `raw.githubusercontent` / GitLab / GitHub-`tree` link was
+  reported as a dead relative pointer, the checker refusing its own prescribed fix written another way.
+  The opt-out marker's whole-line scope is a deliberate trade-off and is now pinned by a test. Separately,
+  `.` is no longer a token terminator in the misplaced-flag match: a typo'd filename (`--dotenv.yaml`) was
+  read as the flag and answered with "move it before the subcommand".
+
+### Added
+
+- **`lint-skill` flags a skill corpus at or over the 512 KiB critique evidence ceiling** —
+  `skill-corpus-near-evidence-ceiling` (INFO, ≥ 80%) and `skill-corpus-over-evidence-ceiling` (WARN), so
+  the fact is free and static instead of costing a paid critique. The figure approximates the packager's
+  corpus — it excludes `agents/<skill>.md` and does not apply the tracked-set filter — which the finding
+  text states; `corpusCuts` in the report remains the authority. **CI note:** the over-ceiling finding is a
+  WARN, so a `lint-skill --strict` job that was green can now fail — which is the point, since that corpus
+  is one a critique would cut before grading.
+
+### Documentation
+
+- **`critique` is in the skill's orientation router, with the routing rule.** "What does this skill do"
+  is a `skill` question; "what is wrong with this skill" is a `critique` question, and the second costs
+  four model workloads. The router listed five entry points and `critique` was not among them.
+  Reported by a consumer.
+
+- **`referencesRead` is main-agent-only, stated inside the plugin payload.** Sub-agent Reads live under
+  `subagents[].referencesRead`, so an empty top-level list on a dispatcher-style skill is not evidence
+  the material went unread; the critique report's `noSkillFilesRead` unions both. Reported by a consumer.
+
+- **The run's own evidence and the critique evidence package are distinguished at the router and on the
+  debugging page**, not only mid-document — the first place a reader meets the word, rather than the
+  third. Reported by a consumer.
+
 ## [1.13.0] — 2026-07-28
 
 **Upgrade notes.**

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@>=1.13.0"`), point at the package root instead:
+> From a global install (`npm i -g "cowork-harness@>=1.13.2"`), 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@>=1.13.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.13.2"`.
 
 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@>=1.13.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.13.2"` (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@>=1.13.0"` — see
+above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@>=1.13.2"` — 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
@@ -411,7 +411,7 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 | `scaffold <run-id>` | Turn a kept run into a starter scenario YAML (gates→answers, artifacts→`file_exists`) | authoring a scenario from a real run instead of guessing |
 | `python3 …/scenario.py scaffold --name <name> --skill <dir>` | Generate a starter scenario skeleton from scratch (the `…` is `.claude/skills/cowork-harness/scripts/`) | starting a new scenario when you have no prior run |
 | `lint <scenario.yaml \| dir/>…` | Check scenarios for silent false-greens — assertions placed on the wrong CI lane, mixed content/live keys, missing `controlOut`-required keys (files or a directory of `*.yaml`/`*.yml`; bundled `scenario.py`; needs python3 — PyYAML is bundled); `--json` emits findings as machine-readable JSON instead of the text report; `--min-severity ERROR|WARN|INFO` drops findings below a floor **before** both the report and the exit computation (so `--strict --min-severity ERROR` behaves as a plain lint), which is the way to mute the unconditional INFO advisories in CI | before committing a new scenario or after changing assertions |
-| `lint-skill <SKILL.md \| skill-dir/>…` | Lint a skill body (and any sibling `hooks.json`) for two Cowork host-loop footguns — a `${CLAUDE_PLUGIN_ROOT}` path used in an in-VM bash context, and a hook command that exports an env var or writes into `/tmp` for the in-VM agent — plus static resolution of any pinned `subagent_type` against the enclosing plugin's `agents/*.md` (bundled `scenario.py`; needs python3); the two footguns are WARN-only, and of the three `subagent_type` outcomes, an in-plugin-prefixed agent missing from the enclosing plugin's fully-enumerated `agents/*.md` (`subagent-type-not-found-in-plugin`) is a **provable typo and is WARN too**, while a cross-plugin (`subagent-type-unresolvable`) or unknown-bare (`subagent-type-unknown`) value stays INFO (no built-in agent-type registry to disprove it against) — pass `--strict` (the CI-recommended invocation; plain `lint-skill` is advisory-only) to fail on any WARN, or `--json` for machine-readable findings | authoring or reviewing a skill before a paid Cowork host-loop run exposes the footgun, or before a pinned `subagent_type` typo breaks a `Task` dispatch |
+| `lint-skill <SKILL.md \| skill-dir/>…` | Lint a skill body (and any sibling `hooks.json`) for two Cowork host-loop footguns — a `${CLAUDE_PLUGIN_ROOT}` path used in an in-VM bash context, and a hook command that exports an env var or writes into `/tmp` for the in-VM agent — plus static resolution of any pinned `subagent_type` against the enclosing plugin's `agents/*.md` (bundled `scenario.py`; needs python3); the two footguns are WARN-only, and of the three `subagent_type` outcomes, an in-plugin-prefixed agent missing from the enclosing plugin's fully-enumerated `agents/*.md` (`subagent-type-not-found-in-plugin`) is a **provable typo and is WARN too**, while a cross-plugin (`subagent-type-unresolvable`) or unknown-bare (`subagent-type-unknown`) value stays INFO (no built-in agent-type registry to disprove it against); it also sizes the skill's own content — `SKILL.md` + every file under `references/` (any extension) + a plugin skill's `agents/<name>.md`, the same three classes the ceiling governs — against the 512 KiB `critique` evidence ceiling — `skill-corpus-near-evidence-ceiling` at ≥ 80% is INFO, and `skill-corpus-over-evidence-ceiling` past it is **WARN**, so a corpus a critique would cut fails `--strict` — pass `--strict` (the CI-recommended invocation; plain `lint-skill` is advisory-only) to fail on any WARN, or `--json` for machine-readable findings | authoring or reviewing a skill before a paid Cowork host-loop run exposes the footgun, or before a pinned `subagent_type` typo breaks a `Task` dispatch |
 | `python3 …/scenario.py resolve-agent-types <plugin-dir> [--json]` | Token-free: print a plugin's valid `<plugin>:<agent>` subagent types, resolved from `.claude-plugin/plugin.json` + `agents/*.md` frontmatter (filename-stem fallback when an agent file has no `name:`); the `…` is `.claude/skills/cowork-harness/scripts/` | "does `founder-skills:deck-review` resolve within this plugin?" without a live dispatch |
 | `analyze-skill <SKILL.md \| skill-dir/ \| glob>…` | Token-free ADVISORY scan: flags a `/sessions/...` path handed to a file tool or used as a dispatch/sub-agent output path — that path class is DENIED on host-loop. Accepts multiple positionals (files, dirs, or a simple `*`/`**` glob), walked recursively across a plugin's `SKILL.md`/`agents/`/`references/`/`commands/`. Findings print but exit 0 by default; `--strict` (the CI-recommended invocation) fails on any unsuppressed finding. Three per-file ignore markers (`ignore-next-line`, `ignore-start`/`ignore-end`, file-wide `ignore`) and a `--output-format json` payload are supported. **It also flags interactive-artifact write-backs lost under Cowork**: it statically analyzes `.html`/`.js`/`.ts`/`.py` sources under the target for a relative `fetch`/XHR/`sendBeacon`/`<form method=post>` write-back that silently fails when the artifact is served from Cowork's own origin (`artifact-write-back-lost` gates under `--strict`; `artifact-write-back-suspect` is advisory; a candidate that can't be parsed is a could-not-verify exit `3`). `--runtime` adds an optional headless-DOM confirmation (needs `jsdom`) that *observes* the lost write-back. Full reference — ignore-marker syntax, directory-walk rules, JSON shape, and the artifact detector: [docs/subagents.md](./docs/subagents.md#static-path-fidelity-check-analyze-skill) | catching the exact "skill hands `/sessions/...` to a file tool" defect — or an artifact whose Submit silently fails under Cowork — statically, before paying for a live run to discover it |
 | `probe-dispatch <skill-dir> "<prompt>"` | Cheap single-dispatch mechanics probe: a THIN wrapper over `skill` (fidelity `container`/`microvm`/`hostloop`, default `hostloop`) that scopes a prompt to trigger ONE `Task` dispatch, then prints just that dispatch's `{resolvedAgentType, pathDenials, delivered}` — no new data model, a pure projection of the same `RunResult` `skill` already produces; `--expect-write <suffix>` narrows `delivered`; "one dispatch" is prompt-scoped, not enforced (`--output-format json` for machine consumption); also inherits the common decider/answer flags — `--decider-cmd`, `--decider-dir`, `--on-unanswered`, `--ablate-skill` | "did THIS dispatch resolve to the type I expect, avoid a path denial, and actually deliver its write?" without hand-writing a scenario or reading `trace --view dispatches` |
@@ -694,7 +694,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 `cowork-harness@>=1.13.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.13.2` 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 **seven-stage pipeline**. The **build** + **test** stages are 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/dist/cli.js

@@ -1264,6 +1264,15 @@ async function cmdRun(rawArgs) {
     const args = rawRest.filter((a) => a !== "--keep");
     if (keepRequested)
         log("note: `run` always keeps runs (under the runs root); --keep is a no-op here.");
+    // A leftover global-only flag is NOT a positional. `takeCommonFlags` has already consumed every real
+    // flag VALUE, so a `--dotenv=`/`--run-dir=` token surviving to here is provably a misplaced flag rather
+    // than someone's argument. Letting it fall through made `args[0]` the FLAG and the user's real scenario
+    // path the "unexpected argument(s)" — blaming the one token that was correct, and in the no-other-arg
+    // case reporting `scenario path not found: --dotenv=…`. Emitting the unknown-flag SHAPE routes this
+    // through fail()'s misplaced-global derivation instead of restating that sentence here.
+    const strayGlobal = args.find((a) => /^--(dotenv|run-dir)(=|$)/.test(a));
+    if (strayGlobal)
+        fail("run", "usage", `unknown flag: ${strayGlobal}`, undefined, flags.output === "json");
     const target = args[0];
     if (!target)
         fail("run", "usage", "usage: run <scenario.yaml | dir/>", undefined, flags.output === "json");

package/dist/run/envelope.js

@@ -135,6 +135,63 @@ export function isJsonOutput(args) {
     }
     return process.env.COWORK_HARNESS_OUTPUT_FORMAT === "json";
 }
+/** Flags the CLI honors ONLY in leading position, before the subcommand. */
+const GLOBAL_ONLY_FLAGS = ["--dotenv", "--run-dir"];
+/** The ONLY message shapes for which "you put a global flag after the subcommand" is a correct
+ *  diagnosis. Anchored deliberately narrowly: the same usage exit also serves errors about a
+ *  CORRECTLY-PLACED leading global (`--dotenv file not found: …`, `--dotenv requires a path …`) and
+ *  errors where the flag name appears inside a QUOTED VALUE (`… got a flag-looking token
+ *  "--dotenv=/x"`). Matching on "the message mentions --dotenv" fires on all of those and tells the user
+ *  to move a flag that is already in the right place. */
+const UNRECOGNIZED_FLAG_SHAPES = [/^unknown flag:/, /^unexpected argument\(s\):/];
+/** Recover the "put it before the subcommand" guidance for a misplaced global flag written in the
+ *  `--flag=value` form.
+ *
+ *  The pre-dispatch guard in cli.ts matches the SPACED form by EXACT token and deliberately does not
+ *  match `--dotenv=<path>` — that exact-token rule is what stops a legitimate per-command VALUE
+ *  (`skill … --answer "--dotenv=x=foo"`) from being hijacked, and it must stay. The equals form therefore
+ *  reaches each command's own parser and surfaces as a bare `unknown flag: --dotenv`, dropping the one
+ *  thing the user needs: where to put it instead. Deriving it here also covers `run`'s
+ *  `unexpected argument(s):` path, which a flag-level fix never reaches.
+ *
+ *  "It is a usage error, therefore the flag is misplaced" is FALSE, and the narrowness below is the
+ *  whole safety argument. The same exit serves errors about a CORRECTLY-PLACED leading global
+ *  (`--dotenv file not found: …`) and errors naming the flag inside a quoted VALUE (`… got a
+ *  flag-looking token "--dotenv=/x"`). The SHAPE allowlist is what excludes both: neither wording
+ *  begins with `unknown flag:` or `unexpected argument(s):`. The program-name skip below is
+ *  defense-in-depth on top of that — every leading-position error also carries `cowork-harness` as its
+ *  command — and removing it today changes no observable behaviour. Keep it: it is the guard that still
+ *  holds if a future message is reworded into one of the two shapes.
+ *
+ *  `critique` needs no exemption here: it never calls `fail()` (it writes to stderr and exits directly),
+ *  so its legitimate per-command `--dotenv` cannot reach this function. Its exemption lives in cli.ts's
+ *  pre-dispatch guard and nowhere else — do not add a dead branch for it here.
+ *
+ *  Coverage is most of the CLI, not all of it, and the gaps are structural rather than oversights: a
+ *  command that never reaches `fail()` (`critique`, `chat`, `prune`, `migrate-run-dir` all log and exit
+ *  directly) or whose usage message is shaped differently (`vm` and a bare `assertions` emit a usage
+ *  block; `lint`/`lint-skill` forward the token to Python argparse) keeps its own bare message. Those
+ *  are worth closing at their own call sites — not by widening the allowlist here, which is what keeps
+ *  the false positives out. */
+function misplacedGlobalHint(command, message) {
+    // Leading-position global-flag errors are emitted with the PROGRAM NAME as `command`, never a
+    // subcommand, and are about a flag that is already correctly placed. Never hint there — and the
+    // example string would read `cowork-harness --dotenv <path> cowork-harness …` if we did.
+    if (command === "cowork-harness")
+        return undefined;
+    if (!UNRECOGNIZED_FLAG_SHAPES.some((re) => re.test(message)))
+        return undefined;
+    for (const flag of GLOBAL_ONLY_FLAGS) {
+        // Token-boundary match: the flag bare at end-of-token, or introducing an `=value` form. `.` is NOT a
+        // terminator — with it, a typo'd filename (`--dotenv.yaml`) was read as the flag and answered with
+        // "move it before the subcommand". No real message ends a flag token with a period; the two shapes
+        // this runs against terminate it with `=`, whitespace, or end-of-string.
+        if (!new RegExp(`(^|[\\s:])${flag}(=|$|[\\s,])`).test(message))
+            continue;
+        return `${flag} is a GLOBAL flag and must come BEFORE the subcommand (e.g. \`cowork-harness ${flag} <path> ${command} …\`)`;
+    }
+    return undefined;
+}
 /** The single error exit used by every command + the top-level catch, in both `cli.ts` and `doctor.ts`.
  *  boundary → exit 3, every other category → exit 2, UNLESS `exitCode` overrides it — SPEC.md's exit-code
  *  contract names two exceptions that exit `1` instead of the general `2`: `sync` hard-failures (missing
@@ -142,12 +199,15 @@ export function isJsonOutput(args) {
  *  failure reading a prior run's output (SPEC.md:428-436). Every EXISTING call site omits `exitCode` and
  *  keeps its current behavior exactly. */
 export function fail(command, category, message, hint, json, exitCode) {
+    // A caller-supplied hint always wins. The pre-dispatch guard's own message is not one of the two
+    // recognized shapes, so it can never pick up a duplicate copy of its own sentence.
+    const effective = hint ?? (category === "usage" ? misplacedGlobalHint(command, message) : undefined);
     if (json)
-        out(jsonError(command, category, message, hint));
+        out(jsonError(command, category, message, effective));
     else {
         log(message);
-        if (hint)
-            log(hint);
+        if (effective)
+            log(effective);
     }
     process.exit(exitCode ?? (category === "boundary" ? 3 : 2));
 }

package/docs/critique.md

@@ -243,7 +243,14 @@ malformed evaluator items (the surviving findings are then not necessarily the c
 agents md), `corpusCuts` (per-file — empty on every real skill; only non-empty once the ceiling is
 actually breached), `corpusExcluded` (files present on the host but never delivered to the agent by
 staging — untracked, with git-mode on), and `trimRecord` (any section the overall belt-and-suspenders cap
-shaved). On a normal skill this is one reassuring line; the other fields only grow teeth on a genuinely
+shaved). `cowork-harness lint-skill <skill-dir>` answers the same proximity question **without a paid
+run** — `skill-corpus-near-evidence-ceiling` (INFO) from 80%, `skill-corpus-over-evidence-ceiling` (WARN,
+so it fails `--strict`) past it. It counts the same three classes the ceiling governs: `SKILL.md`, every
+file under `references/` (**any extension** — the packager applies no extension filter, so JSON schemas
+and rule packs count), and a plugin skill's `agents/<name>.md`. It does not apply staging's git-tracked
+filter, so an untracked reference inflates the figure — it errs toward warning early, and `corpusCuts`
+stays the authority.
+On a normal skill this is one reassuring line; the other fields only grow teeth on a genuinely
 oversized skill or an untracked-file mistake.
 
 **A corpus-ceiling breach has a second, sharper consequence than the not-adjudicable steer: DROPPED

package/docs/debugging.md

@@ -4,6 +4,12 @@ When a run does the wrong thing — or greens when you don't trust it — this i
 the right tool; the authoritative reference for each command's flags is its `--help` and the
 [README → Commands at a glance](../README.md#commands-at-a-glance).
 
+> **Scope.** "Evidence" on this page 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`, written at the run-dir root
+> whenever the evaluator ran. None of the five tools below surface it — see
+> [`docs/critique.md`](./critique.md#run-dir-artifacts).
+
 <!-- BEGIN triage-canonical -->
 Two situations need different tools — figure out which one you're in first, then reach for the tool
 instead of re-running and hoping. The run already wrote its evidence to a kept run dir (`--keep` prints

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@>=1.13.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.13.2"`. (`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": "1.13.0",
+  "version": "1.13.2",
   "description": "Scriptable, CI-friendly harness for Claude Cowork's runtime contract for testing skills across scenarios \u2014 same agent, mounts, egress allowlist, permission protocol, and sandbox limitations.",
   "license": "MIT",
   "type": "module",

package/scripts/check-skill-doc-links.ts

@@ -1,16 +1,18 @@
-// Guards against a `docs/*.md` pointer inside the shipped skill payload (.claude/skills/**) that
-// resolves nowhere for a PLUGIN-install consumer. A Claude Code plugin cache materializes ONLY
-// `.claude/skills/<name>/**` — `docs/` ships in the npm tarball (see package.json `files`), not the
-// plugin payload — so a bare relative reference like `docs/critique.md` is a dead pointer for every
-// plugin-install user, even though it resolves fine for an npm/tarball install. This cost a real
-// consumer hours (they needed `critique-evidence-package.txt`'s name, documented only in
-// docs/critique.md) and shipped unfixed across two releases before this check existed.
+// Guards against a pointer to a repo directory the shipped skill payload (.claude/skills/**) cannot
+// reach. A Claude Code plugin cache materializes ONLY `.claude/skills/<name>/**`, so a bare relative
+// reference like `docs/critique.md`, `schema/run-result.json` or `examples/answer-policies/demo.yaml`
+// is a dead pointer for every plugin-install user, even where it resolves fine for an npm/tarball
+// install. This cost a real consumer hours (they needed `critique-evidence-package.txt`'s name,
+// documented only in docs/critique.md) and shipped unfixed across two releases before this check
+// existed. See DEAD_ROOTS below for which roots are in scope and, just as importantly, which are not.
 //
 //   npx tsx scripts/check-skill-doc-links.ts
 //
-// Fix for a violation: rewrite the bare `docs/x.md` into a GitHub blob permalink
-// (https://github.com/<owner>/<repo>/blob/main/docs/x.md) so it resolves regardless of install
-// path — see the many examples already in .claude/skills/cowork-harness/SKILL.md and references/.
+// Fix for a violation: rewrite the bare path (`docs/x.md`, `schema/x.json`, `examples/x.yaml`) into a
+// GitHub blob permalink (https://github.com/<owner>/<repo>/blob/main/<path>) so it resolves regardless
+// of install path — see the many examples already in .claude/skills/cowork-harness/SKILL.md and
+// references/. Where the surrounding sentence ALREADY qualifies the pointer as npm-only, append the
+// OPT_OUT_MARKER to that line instead.
 //
 // Scope: git-TRACKED files under .claude/skills/** only. This is deliberately the same boundary a
 // plugin marketplace install and the harness's own `local_plugins` staging use — an untracked file
@@ -24,21 +26,50 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
-// A full GitHub blob permalink for a docs/*.md file, e.g.
+// Repo roots that exist in the REPO but never in a PLUGIN cache, so a bare relative pointer to one is
+// dead for every plugin-install consumer. Deliberately NOT exhaustive:
+//   scripts/   — the payload ships its own .claude/skills/<name>/scripts/, so the path resolves
+//   cassettes/ — in a recipe this names the READER's directory, not ours
+//   src/, test/ — provenance citations ("the rule lives here"), not "go open this"
+//   baselines/ — its payload occurrences are a glob and a bare directory mention; no filename pattern matches either
+// Nested segments are included: a reference into a SUBDIRECTORY is just as dead as a flat one, and a
+// pattern that only matched the flat form would let the next one through.
+const DEAD_ROOTS = ["docs", "schema", "examples"] as const;
+// LEFT boundary `(?<![\w.-])`: without it `mydocs/x.md` and `xschema/y.json` matched their tails and were
+// reported as violations of paths nobody wrote. `/` is deliberately NOT excluded, so a genuine relative
+// pointer (`./docs/x.md`) is still caught — the residual cost is that an absolute system path containing
+// one of these segments would flag, which does not occur in a skill payload and has the marker as an out.
+// RIGHT boundary `(?![\w])`: without it `docs/x.mdx` matched as `docs/x.md`, so the error told the author
+// to permalink a file that does not exist. Case-insensitive so `schema/x.JSON` cannot slip through.
+const DEAD_PATH_BODY = `(?<![\\w.-])(?:${DEAD_ROOTS.join("|")})/(?:[\\w.-]+/)*[\\w.-]+\\.(?:md|json|ya?ml)(?![\\w])`;
+
+// A full GitHub blob permalink to one of those paths, e.g.
 // `https://github.com/yaniv-golan/cowork-harness/blob/main/docs/critique.md` — this resolves
 // regardless of install path, so any occurrence of it is exempt from the bare-reference check below.
-const PERMALINK_RE = /https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/blob\/[^\s)]+\/docs\/(?:[\w-]+\/)*[\w-]+\.md/g;
+// ANY absolute URL, not just a github blob permalink. Scoping the exemption to one URL shape meant an
+// equally-resolvable link — a raw.githubusercontent URL, a GitLab `/-/blob/`, a github `/tree/` — was
+// reported as a dead relative pointer, i.e. the checker rejected its own prescribed fix written another
+// way. An absolute URL resolves for every install path, which is the only property this guard cares about.
+const ANY_URL_RE = /https?:\/\/\S+/g;
 
 // A markdown link `[text](permalink)` whose target is one of the permalinks above — stripped as a
-// whole unit FIRST, because the link text itself is often the same bare `docs/x.md` string (e.g.
+// whole unit FIRST, because the link text itself is often the same bare path (e.g.
 // `` [`docs/critique.md`](https://…/docs/critique.md) ``) and must not separately trip the bare check.
-const MD_LINK_TO_DOCS_RE = /\[[^\]\n]*\]\(https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/blob\/[^\s)]+\/docs\/(?:[\w-]+\/)*[\w-]+\.md\)/g;
+// `[text](url)` — stripped as a whole unit FIRST, because the link TEXT is often the same bare path
+// (`` [`docs/critique.md`](https://…) ``); stripping only the URL would leave that text to trip the bare
+// check. A link whose target is RELATIVE is deliberately not stripped: `[docs/x.md](./docs/x.md)` is dead
+// for a plugin install in both halves.
+const MD_LINK_TO_URL_RE = /\[[^\]\n]*\]\(https?:\/\/[^\s)]+\)/g;
 
-// A bare/relative reference to a docs/*.md page, anywhere it isn't already covered by a permalink —
+// A bare/relative reference to one of those paths, anywhere it isn't already covered by a permalink —
 // this is the dead pointer for a plugin install.
-// Nested segments included: a reference to a doc in a SUBDIRECTORY of docs/ is just as dead as
-// `docs/critique.md`, and a pattern that only matched the flat form would let the next one through.
-const BARE_DOC_RE = /docs\/(?:[\w-]+\/)*[\w-]+\.md/g;
+const BARE_DEAD_RE = new RegExp(DEAD_PATH_BODY, "gi");
+
+// Explicit, greppable per-line opt-out for a pointer the SAME sentence already qualifies as npm-only
+// (e.g. "published as `schema/verify-cassettes.json` in the npm package"). Mirrors lint-skill's
+// `ignore-next-line` convention: an escape hatch visible in the source, never a silent heuristic over
+// surrounding prose. Line-scoped by design — a file-wide opt-out would hide the next real one.
+const OPT_OUT_MARKER = "<!-- npm-only-ok -->";
 
 export interface Violation {
   file: string;
@@ -55,10 +86,11 @@ export function findViolations(files: Array<{ path: string; content: string }>):
   for (const { path, content } of files) {
     const lines = content.split("\n");
     lines.forEach((lineText, i) => {
+      if (lineText.includes(OPT_OUT_MARKER)) return;
       // Strip whole markdown-link-to-permalink constructs, then any remaining bare permalink (the
       // YAML/Python-comment case, where the URL appears with no surrounding [text](...) brackets).
-      const residual = lineText.replace(MD_LINK_TO_DOCS_RE, "").replace(PERMALINK_RE, "");
-      const matches = residual.match(BARE_DOC_RE);
+      const residual = lineText.replace(MD_LINK_TO_URL_RE, "").replace(ANY_URL_RE, "");
+      const matches = residual.match(BARE_DEAD_RE);
       if (matches) {
         for (const target of matches) violations.push({ file: path, line: i + 1, target });
       }
@@ -82,9 +114,10 @@ export function checkSkillDocLinks(repoRoot: string = REPO_ROOT): { ok: boolean;
   const violations = findViolations(files);
   const errors = violations.map(
     (v) =>
-      `${v.file}:${v.line}: bare reference to "${v.target}" — dead for a plugin install (docs/ ships ` +
-      `only in the npm tarball, not the plugin cache); rewrite to a GitHub blob permalink ` +
-      `(https://github.com/yaniv-golan/cowork-harness/blob/main/${v.target})`,
+      `${v.file}:${v.line}: bare reference to "${v.target}" — dead for a plugin install, which ` +
+      `materializes only .claude/skills/<name>/**; rewrite to a GitHub blob permalink ` +
+      `(https://github.com/yaniv-golan/cowork-harness/blob/main/${v.target}), or append ` +
+      `"${OPT_OUT_MARKER}" to the line if its own sentence already qualifies the pointer as npm-only`,
   );
   return { ok: violations.length === 0, errors, violations };
 }
@@ -92,10 +125,10 @@ export function checkSkillDocLinks(repoRoot: string = REPO_ROOT): { ok: boolean;
 function main(): void {
   const { ok, errors, violations } = checkSkillDocLinks();
   if (ok) {
-    process.stdout.write("✓ no dangling docs/*.md references under .claude/skills/**\n");
+    process.stdout.write(`✓ no dangling ${DEAD_ROOTS.join("/")}/ references under .claude/skills/**\n`);
     return;
   }
-  process.stdout.write(`found ${violations.length} dangling docs/*.md reference(s):\n`);
+  process.stdout.write(`found ${violations.length} dangling repo-path reference(s):\n`);
   for (const e of errors) process.stderr.write(`::error::${e}\n`);
   process.exitCode = 1;
 }