paperlint 2.0.0

package/docs/prior-art/readme-structure.md

@@ -0,0 +1,69 @@
+# How comparable tools shape their README
+
+**The question:** our README read like notes for the maintainer. How do well-regarded tools of the
+same kind — a linter with a CLI, for a particular kind of document, often with an editor or agent
+integration — lead a new reader from "what is this" to "it works on my files"?
+
+Fetched 2026-09-23 from the raw README on each project's default branch (URLs below). Line
+numbers are in the raw file, so they include badges and HTML banners. "First code block" is the
+first fenced or indented block a reader can copy.
+
+## The measurements
+
+| tool                        | lines | tagline at | first code block | install at | first run at | how output is shown                                                     | pushed out of the README                          |
+| --------------------------- | ----: | ---------: | ---------------: | ---------: | -----------: | ----------------------------------------------------------------------- | ------------------------------------------------- |
+| **Vale** (prose linter)     |   175 |          8 |               37 |        119 |       38/149 | a real `console` block: commands, then findings, then a total           | per-OS install matrix, quickstart walk-through    |
+| **textlint**                |   629 |         10 |               45 |         41 |          100 | a screenshot of the pretty formatter                                    | getting-started guide, rule collection (wiki)     |
+| **markdownlint-cli2**       |   591 |          3 |               13 |          9 |          111 | not shown; `--help` text verbatim, and exit codes 0/1/2 listed          | rule list, each formatter's own README            |
+| **TeXtidote** (LaTeX)       |   773 |          1 |               46 |         34 |           72 | verbatim text block, then every field of a finding explained            | nothing — one long manual                         |
+| **Ruff**                    |   454 |         14 |              124 |        114 |          124 | a benchmark chart, no findings                                          | rules, settings, editors — all on docs.astral.sh  |
+| **Biome**                   |   204 |         37 |               49 |         47 |           56 | not shown                                                               | everything past "Usage" goes to biomejs.dev       |
+| **lychee** (link checker)   |   978 |         13 |               54 |         48 |          295 | an animated terminal recording at line 22                               | usage guide on the website                        |
+| **cspell**                  |   224 |         12 |             none |          — |            — | —                                                                       | everything: the README is a pointer to cspell.org |
+| **superpowers** (CC skills) |   399 |          3 |               64 |         52 |           64 | not shown; "The Basic Workflow" lists the skills in the order they fire | per-harness install steps are long but stay       |
+
+Sources:
+
+- Vale — https://raw.githubusercontent.com/errata-ai/vale/v3/README.md
+- textlint — https://raw.githubusercontent.com/textlint/textlint/master/README.md
+- markdownlint-cli2 — https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/README.md
+- TeXtidote — https://raw.githubusercontent.com/sylvainhalle/textidote/master/Readme.md
+- Ruff — https://raw.githubusercontent.com/astral-sh/ruff/main/README.md
+- Biome — https://raw.githubusercontent.com/biomejs/biome/main/packages/@biomejs/biome/README.md
+  (the root `README.md` is a symlink to this file)
+- lychee — https://raw.githubusercontent.com/lycheeverse/lychee/master/README.md
+- cspell — https://raw.githubusercontent.com/streetsidesoftware/cspell/main/README.md
+- superpowers — https://raw.githubusercontent.com/obra/superpowers/main/README.md
+
+## Section order, weighted to the three closest tools
+
+- **Vale:** tagline · screenshot · one paragraph of what it is · a console block with commands
+  _and their output_ · sponsors · Why Vale · Install · Quickstart · Styles · Contributing · License.
+- **textlint:** tagline · "similar to ESLint, but for natural language" · Features · Quick Tour
+  (a link) · Installation · Usage (install a rule, `--init`, run) · CLI · config file · formats ·
+  rules · formatters · library use · FAQ · integrations.
+- **markdownlint-cli2:** tagline · Install (five ways, one block each) · Overview · Use (the
+  `--help` text, verbatim) · Output formatters · Exit codes · Rule list (a link) · Configuration.
+
+What the three share: **one sentence of what it is, then install within the first screen, then
+one run.** Vale is the strongest version — the reader sees a real run with real findings before
+reading a single paragraph of explanation. markdownlint-cli2 is the most explicit about exit
+codes, which is the thing a CI user actually needs. TeXtidote, the only LaTeX tool here, is the
+one that explains each field of a finding line; it also spends 30 lines on the problem before
+its first command, which is the part to avoid.
+
+## What we take, what we don't, and why
+
+**We take** Vale's opening: one sentence, then a real run with its real output, captured by
+running the CLI rather than written by hand. We take markdownlint-cli2's short, explicit exit-code
+list, because `rpp lint` is mostly run in CI and "does this fail the build" is the first question
+there. We take Ruff's and Biome's habit of a short commented command list for usage, with every
+flag left to `--help`. We take TeXtidote's one-line explanation of what a finding line means,
+because our findings name files a new user has not heard of yet. We take superpowers' move for
+the agent half: say what the skills do, in the order a user meets them, and keep the plugin
+install to two lines. **We do not take** sponsors, testimonials, benchmark charts or badges —
+this package has no users to quote and no speed story, and a badge wall would push the first
+command down the page. We do not take cspell's "the README is only a link" either: there is no
+docs website here, so the README has to carry the path to a first working run by itself. And we
+do not keep design reasoning in the README at all; every one of these tools keeps "why it is
+built this way" out of the front page, and ours had it in nearly every section.

