paperlint 2.0.0

package/docs/prior-art/repro/claim3-imports.mjs

@@ -0,0 +1,50 @@
+/** CLAIM 3, script half: transitive third-party import closure over the scripts
+ *  the SKILL.md files actually reference. Reads only; never executes them. */
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+
+const REPO = "/home/user/research-paper-pipeline";
+const SKILLS = join(REPO, "skills");
+
+// 1. what do SKILL.md files reference?
+const refs = new Set();
+for (const d of readdirSync(SKILLS)) {
+  const md = join(SKILLS, d, "SKILL.md");
+  if (!existsSync(md)) continue;
+  for (const m of readFileSync(md, "utf8").matchAll(/\.claude\/skills\/paper-pipeline\/(scripts\/[A-Za-z0-9_-]+\.mjs)/g))
+    refs.add(m[1]);
+}
+console.log("=== scripts referenced by SKILL.md files ===");
+const entry = [];
+for (const r of [...refs].sort()) {
+  const p = join(SKILLS, "paper-pipeline", r);
+  const ok = existsSync(p);
+  console.log(`  ${ok ? "EXISTS " : "MISSING"}  ${r}`);
+  if (ok) entry.push(p);
+}
+
+// 2. transitive closure of local imports; collect bare specifiers
+const IMPORT = /(?:^|\s)(?:import|export)\s[^;]*?from\s*["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|await import\(\s*([A-Za-z_$][\w$]*)\s*\)/gm;
+const seen = new Set(), thirdParty = new Map(), dynamicNonLiteral = [];
+const queue = [...entry];
+while (queue.length) {
+  const f = resolve(queue.pop());
+  if (seen.has(f) || !existsSync(f)) continue;
+  seen.add(f);
+  const src = readFileSync(f, "utf8");
+  for (const m of src.matchAll(IMPORT)) {
+    const spec = m[1] ?? m[2];
+    if (!spec) { dynamicNonLiteral.push(`${f.replace(REPO+"/","")}: import(<variable ${m[3]}>)`); continue; }
+    if (spec.startsWith("node:")) continue;
+    if (spec.startsWith(".") || spec.startsWith("/")) { queue.push(resolve(dirname(f), spec)); continue; }
+    if (!thirdParty.has(spec)) thirdParty.set(spec, []);
+    thirdParty.get(spec).push(f.replace(REPO + "/", ""));
+  }
+}
+console.log("\n=== transitive local module closure (" + seen.size + " files) ===");
+for (const f of [...seen].sort()) console.log("  " + f.replace(REPO + "/", ""));
+console.log("\n=== THIRD-PARTY (bare) SPECIFIERS IN THAT CLOSURE ===");
+if (!thirdParty.size) console.log("  (none)");
+for (const [spec, where] of [...thirdParty].sort()) console.log(`  ${spec}  <-  ${[...new Set(where)].join(", ")}`);
+console.log("\n=== non-literal dynamic imports (cannot be resolved statically) ===");
+console.log(dynamicNonLiteral.length ? dynamicNonLiteral.map(s=>"  "+s).join("\n") : "  (none)");

package/docs/prior-art/repro/claim4-find-package-json.mjs

@@ -0,0 +1,8 @@
+import module, { findPackageJSON } from "node:module";
+import { pathToFileURL } from "node:url";
+const consumer = process.cwd();
+console.log("typeof findPackageJSON:", typeof findPackageJSON);
+try { console.log("findPackageJSON('research-paper-pipeline', consumer/x.js) ->", findPackageJSON("research-paper-pipeline", pathToFileURL(consumer+"/x.js").href)); }
+catch(e){ console.log("FAIL:", e.code, String(e.message).split("\n")[0]); }
+try { console.log("findPackageJSON('vigiles', consumer/x.js) ->", findPackageJSON("vigiles", pathToFileURL(consumer+"/x.js").href)); }
+catch(e){ console.log("vigiles FAIL:", e.code, String(e.message).split("\n")[0]); }

package/docs/prior-art/repro/claim4-package-dir.mjs

@@ -0,0 +1,39 @@
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join, relative } from "node:path";
+import { lstatSync, readlinkSync, readFileSync, existsSync, realpathSync } from "node:fs";
+const req = createRequire(import.meta.url);
+const NAME = "research-paper-pipeline";
+
+const pkgJson = req.resolve(`${NAME}/package.json`);
+const pkgDir  = dirname(pkgJson);
+console.log("resolved package.json :", pkgJson);
+console.log("=> package dir        :", pkgDir);
+
+const literal = join(process.cwd(), "node_modules", NAME);
+console.log("literal node_modules/ :", literal);
+console.log("   exists?            :", existsSync(literal));
+if (existsSync(literal)) {
+  const st = lstatSync(literal);
+  console.log("   isSymbolicLink?    :", st.isSymbolicLink(), st.isSymbolicLink() ? "-> " + readlinkSync(literal) : "");
+  console.log("   realpath           :", realpathSync(literal));
+  console.log("   SAME as resolved?  :", realpathSync(literal) === realpathSync(pkgDir));
+}
+
+// the manifest itself: main / exports / bin
+const man = JSON.parse(readFileSync(pkgJson, "utf8"));
+console.log("manifest.main    :", JSON.stringify(man.main));
+console.log("manifest.exports :", JSON.stringify(man.exports));
+console.log("manifest.bin     :", JSON.stringify(man.bin));
+console.log("bin from manifest:", join(pkgDir, man.bin.rpp), existsSync(join(pkgDir, man.bin.rpp)) ? "EXISTS" : "MISSING");
+
+// two-arg import.meta.resolve (the parent form)
+try { console.log("import.meta.resolve(spec, parent):", import.meta.resolve(`${NAME}/package.json`, pathToFileURL(process.cwd() + "/x.js").href)); }
+catch (e) { console.log("import.meta.resolve(spec,parent) FAIL:", e.code, String(e.message).split("\n")[0]); }
+
+// resolve vigiles FROM INSIDE the installed package (what cli.ts does)
+const inside = createRequire(pathToFileURL(join(pkgDir, "dist", "cli.js")).href);
+for (const spec of ["vigiles", "vigiles/package.json"]) {
+  try { console.log(`from inside pkg: resolve(${spec}) ->`, inside.resolve(spec)); }
+  catch (e) { console.log(`from inside pkg: resolve(${spec}) FAIL:`, e.code, String(e.message).split("\n")[0]); }
+}

