cowork-harness 3.5.0 → 3.7.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: 3.5.0
-  tracks-harness: cowork-harness 3.5.0 (baseline desktop-1.46388.4)
+  version: 3.7.0
+  tracks-harness: cowork-harness 3.7.0 (baseline desktop-2.2553.1)
 ---
 
 # cowork-harness
@@ -25,8 +25,8 @@ 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 3.5.0` (baseline
-> `desktop-1.46388.4`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 3.7.0` (baseline
+> `desktop-2.2553.1`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
 ## Preflight — make sure the harness can actually run
@@ -42,7 +42,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 **≥ 3.5.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.5.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.5.0"`. **Pin `@^3.5.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 **≥ 3.7.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.7.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.7.0"`. **Pin `@^3.7.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)

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 3.5.0` (baseline `desktop-1.46388.4`).
+Self-contained reference. Tracks `cowork-harness 3.7.0` (baseline `desktop-2.2553.1`).
 
 **Fastest path: the packaged Action.** One step gets you `replay`/`lint`/`verify-cassettes` plus a PR
 job-summary reporter (verdict table, staleness findings, cost/turns when available):
@@ -17,7 +17,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 CLI major reaches your workflow the moment it is promoted even though your `uses:` ref never changed — so a
 copy-pasted recipe that omits the input takes a major bump with no say in it. `^2` holds the major, needs no
 patch number to remember, and only wants a human decision at the next major. Pin an exact version
-(e.g. `version: "3.5.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "3.7.0"`) instead when you want byte-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
@@ -36,7 +36,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Stage the agent binary (official channel, sha256-verified against the pinned baseline)
         run: |
-          V=2.1.260   # match your scenario's pinned baseline's agentVersion
+          V=2.1.275   # match your scenario's pinned baseline's agentVersion
           # The release channel is NOT always the stable one. Desktop also stages release CANDIDATES,
           # served only from .../claude-code-releases/rc/<commit>/ — the stable path 404s for those, and
           # 2.1.255 is one. Take B from your pinned baseline's agentBinary.releaseBaseUrl; baselines