package/docs/prior-art/repro/README.md

@@ -0,0 +1,92 @@
+# Reproduction scripts for the platform measurements
+
+These are the probes behind the verdicts in
+[`../../package-shape-options.md`](../../package-shape-options.md) § "Premise corrections".
+They are kept because a measurement without its script is a number nobody can re-run: the next
+person who doubts a verdict here should be able to disagree with a program, not with prose.
+
+They are **not** part of the package's test suite and are not wired into any gate. Each is a
+standalone script run by hand.
+
+## How the CLAIM 1 probes work
+
+They use `runHarnessTest` from vigiles, which spawns the **real** `claude` CLI against a
+**scripted mock model**. Nothing reaches a paid endpoint, and `r.modelRequests` exposes exactly
+what text arrived at the model — which is what a substitution question is actually asking.
+
+```console
+$ node docs/prior-art/repro/claim1-crosschannel.mjs
+```
+
+| script | what it decides |
+| --- | --- |
+| `claim1-project-skill.mjs` | does `${CLAUDE_SKILL_DIR}` substitute in a **project** skill's body? |
+| `claim1-plugin-skill.mjs` | the same in a **plugin-provided** skill, with cwd elsewhere |
+| `claim1-crosschannel.mjs` | the table that decides the design: which variables resolve in **both** doors |
+| `claim1-allowedtools.mjs`, `claim1-at2.mjs` | does it substitute in `allowed-tools`? (`at2` is the rebuild after the first version turned out vacuous — Bash was broadly granted, so the permit proved nothing; it now carries an identically shaped decoy) |
+| `claim1-frontmatter.mjs`, `claim1-plugin-frontmatter.mjs` | frontmatter `hooks:` — in both channels |
+| `claim1-hook-payload-reporter.mjs` | the hook the two probes above install; reports argv and env separately, so "not substituted" is distinguishable from "not run" |
+| `claim3-imports.mjs` | transitive third-party closure of the scripts SKILL.md files actually reference |
+
+**Every CLAIM 1 probe carries positive controls** (the skill resolved · a literal body sentinel
+reached the model · a granted tool succeeded). Without them a silent empty result reads as a
+finding, which is the failure mode this repository keeps re-measuring.
+
+## The CLAIM 2 fixtures
+
+Five marketplace manifests, flattened to files here so that no directory in this repository looks
+like a real plugin. To run one, put it back where the CLI expects it:
+
+```console
+$ mkdir -p /tmp/m/.claude-plugin
+$ cp docs/prior-art/repro/claim2-marketplace-nested-range.json /tmp/m/.claude-plugin/marketplace.json
+$ claude plugin validate /tmp/m --strict; echo "RC=$?"
+```
+
+| fixture | RC | why it is kept |
+| --- | --: | --- |
+| `nested-range` | 0 | the accepted shape — `source` is an object whose own `source` key names the type |
+| `nested-exact`, `nested-noversion` | 0 | `version` is optional and takes an exact version or a range |
+| `flat-asclaimed` | 1 | the shape the design note originally recorded. It is **rejected** |
+| `negative-control` | 1 | `"source": "nosuchsourcetype"`. Without it, `nested-range` passing would only show the validator is permissive |
+
+⚠️ **Capture the real exit code, not a pipeline's.** `claude plugin validate … \| head` reports
+`head`'s status. Both the measurement and its first re-run got this wrong before it was caught.
+
+## The CLAIM 4–6 probes — where an installed package is, and how to find it
+
+These back [`../package-location.md`](../package-location.md). They measure the two hardcodes in
+`test/e2e/install.mjs` (`node_modules/<name>` and `node_modules/.bin/rpp`) against the
+resolution APIs Node actually offers, under npm, pnpm and Yarn Berry (PnP).
+
+Build the consumer trees once — it packs this repository and installs the SAME tarball twice:
+
+```console
+$ node docs/prior-art/repro/claim4-setup-consumers.mjs /tmp/loc
+/tmp/loc/consumer-npm
+/tmp/loc/consumer-pnpm
+```
+
+| script | how to run it | what it decides |
+| --- | --- | --- |
+| `claim4-setup-consumers.mjs` | `node … [workdir]` | builds the two consumers; prints their paths. The only one of these that is not evidence — re-run it freely |
+| `claim4-resolve-apis.mjs` | **copy into a consumer**, then `cd` there and `node claim4-resolve-apis.mjs` | the matrix: which of `createRequire.resolve`, `require.resolve(…,{paths})` and `import.meta.resolve` answer, for the bare name and for `<pkg>/package.json`, plus the `exports`-closed control (`vigiles`) |
+| `claim4-package-dir.mjs` | same — copy in, run there | resolved dir vs the literal `node_modules/<name>`; symlink status; `main`/`exports`/`bin` of the installed manifest |
+| `claim4-find-package-json.mjs` | same — copy in, run there | `module.findPackageJSON` (Node ≥22.14, Stability 1.1), including that it answers past a closed `exports` map where `require.resolve` throws |
+| `claim4-parent-arg.mjs` | `node … <consumer-dir>` from ANYWHERE else | that `import.meta.resolve`'s second argument is **ignored, not rejected**, without `--experimental-import-meta-resolve`. Run it twice, with and without the flag |
+| `claim4-yarn-pnp.mjs` | `node … [workdir]` — needs the network | builds a PnP consumer and asks whether the path PnP resolves to can be read by the process that asked. Corrects `../test-tooling.md` § "One known limit" |
+| `claim5-resolved-location-and-bin.mjs` | `node … <consumer-dir>` | the proposed replacement for lines 135/172/276, exercised end to end |
+| `claim5-bin-launch.mjs` | `node … <consumer-dir>` | four ways to launch the installed bin, with exit codes and wall time |
+| `claim5-exports-mutation.mjs` | `node … <consumer-dir>` | **the case for the change.** Copies a consumer, adds a closed `exports` map, and shows the hardcode staying green while the documented public import breaks |
+| `claim6-doc-path-candidates.mjs` | `node … <consumer-dir>` | which of `contentDelivery()`'s three candidate base directories actually fires, over the real 104 references |
+| `claim6-candidate-ambiguity.mjs` | `node … <installed-package-dir>` | whether any reference resolves under more than one candidate — i.e. whether the `some()` can hide a wrong base |
+
+🔴 **`claim4-resolve-apis.mjs`, `claim4-package-dir.mjs` and `claim4-find-package-json.mjs` must
+be COPIED INTO the consumer**, because `createRequire(import.meta.url)` and `import.meta.resolve`
+anchor at the calling FILE, not at `cwd`. Run from the repository they report `MODULE_NOT_FOUND`
+for every name-based row — which is itself one of the findings, and is shown both ways in
+`../package-location.md` § 1. Do not "fix" them by taking a directory argument: the anchoring is
+the measurement.
+
+⚠️ `claim5-exports-mutation.mjs` and `claim4-yarn-pnp.mjs` leave their trees on disk and print
+where, so a disputed line can be re-read rather than re-derived.