package/docs/prior-art/repro/claim4-parent-arg.mjs

@@ -0,0 +1,17 @@
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+const NAME = "research-paper-pipeline";
+const consumer = process.argv[2];
+console.log("running from:", import.meta.url);
+// 1) bare, from a dir that does NOT have the package
+try { console.log("  import.meta.resolve(pkg/package.json) 1-arg ->", import.meta.resolve(`${NAME}/package.json`)); }
+catch (e) { console.log("  1-arg FAIL:", e.code, String(e.message).split("\n")[0]); }
+// 2) with an explicit parent inside the consumer
+try { console.log("  import.meta.resolve(..., parent=consumer) ->", import.meta.resolve(`${NAME}/package.json`, pathToFileURL(consumer + "/x.mjs").href)); }
+catch (e) { console.log("  2-arg FAIL:", e.code, String(e.message).split("\n")[0]); }
+// 3) require.resolve with paths:
+try { console.log("  require.resolve(..., {paths:[consumer]}) ->", createRequire(import.meta.url).resolve(`${NAME}/package.json`, { paths: [consumer] })); }
+catch (e) { console.log("  paths: FAIL:", e.code, String(e.message).split("\n")[0]); }
+// 4) createRequire anchored at the consumer
+try { console.log("  createRequire(consumer/x.js).resolve(...) ->", createRequire(pathToFileURL(consumer + "/x.js").href).resolve(`${NAME}/package.json`)); }
+catch (e) { console.log("  anchored FAIL:", e.code, String(e.message).split("\n")[0]); }

package/docs/prior-art/repro/claim4-resolve-apis.mjs

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const req = createRequire(import.meta.url);
+const NAME = "research-paper-pipeline";
+const tries = [
+  ["createRequire.resolve('<pkg>/package.json')", () => req.resolve(`${NAME}/package.json`)],
+  ["createRequire.resolve('<pkg>')",              () => req.resolve(NAME)],
+  ["createRequire.resolve('<pkg>/bin/rpp.mjs')",  () => req.resolve(`${NAME}/bin/rpp.mjs`)],
+  ["require.resolve(name,{paths:[cwd]}) pkg.json",() => req.resolve(`${NAME}/package.json`, { paths: [process.cwd()] })],
+  ["import.meta.resolve('<pkg>/package.json')",   () => fileURLToPath(import.meta.resolve(`${NAME}/package.json`))],
+  ["import.meta.resolve('<pkg>')",                () => fileURLToPath(import.meta.resolve(NAME))],
+  // the closed-exports control: vigiles is a dep OF the package, exports map is closed
+  ["createRequire.resolve('vigiles/package.json')", () => req.resolve("vigiles/package.json")],
+  ["createRequire.resolve('vigiles')",              () => req.resolve("vigiles")],
+  ["createRequire.resolve('vigiles/dist/cli.js')",  () => req.resolve("vigiles/dist/cli.js")],
+];
+console.log(`node ${process.version}  cwd=${process.cwd()}`);
+for (const [label, fn] of tries) {
+  try { console.log(`  OK   ${label}\n         -> ${fn()}`); }
+  catch (e) { console.log(`  FAIL ${label}\n         ${e.code ?? ""} ${String(e.message).split("\n")[0]}`); }
+}