@@ -73,7 +73,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@^3.5.0"
+- run: npm i -g "cowork-harness@^3.7.0"
 - run: cowork-harness lint scenarios/*.yaml --strict --min-severity WARN
                                                     # no silent false-greens. WITHOUT --strict this
                                                     # step cannot fail on a WARN-class rule (e.g.
@@ -350,7 +350,7 @@ jobs:
         with: { node-version: '24' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@^3.5.0"
+      - run: npm i -g "cowork-harness@^3.7.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
@@ -379,7 +379,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^3.5.0"
+        run: npm i -g "cowork-harness@^3.7.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

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 3.5.0` (baseline `desktop-1.46388.4`). This is **not** a trim of the full
+Tracks `cowork-harness 3.7.0` (baseline `desktop-2.2553.1`). 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
@@ -103,19 +103,30 @@ 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
+Skill-authored content ships **WHOLE, not rationed**: `SKILL.md`, every file under the skill's own
+`references/**`, every dispatchable `agents/**.md`, and — for a multi-skill plugin — the shared
+plugin-root `references/` files that the skill's own text, a packaged agent body, or the graded agent's
+own read of it actually points at, up to a **512 KiB combined ceiling** across all four together. A
+breach cuts **loudly**: the named file and byte counts are reported, never silent, never refused. The
+plugin-root class is narrow by design — packaging the WHOLE shared tree instead was measured and
+rejected: on a real 6-skill plugin it pushed one skill's corpus to 107% of the ceiling and cost that
+skill's own `SKILL.md` 37,295 B, and `already-covered` (below) judges by presence with no notion of
+authorship, so another skill's shared docs would silently excuse a real gap — a root file the rule leaves
+out is reported in `corpusOmitted` below, never dropped silently. 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.
 
 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.
+and `skill-corpus-over-evidence-ceiling` (WARN, so it fails `--strict`) past it. It counts only the
+skill-local classes — `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 every
+dispatchable `agents/**.md` a plugin skill can dispatch, and every plugin-root `references/` file the
+skill links — the same four classes the packager ships. The one clause it cannot mirror is the
+run-dependent one (a root reference included only because the graded agent READ it), since a static lint
+has no run to read, so its number can under-report there. It also does not apply staging's git-tracked filter,
+so an untracked skill-local reference inflates the figure the other way; `corpusCuts`/`corpusOmitted`
+below stay the authority.
 
 The report's `evidenceBudget` object says exactly what was shown — read it instead of inferring budgets
 from `dist/` source:
@@ -124,7 +135,9 @@ from `dist/` source:
 |---|---|
 | `corpusBytes` | total skill-content bytes found, BEFORE any cut |
 | `corpusCeiling` | the 512 KiB combined ceiling |
+| `corpusPackaged` | every corpus file whose CONTENT shipped into the corpus sections, by the same key `corpusCuts`/`corpusOmitted` use — so a reader can see exactly which sub-agent bodies and shared references the grade rests on. A file the ceiling zeroed is NOT listed; a partially cut one is, with its loss in `corpusCuts`; a placeholder for an unreadable file is never a corpus entry at all |
 | `corpusCuts` | per-file cut record — empty on every real skill; non-empty only once the ceiling is actually breached |
+| `corpusOmitted` | plugin-root `references/` files present on the HOST under `<plugin>/references/` but NOT packaged (a raw walk, so an untracked file staging would not deliver is listed too — `alsoUntracked: true` says so, and the property is ABSENT rather than `false` when trackedness could not be evaluated), and why: `not-linked` (nothing in the skill's authored text, a packaged agent body, or the graded agent's own read points at it), `not-utf8` (fails to decode as clean UTF-8 — the skill's **own** `references/**` has no such filter), or `ambiguous-read` (the graded agent read a path that exists under both the skill's own `references/` and the plugin root's, so which tree it read cannot be attributed) |
 | `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" |

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

@@ -1,6 +1,13 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 3.5.0` (baseline `desktop-1.46388.4`).
+Self-contained reference. Tracks `cowork-harness 3.7.0` (baseline `desktop-2.2553.1`).
+
+> **This page vs. the repo docs.** This is the **offline snapshot** that ships inside the installed
+> plugin — it is self-contained on purpose. The repo carries four other fidelity views, each answering a
+> different question: *which tier do I pick?* ([README → Fidelity tiers](https://github.com/yaniv-golan/cowork-harness/blob/main/README.md#fidelity-tiers-pick-per-scenario--per-ci-job)),
+> *what does a tier enforce?* ([docs/boundary.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/boundary.md)), *what does it NOT reproduce?*
+> ([docs/fidelity-gaps.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/fidelity-gaps.md)), and *why is it built this way?*
+> ([DESIGN.md § 2](https://github.com/yaniv-golan/cowork-harness/blob/main/DESIGN.md#2-parity-matrix-per-tier)).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 

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

@@ -1,7 +1,7 @@
 # Scenario & session schema, assertion catalog, web_fetch, authoring gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.5.0`
-(baseline `desktop-1.46388.4`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.7.0`
+(baseline `desktop-2.2553.1`). 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:

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 3.5.0` (baseline `desktop-1.46388.4`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 3.7.0` (baseline `desktop-2.2553.1`), 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.
 

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

@@ -1762,23 +1762,342 @@ def _agent_name_from_frontmatter(md_path, yaml_mod):
     return None
 
 
+def _enumerate_plugin_agents(plugin_dir):
+    """Every agent markdown under `<plugin_dir>/agents/`, RECURSIVELY, as (declared_name, Path) pairs.
+
+    Recursive on purpose. Claude Code discovers `agents/sub/x.md` (see src/run/analyze-skill.ts:981-983)
+    and skill-hash.ts's `agentSkillName` already attributes both the flat and nested shapes, so a nested
+    agent is dispatchable, hash-attributed and analyze-scanned. The old non-recursive `glob("*.md")` made
+    it invisible to BOTH this linter's subagent_type resolution and the critique corpus.
+
+    This CAN change a severity in both directions, verified, not assumed:
+      - a literal naming a nested agent stops being a `subagent-type-not-found-in-plugin` WARN (it really
+        is dispatchable, so that WARN was a false positive); and
+      - for a plugin whose `agents/` holds ONLY subdirectories, the agent set was previously EMPTY, which
+        sent every same-plugin literal down the `plugin_agent_types` falsy branch in
+        `_classify_subagent_type` to `subagent-type-unknown` (INFO). The set is now non-empty, so a
+        genuinely typo'd literal is reported as the WARN it always was -- a true positive that used to be
+        suppressed, but a NEW `--strict` failure on an unchanged tree."""
+    agents_dir = Path(plugin_dir) / "agents"
+    if not agents_dir.is_dir():
+        return []
+    yaml = _require_yaml()
+    out = []
+    for md in sorted(agents_dir.rglob("*.md")):
+        if not md.is_file():
+            continue
+        out.append((_agent_name_from_frontmatter(md, yaml) or md.stem, md))
+    return out
+
+
 def _resolve_plugin_agents(plugin_dir):
     """Resolve in-plugin agent types: return the set of valid `<plugin>:<agent>` subagent types defined WITHIN plugin_dir.
-    Reads the plugin name from plugin.json and each agents/*.md's `name:` frontmatter (filename stem
+    Reads the plugin name from plugin.json and each agents/**.md's `name:` frontmatter (filename stem
     fallback). Returns an empty set (never crashes) when no plugin.json is found — a bare SKILL.md
     dir with no plugin manifest has nothing to resolve against."""
     plugin_name = _read_plugin_name(plugin_dir)
     if not plugin_name:
         return set()
-    agents_dir = Path(plugin_dir) / "agents"
-    if not agents_dir.is_dir():
-        return set()
-    yaml = _require_yaml()
-    types = set()
-    for md in sorted(agents_dir.glob("*.md")):
-        agent_name = _agent_name_from_frontmatter(md, yaml) or md.stem
-        types.add(f"{plugin_name}:{agent_name}")
-    return types
+    return {f"{plugin_name}:{name}" for name, _ in _enumerate_plugin_agents(plugin_dir)}
+
+
+def _literal_to_agent_name(value, plugin_name):
+    """Map a pinned `subagent_type` literal to a declared agent name WITHIN this plugin, or None.
+
+    A colon-bearing literal is namespaced (`<plugin>:<agent>`) and its prefix MUST equal this plugin's
+    name, or a cross-plugin `other:market-sizing` would match THIS plugin's `market-sizing`. A bare
+    literal matches a declared name directly. MIRRORED in src/critique/resolve-agents.ts; the two are
+    pinned by test/fixtures/dispatchable-agents.json, which both sides execute."""
+    if ":" not in value:
+        return value or None
+    if not plugin_name:
+        return None
+    prefix, _, suffix = value.partition(":")
+    return suffix if prefix == plugin_name and suffix else None
+
+
+def _resolve_corpus_agents(skill_dir):
+    """Every agent file the critique packager will put in THIS skill's evidence corpus, as a sorted list
+    of Paths. Mirrors `resolveDispatchableAgents` in src/critique/resolve-agents.ts -- union of:
+      1. `agents/<skillname>.md` by FILENAME (what the packager did through 3.6.0),
+      2. every in-plugin agent a pinned `subagent_type` literal in SKILL.md / references/** resolves to,
+      3. every agent whose DECLARED name equals the skill name,
+    then a transitive closure over the resolved agent bodies (an agent that dispatches another agent).
+
+    The union is the SAFETY property: this can never resolve to less than the single agents/<skill>.md
+    the old sizing counted, so a skill's reported corpus never shrinks under this change."""
+    skill_dir = Path(skill_dir)
+    # Walk UP for the manifest, exactly as the TypeScript side does (`findEnclosingPluginDir`). The
+    # old `parent.name == "skills"` LAYOUT rule disagreed with the packager outside the
+    # `<root>/skills/<name>` shape: a skill at `<root>/foo/SKILL.md` with a manifest at `<root>` made the
+    # packager size a corpus this sized as ZERO, which is the packager-vs-linter divergence 0003e38
+    # closed in one shape and left open in another.
+    # Nearest MANIFEST first (matching the TypeScript `findEnclosingPluginDir`), falling back to the
+    # `<root>/skills/<name>` LAYOUT. Manifest-only diverged from the packager for a manifest-less plugin,
+    # where the TS side still enumerates agents because it is handed the root explicitly; layout-only
+    # diverged for a skill that is not under `skills/` but does have a manifest above it, which the
+    # packager sizes and this sized as ZERO. Neither rule alone matches; the union does.
+    plugin_dir = _find_enclosing_plugin_dir(skill_dir / "SKILL.md") or (
+        skill_dir.parent.parent if skill_dir.parent.name == "skills" else None
+    )
+    if plugin_dir is None or not (plugin_dir / "agents").is_dir():
+        return []
+    all_agents = _enumerate_plugin_agents(plugin_dir)
+    if not all_agents:
+        return []
+    plugin_name = _read_plugin_name(plugin_dir)
+    skill_name = skill_dir.name
+    picked = {}
+    sources = []  # declared before `add`: every picked agent is itself a dispatch SOURCE
+
+    def add(path):
+        """Record an agent AND queue its body as a dispatch source.
+
+        Clauses 1 and 3 used to record without queueing, so a skill's own primary agent -- the most
+        likely dispatcher of a second agent -- was never scanned and the transitive closure did not run
+        for the dominant real shape. `scanned` below still guarantees termination."""
+        if str(path) in picked:
+            return
+        picked[str(path)] = path
+        sources.append(path)
+
+    for name, md in all_agents:
+        # clause 1 (filename) and clause 3 (declared name)
+        if md == plugin_dir / "agents" / f"{skill_name}.md" or name == skill_name:
+            add(md)
+
+    skill_md = skill_dir / "SKILL.md"
+    if skill_md.is_file():
+        sources.append(skill_md)
+    refs = skill_dir / "references"
+    if refs.is_dir():
+        sources.extend(p for p in sorted(refs.rglob("*")) if p.is_file())
+    scanned = set()
+    while sources:
+        src = sources.pop(0)
+        if str(src) in scanned:
+            continue
+        scanned.add(str(src))
+        try:
+            text = src.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        for m in _SUBAGENT_TYPE_RE.finditer(text):
+            agent_name = _literal_to_agent_name(m.group(1), plugin_name)
+            if not agent_name:
+                continue
+            for name, md in all_agents:
+                if name == agent_name:
+                    add(md)  # queues the body too -- transitive: this agent may dispatch another
+    return [picked[k] for k in sorted(picked)]
+
+
+# --------------------------------------------------------------------------- #
+# plugin-root references/ resolution, for corpus sizing only
+#
+# Mirrors `resolveRootReferences` in src/critique/resolve-references.ts (clauses 1 + 2 only -- see the
+# docstring on `_resolve_corpus_root_references` below for why clause 3 cannot be mirrored here). The TS
+# packager now puts a multi-skill plugin's SHARED plugin-root `references/` files into the evaluator
+# corpus when the graded skill's own text (or a sub-agent it can dispatch) points at them, so
+# `_lint_skill_corpus_size` must size the same files or the ceiling warning under-reports exactly the
+# plugins this feature targets.
+# --------------------------------------------------------------------------- #
+
+# Trailing punctuation a prose or markdown token picks up, stripped as a RUN and WITHOUT requiring
+# balance -- byte-identical rule to TRAILING_PUNCT in resolve-references.ts.
+_TRAILING_PUNCT_RE = re.compile(r"""[)\]}>.,;:!?'"]+$""")
+_LEADING_QUOTE_RE = re.compile(r"""^["'<([]+""")
+_HASH_QUERY_RE = re.compile(r"[#?].*$")
+_BACKTICK_SPAN_RE = re.compile(r"`([^`]+)`")
+_MD_LINK_TARGET_RE = re.compile(r"\]\(([^)\s]+)")
+_HREF_TARGET_RE = re.compile(r"""href=["']([^"']+)["']""")
+
+
+def _line_tokens(line):
+    """Candidate tokens on one line: backticked spans, markdown/href link targets, and bare whitespace-
+    delimited runs. Only those containing `/` are resolved as paths (`pathish`); the bare ones matter only
+    for the ARMED basename pass. Mirrors `lineTokens()` in resolve-references.ts."""
+    pathish = []
+    bare = []
+    raw = (
+        _BACKTICK_SPAN_RE.findall(line)
+        + _MD_LINK_TARGET_RE.findall(line)
+        + _HREF_TARGET_RE.findall(line)
+        + line.split()
+    )
+    for t0 in raw:
+        t = _HASH_QUERY_RE.sub("", t0)
+        t = _LEADING_QUOTE_RE.sub("", t)
+        t = _TRAILING_PUNCT_RE.sub("", t)
+        t = t.replace("\\", "/")
+        if not t:
+            continue
+        if "/" in t:
+            pathish.append(t)
+        else:
+            bare.append(t)
+    return pathish, bare
+
+
+def _token_to_abs(token, plugin_root, plugin_name, file_dir):
+    """Resolve one path-ish token to an absolute (not yet realpath'd) host path. `${CLAUDE_PLUGIN_ROOT}`
+    and a leading `<pluginName>/` both mean the plugin root; everything else is relative to the
+    directory of the file the token was found in. Mirrors `tokenToAbs()`."""
+    if "${CLAUDE_PLUGIN_ROOT}" in token:
+        return os.path.normpath(token.replace("${CLAUDE_PLUGIN_ROOT}", plugin_root))
+    if plugin_name and token.startswith(plugin_name + "/"):
+        return os.path.normpath(os.path.join(plugin_root, token[len(plugin_name) + 1 :]))
+    if os.path.isabs(token):
+        return os.path.normpath(token)
+    return os.path.normpath(os.path.join(file_dir, token))
+
+
+def _realpath_strict(path):
+    """Mirrors node's `realpathSync`: resolves symlinks and raises if any path component doesn't exist
+    (unlike `os.path.realpath`, which resolves lexically even against a nonexistent path)."""
+    return str(Path(path).resolve(strict=True))
+
+
+def _links_in(text, file_dir, plugin_root, plugin_name, by_basename):
+    """Every plugin-root reference `text` (from a file at `file_dir`) points at, mapped to the 1-based
+    line it was pointed at from. Mirrors `linksIn()` -- including the ARMING rule: a token resolving to
+    the plugin-root `references/` DIRECTORY ITSELF arms bare-basename matching for THAT LINE ONLY; it
+    never recurses and never carries to the next line."""
+    try:
+        refs_dir = _realpath_strict(os.path.join(plugin_root, "references"))
+    except OSError:
+        return {}
+    hits = {}
+    for i, line in enumerate(text.splitlines()):
+        pathish, bare = _line_tokens(line)
+        armed = False
+        for t in pathish:
+            abs_path = _token_to_abs(t, plugin_root, plugin_name, file_dir)
+            try:
+                rp = _realpath_strict(abs_path)
+            except OSError:
+                continue  # most prose tokens are not paths at all
+            if rp == refs_dir:
+                armed = True
+                continue
+            if rp.startswith(refs_dir + os.sep):
+                rel = "references/" + rp[len(refs_dir) + 1 :].replace(os.sep, "/")
+                if rel not in hits:
+                    hits[rel] = i + 1
+        if not armed:
+            continue
+        for b in bare:
+            rel = by_basename.get(b)
+            if rel is not None and rel not in hits:
+                hits[rel] = i + 1
+    return hits
+
+
+def _is_clean_utf8(path):
+    """Valid UTF-8, decided by the decoder rather than by scanning the decoded string -- mirrors
+    `isCleanUtf8()` (a `TextDecoder("utf-8", { fatal: true })` decode). `bytes.decode("utf-8")` is
+    strict by default, so a decode failure (not a scan of the result) is what disqualifies a file."""
+    try:
+        path.read_bytes().decode("utf-8")
+        return True
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+def _resolve_root_references(skill_dir, plugin_dir, agents):
+    """Low-level worker, taking an explicit `plugin_dir` so the same-directory guard below is directly
+    unit-testable regardless of how a caller derives `plugin_dir`. Mirrors `resolveRootReferences()`,
+    clauses 1 + 2 only:
+      1. the skill's own authored text (SKILL.md + its own `references/**`), and
+      2. every sub-agent body already in the corpus (`agents`, from `_resolve_corpus_agents`).
+
+    Clause 3 in the TS packager (files the graded AGENT actually read during a live run) is
+    run-dependent -- it needs a recorded turn's access log -- and CANNOT be mirrored by a static lint
+    pass with no run to inspect, so it is deliberately NOT reproduced here. This makes this function's
+    count a floor, never an exact match, relative to what a real critique run would package; that is the
+    same "warn early, the packager's report is the authority" posture the rest of this linter already
+    has for the ceiling.
+
+    Two further known, deliberate divergences (not fixed here -- out of scope for this change):
+      - byte counting: the packager measures UTF-8-DECODED string length while `_lint_skill_corpus_size`
+        (like its pre-existing SKILL.md/references/agents counting) sums `stat().st_size` -- raw bytes
+        on disk. These agree for pure single-byte UTF-8 text and diverge slightly otherwise.
+      - cleanliness filtering: this module's existing `references/` walks (`rglob("*")`, used here and
+        for the skill's own references/** in `_lint_skill_corpus_size`) have no git-tracked-set or
+        symlink-containment filter, unlike `listSkillFilesRecursive` in corpus-walk.ts. This function
+        reuses that same untared posture for consistency with the rest of this linter, not because it is
+        provably safe against a hostile references/ tree."""
+    skill_dir = Path(skill_dir)
+    plugin_dir = Path(plugin_dir)
+    # SKIP (not "dedupe") the standalone-skill shape: those files are already packaged as skill-local,
+    # and running this pass too would double-count them under two different display keys.
+    try:
+        same = skill_dir.resolve(strict=True) == plugin_dir.resolve(strict=True)
+    except OSError:
+        same = skill_dir.resolve() == plugin_dir.resolve()
+    if same:
+        return []
+    refs_root = plugin_dir / "references"
+    if not refs_root.is_dir():
+        return []
+    all_files = sorted(p for p in refs_root.rglob("*") if p.is_file())
+    if not all_files:
+        return []
+    plugin_name = _read_plugin_name(plugin_dir) or plugin_dir.name
+    # Later (sorted) entries win on a real basename collision -- matches the TS `Map` construction,
+    # where each duplicate key overwrites the previous.
+    by_basename = {}
+    for p in all_files:
+        rel = "references/" + p.relative_to(refs_root).as_posix()
+        by_basename[p.name] = rel
+
+    linked = set()
+    sources = [skill_dir / "SKILL.md"]
+    local_refs = skill_dir / "references"
+    if local_refs.is_dir():
+        sources.extend(p for p in sorted(local_refs.rglob("*")) if p.is_file())
+    sources.extend(Path(a) for a in agents)
+    for src in sources:
+        try:
+            text = src.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for rel in _links_in(text, str(src.parent), str(plugin_dir), plugin_name, by_basename):
+            linked.add(rel)
+
+    packaged = []
+    for p in all_files:
+        rel = "references/" + p.relative_to(refs_root).as_posix()
+        if rel not in linked:
+            continue
+        if not _is_clean_utf8(p):
+            continue
+        packaged.append(p)
+    return packaged
+
+
+def _resolve_corpus_root_references(skill_dir, agents):
+    """Every plugin-root `references/` file the critique packager will put in THIS skill's evidence
+    corpus, as a sorted list of Paths. Derives `plugin_dir` the same way `_resolve_corpus_agents` does
+    (the `skills/<name>` multi-skill-plugin shape); a standalone skill (no `skills/` parent) has no
+    plugin-root references pass and is unaffected."""
+    skill_dir = Path(skill_dir)
+    # Walk UP for the manifest, exactly as the TypeScript side does (`findEnclosingPluginDir`). The
+    # old `parent.name == "skills"` LAYOUT rule disagreed with the packager outside the
+    # `<root>/skills/<name>` shape: a skill at `<root>/foo/SKILL.md` with a manifest at `<root>` made the
+    # packager size a corpus this sized as ZERO, which is the packager-vs-linter divergence 0003e38
+    # closed in one shape and left open in another.
+    # Nearest MANIFEST first (matching the TypeScript `findEnclosingPluginDir`), falling back to the
+    # `<root>/skills/<name>` LAYOUT. Manifest-only diverged from the packager for a manifest-less plugin,
+    # where the TS side still enumerates agents because it is handed the root explicitly; layout-only
+    # diverged for a skill that is not under `skills/` but does have a manifest above it, which the
+    # packager sizes and this sized as ZERO. Neither rule alone matches; the union does.
+    plugin_dir = _find_enclosing_plugin_dir(skill_dir / "SKILL.md") or (
+        skill_dir.parent.parent if skill_dir.parent.name == "skills" else None
+    )
+    if plugin_dir is None:
+        return []
+    return _resolve_root_references(skill_dir, plugin_dir, agents)
 
 
 def cmd_resolve_agent_types(args):
@@ -1938,9 +2257,12 @@ _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.
+    Counts the SAME FOUR 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), for a
+    skill inside a multi-skill plugin every <root>/agents/**.md the skill can dispatch, and -- also for a
+    multi-skill plugin -- every <root>/references/** file the skill's authored text (or a dispatchable
+    agent) links (see `_resolve_corpus_root_references`; the run-dependent fourth TS clause, files the
+    agent actually read live, is out of scope for a static lint).
 
     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
@@ -1956,13 +2278,18 @@ def _lint_skill_corpus_size(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)
+    # Multi-skill plugin layout: skillDir is <root>/skills/<name> and the skill's dispatchable sub-agent
+    # prompts live under <root>/agents/ -- the same resolution the critique command performs, via the
+    # shared `_resolve_corpus_agents`. This counted exactly ONE file (agents/<name>.md) while the packager
+    # shipped N, which under-reported the ceiling for precisely the multi-agent plugins that need the
+    # warning most. A standalone skill (no `skills/` parent) has no agents and is unaffected.
+    agents = _resolve_corpus_agents(skill_dir)
+    files.extend(agents)
+    # The packager also puts a multi-skill plugin's SHARED plugin-root `references/` files into the
+    # evidence corpus when the graded skill's own text (or a dispatchable agent) points at them -- see
+    # `_resolve_corpus_root_references`. Omitting this would under-report the ceiling for exactly the
+    # plugins that feature targets, the same failure mode the agents fix above was written to close.
+    files.extend(_resolve_corpus_root_references(skill_dir, agents))
     for p in files:
         try:
             total += p.stat().st_size
@@ -1977,9 +2304,11 @@ def _lint_skill_corpus_size(md_path):
                 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.",
+                "agents/** (every agent the skill can dispatch) + linked plugin-root references/** "
+                "(the shared files the skill's own text or a dispatchable agent points at), the same "
+                "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),
             )
         ]