package/docs/prior-art/repro/claim1-allowedtools.mjs

@@ -0,0 +1,66 @@
+/** Does ${CLAUDE_SKILL_DIR} substitute in the `allowed-tools` FRONTMATTER Bash rule?
+ *  Measured by CONSEQUENCE: the session grant deliberately omits Bash, so the only way
+ *  a Bash call can succeed is via the skill's own allowed-tools rule.
+ *    PROBE    : bash <skilldir>/scripts/ok.sh   -> permitted only if the rule substituted
+ *    NEG CTRL : bash -c 'echo nope'             -> must be DENIED, else the session is
+ *                                                  granting Bash and the probe is vacuous
+ */
+import { runHarnessTest } from "vigiles";
+
+const skillMd = `---
+name: at-probe
+description: allowed-tools substitution probe. Use when asked to probe allowed tools.
+allowed-tools: Bash(bash \${CLAUDE_SKILL_DIR}/scripts/ok.sh *)
+---
+
+# at-probe
+
+AT_BODY_CONTROL_ZQX7
+resolved skilldir: AT_BEGIN>>>\${CLAUDE_SKILL_DIR}<<<AT_END
+`;
+
+const r = await runHarnessTest({
+  sandbox: false, transcript: true, timeoutMs: 180_000, prompt: "probe allowed tools",
+  allowedTools: ["Skill"],            // NOTE: no Bash here, on purpose
+  files: {
+    ".claude/skills/at-probe/SKILL.md": skillMd,
+    ".claude/skills/at-probe/scripts/ok.sh": "#!/bin/sh\necho OK_SCRIPT_RAN_ZQX7\n",
+  },
+  model: [
+    { tool: "Skill", input: { skill: "at-probe" } },
+    { tool: "Bash", input: { command: "bash ${SKILLDIR}/scripts/ok.sh now" } },   // placeholder, rewritten below
+    { tool: "Bash", input: { command: "echo nope" } },
+    { text: "done" },
+  ],
+});
+try {
+  const reached = r.modelRequests.map(q=>[q.system,...q.messages.map(m=>m.text)].join("\n")).join("\n");
+  const i = reached.indexOf("AT_BEGIN>>>");
+  const skillDir = i === -1 ? null : reached.slice(i + 11, reached.indexOf("<<<AT_END", i));
+  console.log("body control:", reached.includes("AT_BODY_CONTROL_ZQX7") ? "PASS":"FAIL");
+  console.log("skill dir resolved in body:", skillDir);
+  console.log("\n=== tool calls (run 1, literal placeholder — expected deny) ===");
+  for (const c of r.toolCalls) console.log(` ${c.name}${c.isError?" [DENIED/ERROR]":" [OK]"}: ${String(c.resultText).slice(0,180).replace(/\n/g," ")}`);
+  r.cleanup();
+
+  if (!skillDir) { console.log("cannot continue: skill dir not resolved"); process.exit(0); }
+
+  // Run 2: same fixture, but the scripted Bash call now uses the REAL absolute path.
+  const r2 = await runHarnessTest({
+    sandbox: false, transcript: true, timeoutMs: 180_000, prompt: "probe allowed tools",
+    allowedTools: ["Skill"],
+    files: {
+      ".claude/skills/at-probe/SKILL.md": skillMd,
+      ".claude/skills/at-probe/scripts/ok.sh": "#!/bin/sh\necho OK_SCRIPT_RAN_ZQX7\n",
+    },
+    model: [
+      { tool: "Skill", input: { skill: "at-probe" } },
+      { tool: "Bash", input: { command: "bash SKILLDIR_PLACEHOLDER/scripts/ok.sh now" } },
+      { tool: "Bash", input: { command: "echo nope" } },
+      { text: "done" },
+    ],
+  });
+  console.log("\n(run 2 needs the temp cwd, which differs per run — see note below)");
+  for (const c of r2.toolCalls) console.log(` ${c.name}${c.isError?" [DENIED/ERROR]":" [OK]"}: ${String(c.resultText).slice(0,180).replace(/\n/g," ")}`);
+  r2.cleanup();
+} catch (e) { console.log("ERR", e.message); }