package/docs/prior-art/repro/claim4-setup-consumers.mjs

@@ -0,0 +1,45 @@
+/**
+ * Builds the consumer trees the CLAIM 4/5 probes measure: `npm pack` this repository once, then
+ * install the SAME tarball into a clean project with npm and with pnpm.
+ *
+ * Kept separate from the probes on purpose. The probes are the files that produced the numbers in
+ * `../package-location.md` and must stay byte-identical to what was run; this one only makes a
+ * tree for them to look at, so it may be re-run freely.
+ *
+ * Usage:  node docs/prior-art/repro/claim4-setup-consumers.mjs [workdir]
+ * Prints the two consumer directories, one per line, in the order npm, pnpm.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
+const work = process.argv[2] ?? mkdtempSync(join(tmpdir(), "rpp-location-"));
+mkdirSync(work, { recursive: true });
+
+const packed = execFileSync("npm", ["pack", "--silent", "--pack-destination", work], {
+  cwd: ROOT,
+  encoding: "utf8",
+})
+  .trim()
+  .split("\n")
+  .pop();
+const tgz = join(work, packed);
+if (!existsSync(tgz)) throw new Error(`npm pack left no tarball: ${tgz}`);
+
+const out = [];
+for (const [manager, args] of [
+  ["npm", ["install", "--silent", tgz]],
+  ["pnpm", ["install", "--silent", tgz]],
+]) {
+  const consumer = join(work, `consumer-${manager}`);
+  rmSync(consumer, { recursive: true, force: true });
+  mkdirSync(consumer, { recursive: true });
+  writeFileSync(join(consumer, "package.json"), '{"name":"c","version":"1.0.0","private":true}');
+  const r = spawnSync(manager, args, { cwd: consumer, encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`${manager} install failed:\n${r.stderr ?? ""}${r.stdout ?? ""}`);
+  out.push(consumer);
+}
+console.log(out.join("\n"));

package/docs/prior-art/repro/claim4-yarn-pnp.mjs

@@ -0,0 +1,70 @@
+/**
+ * Yarn Berry (Plug'n'Play): builds a PnP consumer from this repository's tarball and asks the ONE
+ * question that decides whether a resolution-based rewrite would make PnP supportable.
+ *
+ * It is not "does resolution work under PnP" — it does, inside a process that loaded the PnP
+ * runtime. It is whether the path resolution HANDS BACK can be read by the outside process that
+ * asked. Under PnP that path points inside a zip, and only PnP's patched `fs` can open it.
+ *
+ * Needs the network (corepack downloads yarn, yarn downloads the transitive tree).
+ *
+ * Usage:  node docs/prior-art/repro/claim4-yarn-pnp.mjs [workdir]
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, copyFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
+const work = process.argv[2] ?? mkdtempSync(join(tmpdir(), "rpp-pnp-"));
+mkdirSync(work, { recursive: true });
+const env = { ...process.env, COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" };
+
+const packed = execFileSync("npm", ["pack", "--silent", "--pack-destination", work], {
+  cwd: ROOT,
+  encoding: "utf8",
+}).trim().split("\n").pop();
+
+const consumer = join(work, "consumer-yarn-pnp");
+mkdirSync(consumer, { recursive: true });
+writeFileSync(
+  join(consumer, "package.json"),
+  '{"name":"c-yarn","version":"1.0.0","private":true,"packageManager":"yarn@4.9.2"}',
+);
+copyFileSync(join(work, packed), join(consumer, "rpp.tgz"));
+
+const yarn = (args) => spawnSync("corepack", ["yarn", ...args], { cwd: consumer, encoding: "utf8", env });
+const add = yarn(["add", "./rpp.tgz"]);
+if (add.status !== 0) throw new Error(`yarn add failed:\n${add.stdout}${add.stderr}`);
+console.log("yarn add: ok");
+console.log("node_modules present?", existsSync(join(consumer, "node_modules")) ? "YES" : "NO");
+
+const probe = `
+import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+try { console.log("  resolve(pkg/package.json) ->", req.resolve("research-paper-pipeline/package.json")); }
+catch (e) { console.log("  resolve FAILS:", e.code, String(e.message).split("\\n")[0]); }
+`;
+writeFileSync(join(consumer, "probe.mjs"), probe);
+
+console.log("1) plain node, inside the PnP project (no PnP runtime):");
+process.stdout.write(spawnSync(process.execPath, ["probe.mjs"], { cwd: consumer, encoding: "utf8" }).stdout ?? "");
+
+console.log("2) yarn node (PnP runtime loaded):");
+const withRuntime = yarn(["node", "probe.mjs"]);
+process.stdout.write(withRuntime.stdout ?? "");
+
+const resolved = (withRuntime.stdout ?? "").split("->")[1]?.trim();
+if (resolved) {
+  console.log("3) can the OUTSIDE process read the path PnP handed back?");
+  const outside = spawnSync(process.execPath, ["-e", "console.log('   plain node existsSync:', require('node:fs').existsSync(process.argv[1]))", resolved], { encoding: "utf8" });
+  process.stdout.write(outside.stdout ?? "");
+  const inside = yarn(["node", "-e", "console.log('   yarn node  existsSync:', require('node:fs').existsSync(process.argv[1]))", resolved]);
+  process.stdout.write(inside.stdout ?? "");
+}
+console.log("4) `yarn bin rpp` (the supported way to ask for the bin path):");
+process.stdout.write("   " + (yarn(["bin", "rpp"]).stdout ?? ""));
+console.log("5) does the CLI itself run under PnP?");
+process.stdout.write("   " + ((yarn(["rpp", "--help"]).stdout ?? "").split("\n")[0]) + "\n");
+console.log(`(tree kept at ${consumer})`);

package/docs/prior-art/repro/claim5-bin-launch.mjs

@@ -0,0 +1,39 @@
+/**
+ * How the installed bin can be launched, and what each way costs. Four ways against one consumer:
+ * the `.bin` shim the manager wrote, `node <shim>`, `node <the real file named by `bin` in the
+ * resolved manifest>`, and `npx --no-install`.
+ *
+ * The point of the third row is that the manifest's `bin` value is the REAL file under every
+ * manager, so `node <it>` works where `node <shim>` does not.
+ *
+ * Usage:  node docs/prior-art/repro/claim5-bin-launch.mjs <consumer-dir>
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+const consumer = process.argv[2];
+const from = createRequire(pathToFileURL(join(consumer, "__placeholder__.js")).href);
+const manifestPath = from.resolve("research-paper-pipeline/package.json");
+const installed = dirname(manifestPath);
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+const realBin = join(installed, typeof manifest.bin === "string" ? manifest.bin : manifest.bin.rpp);
+const shim = join(consumer, "node_modules", ".bin", "rpp");
+
+const time = (label, cmd, args) => {
+  const t = Date.now();
+  const r = spawnSync(cmd, args, { cwd: consumer, encoding: "utf8" });
+  const ms = Date.now() - t;
+  const status = r.error ? `ERR ${r.error.code}` : String(r.status);
+  const first = ((r.stdout ?? "") + (r.stderr ?? "")).split("\n").find((l) => l.trim()) ?? "";
+  console.log(`  ${label.padEnd(34)} rc=${status.padEnd(4)} ${String(ms).padStart(5)}ms  ${first.slice(0, 70)}`);
+};
+
+console.log("installed:", installed);
+console.log("real bin :", realBin);
+time("<.bin shim> --help", shim, ["--help"]);
+time("node <.bin shim> --help", process.execPath, [shim, "--help"]);
+time("node <manifest bin> --help", process.execPath, [realBin, "--help"]);
+time("npx --no-install rpp --help", "npx", ["--no-install", "rpp", "--help"]);

package/docs/prior-art/repro/claim5-exports-mutation.mjs

@@ -0,0 +1,57 @@
+/**
+ * The mutation that decides whether replacing the `node_modules/<name>` hardcode with resolution
+ * buys anything MEASURABLE, rather than only looking tidier.
+ *
+ * It copies an installed consumer, adds a CLOSED `exports` map to the installed package's manifest
+ * — one that omits `./bin/rpp.mjs` and `./package.json` — and then asks four questions of the same
+ * broken tree. The hardcode's answers do not change; the documented public import breaks.
+ *
+ * Usage:  node docs/prior-art/repro/claim5-exports-mutation.mjs <consumer-dir>
+ */
+import { cpSync, rmSync, readFileSync, writeFileSync, existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import module from "node:module";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+const src = process.argv[2];
+const mut = mkdtempSync(join(tmpdir(), "rpp-mutation-"));
+rmSync(mut, { recursive: true, force: true });
+cpSync(src, mut, { recursive: true, verbatimSymlinks: true });
+
+const manifest = join(mut, "node_modules", "research-paper-pipeline", "package.json");
+const json = JSON.parse(readFileSync(manifest, "utf8"));
+json.exports = { ".": "./bin/rpp.mjs" };
+writeFileSync(manifest, JSON.stringify(json, null, 2));
+console.log(`MUTATION applied: exports = ${JSON.stringify(json.exports)} (no ./package.json, no ./bin/rpp.mjs)`);
+
+const dir = join(mut, "node_modules", "research-paper-pipeline");
+console.log("1) the HARDCODE still sees everything:");
+console.log("   dir exists          :", existsSync(dir));
+console.log("   plugin/hooks/h.json :", existsSync(join(dir, "plugin", "hooks", "hooks.json")));
+console.log("   skills/             :", existsSync(join(dir, "skills")));
+
+console.log("2) the documented public import is BROKEN:");
+const r = spawnSync(
+  process.execPath,
+  ["--input-type=module", "-e", 'import("research-paper-pipeline/bin/rpp.mjs").then(()=>console.log("   import OK")).catch(e=>console.log("   import FAILS:",e.code,String(e.message).split("\\n")[0]))'],
+  { cwd: mut, encoding: "utf8" },
+);
+process.stdout.write(r.stdout ?? "");
+
+console.log("3) resolution-based location reports it:");
+try {
+  console.log("   resolve pkg/package.json ->", createRequire(pathToFileURL(join(mut, "__placeholder__.js")).href).resolve("research-paper-pipeline/package.json"));
+} catch (e) {
+  console.log("   resolve FAILS:", e.code, String(e.message).split("\n")[0]);
+}
+
+console.log("4) node:module.findPackageJSON, same mutation:");
+try {
+  console.log("   findPackageJSON ->", module.findPackageJSON("research-paper-pipeline", join(mut, "__placeholder__.js")));
+} catch (e) {
+  console.log("   FAILS:", e.code);
+}
+console.log(`(tree kept at ${mut})`);

package/docs/prior-art/repro/claim5-resolved-location-and-bin.mjs

@@ -0,0 +1,33 @@
+// Drop-in replacement for the three hardcodes, exercised against a real consumer.
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+const consumer = process.argv[2];
+const NAME = "research-paper-pipeline";
+
+// ONE anchor, ESLint's __placeholder__.js trick: a file that need not exist.
+const from = createRequire(pathToFileURL(join(consumer, "__placeholder__.js")).href);
+const manifestPath = from.resolve(`${NAME}/package.json`);
+const installed = dirname(manifestPath);                      // replaces line 172
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+const binRel = typeof manifest.bin === "string" ? manifest.bin : manifest.bin.rpp;
+const bin = join(installed, binRel);                          // replaces line 276
+
+console.log("installed :", installed);
+console.log("bin       :", bin, existsSync(bin) ? "" : "MISSING");
+
+// (a) hooks.json from the resolved tree (replaces line 135)
+const hj = join(installed, "plugin", "hooks", "hooks.json");
+console.log("hooks.json:", existsSync(hj) ? "found" : "ABSENT");
+
+// (b) the bin runs — via node <resolved real file>, no .bin shim
+const r = spawnSync(process.execPath, [bin, "--help"], { cwd: consumer, encoding: "utf8" });
+console.log("node <bin> --help  ->", r.status, (r.stdout||"").split("\n")[0]);
+
+// (c) and via the .bin shim, which is what npm/pnpm actually create
+const shim = join(consumer, "node_modules", ".bin", "rpp");
+const r2 = spawnSync(shim, ["--help"], { cwd: consumer, encoding: "utf8" });
+console.log(".bin shim --help   ->", r2.status ?? `ERR ${r2.error?.code}`);

package/docs/prior-art/repro/claim6-candidate-ambiguity.mjs

@@ -0,0 +1,17 @@
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+const installed = process.argv[2];
+const dir = join(installed,"skills");
+const names = readdirSync(dir,{withFileTypes:true}).filter(d=>d.isDirectory()&&existsSync(join(dir,d.name,"SKILL.md"))).map(d=>d.name);
+let amb=0, tot=0;
+const kinds={};
+for (const name of names){
+  const body=readFileSync(join(installed,"skills",name,"SKILL.md"),"utf8");
+  for(const m of body.matchAll(/([\w./-]*scripts\/[\w-]+\.mjs)/g)){
+    tot++; const raw=m[1];
+    const hits=[["c1",join(installed,raw)],["c2",join(installed,"skills",name,raw)],["c3",join(installed,raw.replace(/^\.claude\/skills\//,"skills/"))]].filter(([,p])=>existsSync(p)).map(([k])=>k);
+    if(hits.length>1){amb++; if(amb<6)console.log("AMBIGUOUS:",name,raw,hits.join("+"));}
+    kinds[hits.join("+")||"none"]=(kinds[hits.join("+")||"none"]??0)+1;
+  }
+}
+console.log("total refs",tot,"ambiguous",amb, JSON.stringify(kinds));

package/docs/prior-art/repro/claim6-doc-path-candidates.mjs

@@ -0,0 +1,27 @@
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+const consumer = process.argv[2];
+const installed = dirname(createRequire(pathToFileURL(join(consumer,"x.js")).href).resolve("research-paper-pipeline/package.json"));
+const dir = join(installed, "skills");
+const names = readdirSync(dir,{withFileTypes:true}).filter(d=>d.isDirectory()&&existsSync(join(dir,d.name,"SKILL.md"))).map(d=>d.name);
+const tally = {c1:0,c2:0,c3:0,none:0};
+const seen = new Set();
+for (const name of names) {
+  const body = readFileSync(join(installed,"skills",name,"SKILL.md"),"utf8");
+  for (const m of body.matchAll(/([\w./-]*scripts\/[\w-]+\.mjs)/g)) {
+    const raw = m[1]; seen.add(raw);
+    const c1 = join(installed, raw);
+    const c2 = join(installed, "skills", name, raw);
+    const c3 = join(installed, raw.replace(/^\.claude\/skills\//, "skills/"));
+    if (existsSync(c1)) tally.c1++;
+    else if (existsSync(c2)) tally.c2++;
+    else if (existsSync(c3)) tally.c3++;
+    else tally.none++;
+  }
+}
+console.log("installed dir :", installed);
+console.log("skills        :", names.length);
+console.log("distinct raw spellings:", [...seen].join("\n                        "));
+console.log("which candidate resolved:", JSON.stringify(tally));

package/docs/prior-art/test-tooling.md

@@ -0,0 +1,131 @@
+# What we test with, and why there is no test framework here
+
+**Question this file answers:** this package has 57 `*.harness.mjs` files of plain
+`node:assert/strict`, three bespoke e2e scripts, and no jest, vitest, mocha, ava or `node:test`.
+Is that a gap? Should an npm package's install be tested through a local registry?
+
+**Verdict: change nothing.** A general-purpose runner would buy a reporter and a second answer to
+"do the tests pass". A local registry is what MULTI-package repositories reach for; a single-package
+CLI packs a tarball and installs it. Both conclusions have named triggers for revisiting, below.
+
+---
+
+## The measurement that settles the house rule
+
+The rule "testing goes through vigiles" was narrowed on 2026-09-19 to agent-facing surfaces only.
+The corpus already had that shape, which is the strongest evidence the narrowing is descriptive
+rather than a concession — counted the same day:
+
+```
+harness files                          57
+import anything from "vigiles"         10
+  …of which import ONLY recordCheck     8
+```
+
+So the genuinely agent-facing harnesses are three: `hooks/hooks.harness.mjs` (`runHook`,
+`checkHookImports`), `skills/plan-paper-timeline/plan-paper-timeline.effects.harness.mjs`
+(`runHarnessTest`, which spawns the real `claude` binary against a scripted model), and the skill
+contract checks. Everything else is ordinary Node testing that happens to carry the suffix.
+
+⚠️ **The suffix is a CONTRACT, not a style choice.** `lib/mutation-driver.mjs` pairs batteries to
+harnesses by it. Renaming files for a new runner would break that, which has nothing to do with
+running tests.
+
+## Why the install e2e stays a script
+
+`test/e2e/install.mjs` is one linear scenario per package manager with strictly dependent steps
+— install, bin, `init`, `lint`, hook commands, content delivery — and a summary. A runner adds
+named subtests and a reporter; the script already prints per-check `✓`/`✗` and a per-manager
+verdict. The pack-and-install work stays in our code under any host, so the host buys only the
+reporter, at the cost of a second exit-code path.
+
+It also stays OUT of `npm test`: it needs the network for the consumer's transitive dependencies
+and takes minutes. It is its own CI step with its own timeout.
+
+## Tarball-by-path versus a local registry
+
+We install the tarball by path. A real consumer resolves by name from a registry. The difference
+is smaller than it looks, and the reason is mechanical:
+
+> `npm publish --dry-run` and `npm pack --dry-run` use the same packlist.
+
+So "what lands on disk" is faithful by construction. What the shortcut genuinely misses, and the
+status of each here:
+
+| missed                                                                                       | status in this package                                                                           |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `prepublishOnly`, `publishConfig` — they run/apply only on `npm publish`                     | neither is declared, so the gap is zero today                                                    |
+| a cold `npx <name>` in an empty directory: packument fetch, `latest`, bin resolution by name | the documented install is `npm i`, not `npx`                                                     |
+| a dependency on a sibling package not yet published, referenced by semver range              | none today; would appear if the hook runtime is split out (see `../package-shape-options.md` §2) |
+
+**Not missed, so not arguments for a registry:** the published file list, `bundleDependencies`,
+`engines`, peer auto-install (npm ≥7 and pnpm ≥8 are both exercised for real), and `prepare`.
+
+### Prior art, and what it is actually about
+
+- **Angular CLI** and **Nx** spawn verdaccio and publish the workspace's packages into it before
+  e2e. Both are multi-package: the packages reference each other by range, which a second tarball
+  cannot satisfy.
+- **pnpm** uses `@pnpm/registry-mock` because its tests need controlled packuments, not tarballs.
+- **Single-package CLIs** pack and install into a clean temp project — the shape `r2g` packages as
+  a tool ("tests your package after `npm pack` and `npm install --production`").
+
+✅ **Measured 2026-09-19 that verdaccio DOES work in our environment**, so adopting it later is a
+decision and not an unknown: `npm i -g verdaccio` (v6.10.3) installs, it serves on 4873, its uplink
+to registry.npmjs.org reaches through the agent proxy (`@eslint/markdown` → HTTP 200), `npm publish`
+into it succeeds, and a consumer's `npm i research-paper-pipeline` then resolves **by name** —
+`"resolved": "http://localhost:4873/…"` in the consumer's lockfile — with the installed binary
+answering. Recording this so the question "would it even run here" never has to be asked again.
+
+**Triggers to revisit:** a second published package that this one depends on by range, **or** the
+documented install becoming a cold `npx <name>`. Then: verdaccio as a devDependency spawned by the
+script, Angular-style — not a Docker service in CI.
+
+## Why no vitest, and no `node:test` either
+
+vitest's value is its Vite transform pipeline, jsdom, module mocking and a watch UI. The tests here
+are plain `.mjs`, the sources are compiled by `tsc`, there is no DOM, and the design deliberately
+does not mock — it spawns real processes into temp directories, which is the right shape for a CLI.
+So vitest would add vite and a native esbuild binary to a package whose install weight is itself
+under scrutiny, and nothing breaks without it.
+
+`node:test` costs no dependency but creates the two-answers problem verbatim: a second discovery
+mechanism (`--test` globs against the `.harness.mjs` suffix) and a second exit code.
+
+**What staying honestly costs:** a top-level `assert` stops at the FIRST failure, so a table-driven
+test over many fixtures reports one row per run. Also no name-level filtering (file-level exists:
+`vigiles test <file>`).
+
+**Trigger to revisit:** when continue-after-failure is measurably costing iteration time on a
+table-driven test. The answer then is `node:test`, never vitest, and it must run under the same
+`npm test` line rather than beside it.
+
+## One known limit, recorded so it is not claimed
+
+**Yarn Berry (PnP) cannot be supported as things stand.** `plugin/hooks/hooks.json` addresses
+`${CLAUDE_PROJECT_DIR}/node_modules/research-paper-pipeline/bin/rpp.mjs` literally, and PnP has no
+`node_modules` directory at all. Adding a third `managers()` row for it would be a red test, not a
+feature. Yarn _classic_ is one row away if support is ever claimed.
+
+➕ **Correction, 2026-09-19 — the conclusion holds, the reason above is incomplete.** Measured
+against a real Yarn 4.9.2 PnP consumer (`repro/claim4-yarn-pnp.mjs`): the CLI itself **runs** under
+PnP (`yarn rpp --help` answers), so the package is not PnP-incompatible; the literal path in
+`hooks.json` is the _movable_ blocker, since Claude Code exposes `${CLAUDE_PLUGIN_ROOT}` for
+exactly it. The immovable blocker is one this note does not name — PnP resolves to a path **inside
+a zip**, and the outside process gets `existsSync: false` for the very path PnP handed it, so the
+e2e's `existsSync`/`readdirSync`/`readFileSync` inspection reads nothing whatever API produced the
+path. Supporting PnP means re-executing the inspection under `yarn node`, not swapping a string.
+Full run and the three corrections: [`package-location.md`](package-location.md) § 8.
+
+---
+
+## Status
+
+Written 2026-09-19 from a design pass over this repository plus the sources below, with the
+vigiles-import count and the verdaccio run measured here rather than recalled.
+
+Sources: [Nx — Creating an Install Package](https://nx.dev/docs/extending-nx/create-install-package) ·
+[Verdaccio — End to End testing](https://www.verdaccio.org/docs/e2e/) ·
+[@pnpm/registry-mock](https://www.npmjs.com/package/@pnpm/registry-mock) ·
+[r2g](https://github.com/ORESoftware/r2g) ·
+[npm Docs — scripts, `prepack` vs `prepublishOnly`](https://docs.npmjs.com/cli/v11/using-npm/scripts/)

package/docs/rules.md

@@ -0,0 +1,58 @@
+# The checks, one by one
+
+The README lists what each check catches in one line. This page says exactly which file each one
+reads and when it fails. Errors fail `paperlint lint`; warnings print and do not.
+
+| Rule                           | Level | Reads                                         | Fails when                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------ | ----- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `paper/stages`                 | error | `PIPELINE-STATUS.md`                          | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                                                                                                                                                  |
+| `paper/source`                 | error | `PIPELINE-STATUS.md`                          | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                                                                                                                                                  |
+| `paper/author-list`            | warn  | `PIPELINE-STATUS.md`                          | a stage is declared and **no cell of the scorecard's table contains the run marker** (default `bib-authors`). It checks that you recorded the cross-check; it does not read your `.bib`. What to run is your own `authorListCommand`, empty by default                                                                                                                                                                                                          |
+| `paper/research-question`      | warn  | `paper.tex`, `paper.md`, `PIPELINE-STATUS.md` | a stage is declared and either the scorecard has no `researchQuestion` field, or it has one the paper does not contain. The declared sentence is compared against the source with whitespace collapsed — your words, not a pattern. Advisory, because nothing here can judge whether what you declared _is_ a research question                                                                                                                                 |
+| `paper/typography`             | warn  | `paper.tex`, `paper.md`                       | any of four counts rises above the per-paper allowance you set: `§` or `\S\ref` instead of "Section"; a decimal with no leading zero (`.05` instead of `0.05`, IEEE / ISO 80000-1 style), counted only where the reader sees it — prose, math and table cells, not macro options, column specs, comments, code or tikz; `Fig.` and `Figure` mixed in one document; bibliography entries with no doi, url or arXiv id. Existing debt is tolerated, growth is not |
+| `tex/future-promise`           | warn  | `paper.tex`                                   | a camera-ready build still says "will be released" about something already handed over                                                                                                                                                                                                                                                                                                                                                                          |
+| `tex/acm-frontmatter-override` | error | `paper.tex`                                   | an `acmart` build overrides ACM's front-matter commands and drops template elements from page 1                                                                                                                                                                                                                                                                                                                                                                 |
+| `review/findings-cause`        | error | `reviews/*.md`                                | a review lists at least `minFindings` (default 3) findings and no cell introduces a cause with the marker (default `Cause:`)                                                                                                                                                                                                                                                                                                                                    |
+| `doc/fields`                   | warn  | `reviews/*.md`                                | a front-matter field is missing or holds a value outside the list you configured. Off entirely unless you configure `docFields`                                                                                                                                                                                                                                                                                                                                 |
+
+Optional rules — off unless you turn them on in the `rules` setting, because only some venues need
+them — are on their own page: [`optional-rules.md`](optional-rules.md). Today there is one,
+`pdf/last-page-balance`.
+
+Besides these rules, `paperlint lint` reports a paper directory that is missing a required file (by
+default `PIPELINE-STATUS.md`) as an error. Which files are required is configurable — see
+[`configuration.md`](configuration.md#required-files).
+
+## The paper is LaTeX
+
+The paper body is `paper.tex`, and it gets four rules: `paper/research-question`,
+`paper/typography`, `tex/future-promise` and `tex/acm-frontmatter-override`. The scorecard and
+the review notes are Markdown files, and the other five rules read those.
+
+A Markdown body (`paper.md`, or `draft.md`) is still read today and gets only the two `paper/`
+rules, which is why they list it above. Markdown papers are deprecated and being removed
+([#57](https://github.com/zernie/research-paper-pipeline/issues/57)); do not start a new one.
+
+## The scorecard's `bytes:` and `sourceBytes:`
+
+A stage in `PIPELINE-STATUS.md` looks like this:
+
+```yaml
+---
+stages:
+  - stage: submitted
+    date: 2026-07-22
+    venue: A Venue 2026
+    pdf: versions/2026-07-22-submitted.pdf
+    bytes: 305412
+    source: versions/2026-07-22-submitted.tex
+    sourceBytes: 57210
+researchQuestion: "Does pruning the state space reduce review cost?"
+---
+```
+
+Today you write `bytes:` and `sourceBytes:` yourself, or the agent does, once, when the stage is
+recorded; no command in this package generates them. They are not a checksum to maintain: a
+frozen PDF is never supposed to change, so `bytes:` disagreeing with the file means the file was
+replaced after it was declared, and that is exactly the finding. If you really did re-freeze a
+stage, update the number in the same commit.