package/docs/prior-art/repro/claim1-at2.mjs

@@ -0,0 +1,40 @@
+/** allowed-tools substitution, measured by CONSEQUENCE, with a SAME-SHAPE negative control.
+ *  Skill lives at a FIXED path (plugin dir), so the exact absolute command is knowable.
+ *    PROBE    : bash <skilldir>/scripts/ok.sh      -> allowed iff the rule substituted
+ *    NEG CTRL : bash <decoydir>/scripts/ok.sh      -> identical shape, different dir; must DENY
+ *  If the neg control is ALLOWED, Bash is broadly granted and the probe means nothing. */
+import { runHarnessTest } from "vigiles";
+const P = new URL("../atplugin/", import.meta.url).pathname;
+const SKILLDIR = P + "skills/at-probe";
+const DECOY = new URL("../decoy/", import.meta.url).pathname;
+
+const r = await runHarnessTest({
+  pluginDir: P, sandbox: false, transcript: true, timeoutMs: 180_000,
+  prompt: "probe allowed tools",
+  allowedTools: ["Skill"],   // no blanket Bash
+  model: [
+    { tool: "Skill", input: { skill: "at-probe" } },
+    { tool: "Bash", input: { command: `bash ${SKILLDIR}/scripts/ok.sh` } },
+    { tool: "Bash", input: { command: `bash ${DECOY}scripts/ok.sh` } },
+    { text: "done" },
+  ],
+});
+try {
+  console.log("skill dir (fixed):", SKILLDIR);
+  console.log("decoy    (fixed):", DECOY + "scripts/ok.sh");
+  console.log("\n=== tool calls ===");
+  for (const c of r.toolCalls)
+    console.log(` ${c.name}${c.isError ? " [DENIED]" : " [ALLOWED]"}: ${String(c.resultText).slice(0,200).replace(/\n/g," ")}`);
+  const bash = r.toolCalls.filter(c=>c.name==="Bash");
+  const probe = bash[0], neg = bash[1];
+  console.log("\n=== verdict ===");
+  if (!neg || !neg.isError) {
+    console.log("NEGATIVE CONTROL FAILED: the decoy command was permitted too ->");
+    console.log("  Bash is broadly granted in this configuration; this run proves NOTHING about allowed-tools.");
+  } else if (probe && !probe.isError && /OK_SCRIPT_RAN_ZQX7/.test(probe.resultText)) {
+    console.log("allowed-tools SUBSTITUTION CONFIRMED: the ${CLAUDE_SKILL_DIR} rule permitted the");
+    console.log("  skill-dir command while an identically shaped decoy was denied.");
+  } else {
+    console.log("allowed-tools rule did NOT permit the skill-dir command (probe denied too).");
+  }
+} finally { r.cleanup(); }

package/docs/prior-art/repro/claim1-crosschannel.mjs

@@ -0,0 +1,54 @@
+/** Cross-channel table: what do SKILL_DIR / PLUGIN_ROOT / PLUGIN_DATA resolve to
+ *  in a PROJECT-level skill body, vs in a PLUGIN-provided skill body? */
+import { runHarnessTest } from "vigiles";
+
+const VARS = ["CLAUDE_SKILL_DIR", "CLAUDE_PLUGIN_ROOT", "CLAUDE_PLUGIN_DATA", "CLAUDE_PROJECT_DIR"];
+const body = (title) => `---
+name: ${title}
+description: Cross-channel path-variable probe. Use when asked to probe path variables.
+---
+
+# ${title}
+
+XCHAN_BODY_CONTROL_ZQX7
+
+${VARS.map((v) => `${v}: X${v}X>>>\${${v}}<<<X${v}X`).join("\n\n")}
+`;
+
+function report(label, reached) {
+  console.log(`\n=== ${label} ===`);
+  console.log("  positive control (body reached model):", reached.includes("XCHAN_BODY_CONTROL_ZQX7") ? "PASS" : "FAIL");
+  for (const v of VARS) {
+    const o = `X${v}X>>>`, c = `<<<X${v}X`;
+    const i = reached.indexOf(o);
+    if (i === -1) { console.log(`  ${v.padEnd(20)} marker ABSENT`); continue; }
+    const val = reached.slice(i + o.length, reached.indexOf(c, i));
+    console.log(`  ${v.padEnd(20)} ${val.includes("${") ? "NOT SUBSTITUTED -> " : "-> "}${JSON.stringify(val)}`);
+  }
+}
+const text = (r) => r.modelRequests.map((q) => [q.system, ...q.messages.map((m) => m.text)].join("\n")).join("\n");
+
+// A — project-level skill (the npm + symlink door)
+const a = await runHarnessTest({
+  sandbox: false, transcript: true, timeoutMs: 180_000, prompt: "probe",
+  allowedTools: ["Skill"],
+  files: { ".claude/skills/xchan-project/SKILL.md": body("xchan-project") },
+  model: [{ tool: "Skill", input: { skill: "xchan-project" } }, { text: "done" }],
+});
+try { report("A. PROJECT-level skill (.claude/skills) — the npm+symlink door", text(a)); console.log("  cwd:", a.cwd); } finally { a.cleanup(); }
+
+// B — plugin-provided skill (the plugin door)
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+const P = new URL("../xchanplugin/", import.meta.url).pathname;
+rmSync(P, { recursive: true, force: true });
+mkdirSync(P + ".claude-plugin", { recursive: true });
+mkdirSync(P + "skills/xchan-plugin", { recursive: true });
+writeFileSync(P + ".claude-plugin/plugin.json", JSON.stringify({ name: "xchan", version: "0.0.1", description: "probe" }));
+writeFileSync(P + "skills/xchan-plugin/SKILL.md", body("xchan-plugin"));
+
+const b = await runHarnessTest({
+  pluginDir: P, sandbox: false, transcript: true, timeoutMs: 180_000, prompt: "probe",
+  allowedTools: ["Skill"],
+  model: [{ tool: "Skill", input: { skill: "xchan-plugin" } }, { text: "done" }],
+});
+try { report("B. PLUGIN-provided skill — the plugin door", text(b)); console.log("  cwd:", b.cwd, "\n  plugin root on disk:", P); } finally { b.cleanup(); }

package/docs/prior-art/repro/claim1-frontmatter.mjs

@@ -0,0 +1,76 @@
+/** CLAIM 1 caveat probe: is ${CLAUDE_SKILL_DIR} substituted in SKILL.md FRONTMATTER?
+ *  Two surfaces tested in one run:
+ *    (a) frontmatter `hooks:` command   (the claimed non-substituting surface)
+ *    (b) frontmatter `allowed-tools:`   (where rpp ALSO keeps literal paths)
+ *  Disambiguation: the marker is SINGLE-QUOTED in the command, so the shell cannot
+ *  expand it. Anything other than the literal string must have come from Claude Code.
+ *  POSITIVE CONTROL: a literal sentinel in the same command — if the hook never fires,
+ *  we learn "hook did not run", not "substitution did not happen".
+ */
+import { readFileSync, existsSync, writeFileSync, rmSync } from "node:fs";
+import { runHarnessTest } from "vigiles";
+
+const OUT = new URL("./fm-hook-out.txt", import.meta.url).pathname;
+const HOOKPROBE = new URL("../fmprobe/hookprobe.mjs", import.meta.url).pathname;
+rmSync(OUT, { force: true });
+process.env.FM_PROBE_OUT = OUT;
+
+const skillMd = `---
+name: fmhook-probe
+description: Probe for frontmatter substitution. Use when asked to probe frontmatter.
+allowed-tools: [Read, Skill, "Bash(node \${CLAUDE_SKILL_DIR}/scripts/thing.mjs:*)"]
+hooks:
+  PostToolUse:
+    - matcher: Read
+      hooks:
+        - type: command
+          command: 'FM_PROBE_OUT=${OUT} node ${HOOKPROBE} SENTINEL_HOOK_FIRED_ZQX7 "\${CLAUDE_SKILL_DIR}"'
+---
+
+# fmhook-probe
+
+BODY_CONTROL_ZQX7
+
+body skilldir: BODY_BEGIN>>>\${CLAUDE_SKILL_DIR}<<<BODY_END
+`;
+
+const r = await runHarnessTest({
+  sandbox: false,
+  transcript: true,
+  timeoutMs: 180_000,
+  prompt: "probe the frontmatter",
+  allowedTools: ["Read", "Skill"],
+  files: {
+    ".claude/skills/fmhook-probe/SKILL.md": skillMd,
+    ".claude/skills/fmhook-probe/scripts/thing.mjs": "console.log('x');\n",
+    "control.txt": "CONTROL_FILE_CONTENTS_QQ9\n",
+  },
+  model: [
+    { tool: "Skill", input: { skill: "fmhook-probe" } },
+    { tool: "Read", input: { file_path: "control.txt" } },
+    { text: "done" },
+  ],
+});
+
+try {
+  console.log("=== TOOL CALLS ===");
+  console.log(r.toolCalls.map((c) => `${c.name}${c.isError ? " [ERROR]" : ""}: ${String(c.resultText).slice(0,200)}`).join("\n") || "(none)");
+  console.log("\n=== HOOK FIRES SEEN BY THE CLI ===");
+  console.log(JSON.stringify(r.hooks, null, 1).slice(0, 1200));
+
+  const reached = r.modelRequests.map((q) => [q.system, ...q.messages.map((m) => m.text)].join("\n")).join("\n");
+  const i = reached.indexOf("BODY_BEGIN>>>");
+  console.log("\n=== BODY control (same file, proves the skill loaded) ===");
+  console.log("body marker present:", reached.includes("BODY_CONTROL_ZQX7") ? "PASS" : "FAIL");
+  if (i !== -1) console.log("body substitution:", JSON.stringify(reached.slice(i + 13, reached.indexOf("<<<BODY_END", i))));
+
+  console.log("\n=== FRONTMATTER hooks: OUTPUT FILE ===");
+  if (!existsSync(OUT)) {
+    console.log("POSITIVE CONTROL FAILED: the hook never wrote anything ->");
+    console.log("  the frontmatter `hooks:` key did not fire at all in this CLI version.");
+    console.log("  This is 'hook did not run', NOT 'substitution did not happen'.");
+  } else {
+    console.log(readFileSync(OUT, "utf8").trim());
+  }
+  console.log("\ncwd:", r.cwd, "| exit:", r.exitCode);
+} finally { r.cleanup(); }

package/docs/prior-art/repro/claim1-hook-payload-reporter.mjs

@@ -0,0 +1,10 @@
+import { appendFileSync } from "node:fs";
+appendFileSync(process.env.FM_PROBE_OUT || "/tmp/fm-probe-out.txt",
+  JSON.stringify({
+    event: process.argv[2] || "(none)",
+    argv_literal: process.argv[3] ?? "(no argv)",
+    env_CLAUDE_SKILL_DIR: process.env.CLAUDE_SKILL_DIR ?? "(unset)",
+    env_CLAUDE_PLUGIN_ROOT: process.env.CLAUDE_PLUGIN_ROOT ?? "(unset)",
+    env_CLAUDE_PROJECT_DIR: process.env.CLAUDE_PROJECT_DIR ?? "(unset)",
+  }) + "\n");
+process.exit(0);

package/docs/prior-art/repro/claim1-plugin-frontmatter.mjs

@@ -0,0 +1,27 @@
+import { readFileSync, existsSync } from "node:fs";
+import { runHarnessTest } from "vigiles";
+const OUT = new URL("./fm-plugin-out.txt", import.meta.url).pathname;
+const r = await runHarnessTest({
+  pluginDir: new URL("../fakeplugin/", import.meta.url).pathname,
+  sandbox: false, transcript: true, timeoutMs: 180_000,
+  prompt: "probe plugin frontmatter",
+  allowedTools: ["Read", "Skill"],
+  files: { "control.txt": "CONTROL_QQ9\n" },
+  model: [
+    { tool: "Skill", input: { skill: "pluginfm-probe" } },
+    { tool: "Read", input: { file_path: "control.txt" } },
+    { text: "done" },
+  ],
+});
+try {
+  const skillCall = r.toolCalls.find(c=>c.name==="Skill");
+  console.log("C1 Skill resolved:", skillCall && !skillCall.isError ? "PASS" : "FAIL " + (skillCall?skillCall.resultText.slice(0,200):"none"));
+  const reached = r.modelRequests.map(q=>[q.system,...q.messages.map(m=>m.text)].join("\n")).join("\n");
+  console.log("C2 body marker reached:", reached.includes("PLUGIN_FM_BODY_CONTROL") ? "PASS":"FAIL");
+  const i = reached.indexOf("BODY_BEGIN>>>");
+  if (i!==-1) console.log("body substitution:", JSON.stringify(reached.slice(i+13, reached.indexOf("<<<BODY_END", i))));
+  console.log("hooks seen by CLI:", JSON.stringify(r.hooks));
+  console.log("\n=== PLUGIN-CHANNEL FRONTMATTER HOOK OUTPUT ===");
+  console.log(existsSync(OUT) ? readFileSync(OUT,"utf8").trim() : "POSITIVE CONTROL FAILED: hook never wrote (did not fire)");
+  console.log("\ncwd:", r.cwd);
+} finally { r.cleanup(); }

package/docs/prior-art/repro/claim1-plugin-skill.mjs

@@ -0,0 +1,52 @@
+/** CLAIM 1 probe, PLUGIN channel: is ${CLAUDE_SKILL_DIR} substituted in a
+ *  plugin-provided SKILL.md body? Installed natively via `claude --plugin-dir`. */
+import { writeFileSync } from "node:fs";
+import { runHarnessTest } from "vigiles";
+
+const BODY_CONTROL = "POSITIVE_CONTROL_ZQX7_BODY_REACHED_MODEL";
+const PLUGIN = new URL("../fakeplugin/", import.meta.url).pathname;
+
+const r = await runHarnessTest({
+  pluginDir: PLUGIN,
+  sandbox: false,
+  transcript: true,
+  timeoutMs: 180_000,
+  prompt: "probe the plugin skill dir",
+  allowedTools: ["Read", "Skill"],
+  files: { "control.txt": "CONTROL_FILE_CONTENTS_QQ9\n" },
+  model: [
+    { tool: "Skill", input: { skill: "pluginskill-probe" } },
+    { tool: "Read", input: { file_path: "control.txt" } },
+    { text: "done" },
+  ],
+});
+
+try {
+  console.log("=== TOOL CALLS ===");
+  console.log(r.toolCalls.map((c) => `${c.name}${c.isError ? " [ERROR]" : ""}: ${String(c.resultText).slice(0, 300)}`).join("\n") || "(none)");
+
+  const reached = r.modelRequests.map((q) => [q.system, ...q.messages.map((m) => m.text)].join("\n")).join("\n");
+  writeFileSync(new URL("./claim1-plugin-reached.txt", import.meta.url), reached);
+
+  const skillCall = r.toolCalls.find((c) => c.name === "Skill");
+  const readCall = r.toolCalls.find((c) => c.name === "Read");
+  console.log("\n=== POSITIVE CONTROLS ===");
+  console.log("C1 Skill call resolved:", skillCall && !skillCall.isError ? "PASS" : `FAIL (${skillCall ? skillCall.resultText.slice(0,250) : "no Skill call"})`);
+  console.log("C2 body marker reached model:", reached.includes(BODY_CONTROL) ? "PASS" : "FAIL");
+  console.log("C3 Read control succeeded:", readCall && !readCall.isError ? "PASS" : "FAIL");
+
+  console.log("\n=== SUBSTITUTION VERDICT (plugin channel) ===");
+  for (const [label, open, close] of [
+    ["CLAUDE_SKILL_DIR", "SKILLDIR_BEGIN>>>", "<<<SKILLDIR_END"],
+    ["CLAUDE_PLUGIN_ROOT", "PLUGINROOT_BEGIN>>>", "<<<PLUGINROOT_END"],
+    ["CLAUDE_PROJECT_DIR", "PROJDIR_BEGIN>>>", "<<<PROJDIR_END"],
+  ]) {
+    const i = reached.indexOf(open);
+    if (i === -1) { console.log(`${label}: marker ABSENT`); continue; }
+    const between = reached.slice(i + open.length, reached.indexOf(close, i));
+    console.log(`${label}: ${JSON.stringify(between)}  -> ${between.includes("${") ? "LITERAL (no substitution)" : "SUBSTITUTED"}`);
+  }
+  console.log("\ncwd was:", r.cwd, "| plugin was:", PLUGIN, "| turns:", r.turns, "| exit:", r.exitCode);
+} finally {
+  r.cleanup();
+}

package/docs/prior-art/repro/claim1-project-skill.mjs

@@ -0,0 +1,81 @@
+/**
+ * CLAIM 1 probe — is ${CLAUDE_SKILL_DIR} substituted in a SKILL.md BODY,
+ * for a PROJECT-level skill (.claude/skills/), regardless of cwd?
+ *
+ * Positive controls, so a silent empty result cannot be read as a finding:
+ *   C1 the Skill tool call must resolve (not isError)
+ *   C2 a literal marker from the BODY must appear in what reached the model
+ *   C3 a granted tool (Read) must succeed
+ * Only after all three pass is the substitution verdict meaningful.
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { runHarnessTest } from "vigiles";
+
+const BODY_CONTROL = "POSITIVE_CONTROL_ZQX7_BODY_REACHED_MODEL";
+const OPEN = "SKILLDIR_BEGIN>>>";
+const CLOSE = "<<<SKILLDIR_END";
+
+const skillMd = `---
+name: skilldir-probe
+description: Probe that reports the literal text at the CLAUDE_SKILL_DIR spot. Use when asked to probe the skill dir.
+---
+
+# skilldir-probe
+
+${BODY_CONTROL}
+
+The sibling script lives at ${OPEN}\${CLAUDE_SKILL_DIR}${CLOSE}/scripts/thing.mjs
+
+Also bare: BARE_BEGIN>>>\${CLAUDE_SKILL_DIR}<<<BARE_END
+`;
+
+const r = await runHarnessTest({
+  sandbox: false,
+  transcript: true,
+  timeoutMs: 180_000,
+  prompt: "probe the skill dir",
+  allowedTools: ["Read", "Skill", "Bash"],
+  files: {
+    ".claude/skills/skilldir-probe/SKILL.md": skillMd,
+    ".claude/skills/skilldir-probe/scripts/thing.mjs": "console.log('sibling');\n",
+    "control.txt": "CONTROL_FILE_CONTENTS_QQ9\n",
+  },
+  model: [
+    { tool: "Skill", input: { skill: "skilldir-probe" } },
+    { tool: "Read", input: { file_path: "control.txt" } },
+    { text: "done" },
+  ],
+});
+
+try {
+  const calls = r.toolCalls.map((c) => `${c.name}${c.isError ? " [ERROR]" : ""}: ${String(c.resultText).slice(0, 300)}`);
+  console.log("=== TOOL CALLS ===");
+  console.log(calls.join("\n") || "(none)");
+
+  const reached = r.modelRequests
+    .map((q) => [q.system, ...q.messages.map((m) => m.text)].join("\n"))
+    .join("\n");
+  writeFileSync(new URL("./claim1-reached.txt", import.meta.url), reached);
+
+  const skillCall = r.toolCalls.find((c) => c.name === "Skill");
+  const readCall = r.toolCalls.find((c) => c.name === "Read");
+
+  console.log("\n=== POSITIVE CONTROLS ===");
+  console.log("C1 Skill call resolved:", skillCall && !skillCall.isError ? "PASS" : `FAIL (${skillCall ? skillCall.resultText.slice(0,200) : "no Skill call"})`);
+  console.log("C2 body marker reached model:", reached.includes(BODY_CONTROL) ? "PASS" : "FAIL");
+  console.log("C3 Read control succeeded:", readCall && !readCall.isError ? "PASS" : "FAIL");
+
+  console.log("\n=== SUBSTITUTION VERDICT ===");
+  for (const [label, open, close] of [["sentence form", OPEN, CLOSE], ["bare form", "BARE_BEGIN>>>", "<<<BARE_END"]]) {
+    const i = reached.indexOf(open);
+    if (i === -1) { console.log(`${label}: marker ABSENT from model requests`); continue; }
+    const j = reached.indexOf(close, i);
+    const between = reached.slice(i + open.length, j);
+    console.log(`${label}: between markers = ${JSON.stringify(between)}`);
+    console.log(`${label}: -> ${between.includes("${CLAUDE_SKILL_DIR}") ? "LITERAL (no substitution)" : "SUBSTITUTED"}`);
+  }
+  console.log("\ncwd was:", r.cwd, "| turns:", r.turns, "| exit:", r.exitCode);
+  console.log("full reached-text saved next to this script as claim1-reached.txt");
+} finally {
+  r.cleanup();
+}

package/docs/prior-art/repro/claim2-marketplace-flat-asclaimed.json

@@ -0,0 +1 @@
+{ "name": "rpp-probe", "owner": { "name": "zernie", "url": "https://github.com/zernie" }, "metadata": { "description": "probe marketplace" }, "plugins": [ { "name": "research-paper-pipeline", "source": "npm", "package": "research-paper-pipeline", "version": "^0.1.0", "description": "flat shape as the CLAIM words it" } ] }

package/docs/prior-art/repro/claim2-marketplace-negative-control.json

@@ -0,0 +1 @@
+{ "name": "rpp-probe", "owner": { "name": "zernie", "url": "https://github.com/zernie" }, "metadata": { "description": "probe marketplace" }, "plugins": [ { "name": "research-paper-pipeline", "source": { "source": "nosuchsourcetype", "package": "x" }, "description": "negative control" } ] }

package/docs/prior-art/repro/claim2-marketplace-nested-exact.json

@@ -0,0 +1,9 @@
+{
+  "name": "rpp-probe",
+  "owner": { "name": "zernie", "url": "https://github.com/zernie" },
+  "plugins": [
+    { "name": "research-paper-pipeline",
+      "source": { "source": "npm", "package": "research-paper-pipeline", "version": "0.1.0", "registry": "https://registry.npmjs.org" },
+      "description": "npm-sourced plugin probe" }
+  ]
+}

package/docs/prior-art/repro/claim2-marketplace-nested-noversion.json

@@ -0,0 +1,9 @@
+{
+  "name": "rpp-probe",
+  "owner": { "name": "zernie", "url": "https://github.com/zernie" },
+  "plugins": [
+    { "name": "research-paper-pipeline",
+      "source": { "source": "npm", "package": "research-paper-pipeline" },
+      "description": "npm-sourced plugin probe" }
+  ]
+}

package/docs/prior-art/repro/claim2-marketplace-nested-range.json

@@ -0,0 +1 @@
+{ "name": "rpp-probe", "owner": { "name": "zernie", "url": "https://github.com/zernie" }, "metadata": { "description": "probe marketplace" }, "plugins": [ { "name": "research-paper-pipeline", "source": { "source": "npm", "package": "research-paper-pipeline", "version": "^0.1.0" }, "description": "npm-sourced plugin probe" } ] }