activate-agentmd 2.4.0 → 2.5.0

package/README.md

@@ -1,6 +1,7 @@
 # activate-agentmd
 
-> The package manager for AI coding-agent engineering standards.
+> The package manager for AI coding-agent engineering standards — and the
+> checks that keep what your agent reads trustworthy.
 
 ```bash
 npx activate-agentmd init
@@ -62,6 +63,9 @@ content is never touched.
 | `update` | Pull current versions |
 | `validate` | Check registry + manifest integrity |
 | `agents` | List supported agent config targets |
+| `lint` | Check every file your agent reads: leaked keys, prompt injection, bloat, stale pins. Exit 1 on an error; `--sarif` for code scanning |
+| `pins` | The breaking changes for the dependency majors this project runs |
+| `bundle sign\|verify\|attest` | Sign the exact set of files your agent reads with your org's key; fail CI on any unsigned change |
 
 Package paths are `<model>/<category>/<package>`. A trailing slash installs the
 whole category:
@@ -71,6 +75,12 @@ agentmd install claude/Security/owasp    # one
 agentmd install claude/Testing/          # all 11
 ```
 
+`lint` works on any repository, no install or manifest needed:
+
+```bash
+npx activate-agentmd lint
+```
+
 Full reference:
 [docs/cli.md](https://github.com/Aaditya1273/Agent.md/blob/main/docs/cli.md)
 

package/bin/agentmd.js

@@ -31,6 +31,9 @@ ${pc.bold("GETTING STARTED")}
   ${pc.cyan("init")}                        Scan this project and install what matches
   ${pc.cyan("link")}                        Wire installed packages into your agent config files
   ${pc.cyan("extract")} ${pc.yellow("PRO")}                 Derive this repo's unwritten conventions into a local standard
+  ${pc.cyan("lint")}                        Check every file your agent reads: secrets, prompt injection, bloat, stale pins
+  ${pc.cyan("pins")}                        Print the breaking changes for the dependency majors this project runs
+  ${pc.cyan("bundle")} ${pc.white("<sign|verify|attest>")} Sign and verify the exact set of files your agent reads (keygen to start)
   ${pc.cyan("review")} ${pc.white("[--base ref]")}         Check a diff against the installed standards (--fast: offline patterns, --local: Ollama)
   ${pc.cyan("test")}                        Benchmark whether the model actually obeys the installed standards
 
@@ -73,7 +76,7 @@ ${pc.bold("OPTIONS")}
 ${pc.bold("FREE AND PRO")}
   ${pc.dim("Everything local is free, forever: init, link, install, update, list, search,")}
   ${pc.dim("review --fast and review --local. No account, no key, no telemetry.")}
-  ${pc.dim("Pro adds extract, private sync, analytics and cloud CI — " + (process.env.AGENTMD_PRO_URL || "https://agent-dot-md.vercel.app/pro"))}
+  ${pc.dim("Pro adds extract, private sync, analytics and cloud CI — " + (process.env.AGENTMD_PRO_URL || "https://agentmd.pages.dev/pro"))}
   ${pc.dim("In CI, set AGENTMD_PRO_KEY instead of logging in.")}
 
 ${pc.bold("EXAMPLES")}
@@ -109,6 +112,9 @@ const COMMANDS = {
   validate: () => require("../src/commands/validate").validate,
   agents: () => require("../src/commands/agents").agents,
   review: () => require("../src/commands/review").review,
+  lint: () => require("../src/commands/lint").lint,
+  pins: () => require("../src/commands/pins").pins,
+  bundle: () => require("../src/commands/bundle").bundle,
   test: () => require("../src/commands/test").test,
   ci: () => require("../src/commands/ci").ci,
 
@@ -140,7 +146,8 @@ const ALIASES = {
   up: "update",
   upgrade: "update",
   check: "outdated",
-  lint: "validate",
+  // `lint` used to alias `validate`. It is a command of its own now: it
+  // checks the user's instruction files, where `validate` checks the registry.
 };
 
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "activate-agentmd",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "The package manager for AI coding-agent engineering standards. Install, link and update rules across Claude Code, Cursor, Codex, Gemini and Copilot.",
   "keywords": [
     "ai",

package/src/commands/bundle.js

@@ -0,0 +1,151 @@
+/**
+ * bundle.js
+ *
+ * `agentmd bundle` — sign, verify and attest the set of files an agent reads.
+ *
+ *   agentmd bundle keygen --out ~/keys/agentmd.key [--kid acme-2026]
+ *       New Ed25519 key pair. The private key goes to --out, which must be
+ *       outside this repository; the public key is printed for
+ *       .agentmd/enterprise.json `bundleKeys` (and your CI secret).
+ *
+ *   agentmd bundle sign --key ~/keys/agentmd.key [--kid acme-2026] [--days 90]
+ *       Hash every instruction file and sign the result into
+ *       .agentmd/bundle.sig. In CI, pass the key as AGENTMD_BUNDLE_SIGNING_KEY.
+ *
+ *   agentmd bundle verify [--json]
+ *       Exit 1 if the signature is not from a trusted key, or if any file an
+ *       agent reads was modified, removed or added since signing.
+ *
+ *   agentmd bundle attest
+ *       One JSON record: commit, context digest, bundle status. Store it with
+ *       the build — it is the answer to "what was the agent told when it
+ *       wrote this?"
+ */
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const pc = require("picocolors");
+const { keygen, signBundle, verifyBundle, trustedKeys, SIG_FILE } = require("../lib/bundle");
+const { cmd } = require("../lib/invocation");
+
+const A = cmd();
+
+function flag(args, name) {
+  const eq = args.find((a) => a.startsWith(`--${name}=`));
+  if (eq) return eq.slice(name.length + 3);
+  const i = args.indexOf(`--${name}`);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
+}
+
+const expandHome = (p) => (p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+const fail = (msg) => { console.error(pc.red(`\n  ${msg}\n`)); process.exitCode = 1; };
+
+function doKeygen(cwd, args) {
+  const out = flag(args, "out");
+  const kid = flag(args, "kid") || `org-${new Date().toISOString().slice(0, 7)}`;
+  if (!out) return fail(`Pass --out <file> for the private key, outside this repository. e.g. ${A} bundle keygen --out ~/keys/agentmd-bundle.key`);
+
+  const target = path.resolve(expandHome(out));
+  const project = path.resolve(cwd);
+  if (target === project || target.startsWith(project + path.sep)) {
+    return fail("Refusing to write a private key inside this repository — it would be one `git add .` from being published. Choose a path outside it, then store the key in your secret manager.");
+  }
+  if (fs.existsSync(target)) return fail(`${out} already exists. Not overwriting a key.`);
+
+  const { publicKey, privateKey } = keygen();
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, privateKey + "\n", { mode: 0o600 });
+
+  const record = { kid, publicKey };
+  console.log("");
+  console.log(`  ${pc.green("✓")}  Private key written to ${out} ${pc.dim("(mode 600 — move it into your secret manager)")}`);
+  console.log("");
+  console.log("  Add the public key to .agentmd/enterprise.json:");
+  console.log(pc.dim(`    "bundleKeys": [${JSON.stringify(record)}]`));
+  console.log("");
+  console.log("  And in CI, pin it from a secret so a pull request cannot swap it:");
+  console.log(pc.dim(`    AGENTMD_BUNDLE_KEYS='[${JSON.stringify(record)}]'`));
+  console.log("");
+}
+
+function doSign(cwd, args) {
+  const keyFile = flag(args, "key");
+  let privateKey = process.env.AGENTMD_BUNDLE_SIGNING_KEY || null;
+  if (keyFile) {
+    try { privateKey = fs.readFileSync(path.resolve(expandHome(keyFile)), "utf-8").trim(); } catch (e) { return fail(`Cannot read ${keyFile}: ${e.code || e.message}`); }
+  }
+  if (!privateKey) return fail(`Pass --key <file>, or set AGENTMD_BUNDLE_SIGNING_KEY. No key yet? ${A} bundle keygen --out ~/keys/agentmd-bundle.key`);
+
+  // Default kid: the only trusted key, when there is exactly one.
+  const { keys } = trustedKeys(cwd);
+  const kid = flag(args, "kid") || (keys.length === 1 ? keys[0].kid : null);
+  if (!kid) return fail("Pass --kid — there is not exactly one key in bundleKeys to default to.");
+  const days = flag(args, "days") ? Number(flag(args, "days")) : undefined;
+  if (days !== undefined && !(days > 0)) return fail("--days must be a positive number");
+
+  let result;
+  try { result = signBundle(cwd, privateKey, kid, { days }); } catch (e) {
+    return fail(`Could not sign: ${/key/i.test(e.message) ? "the private key is not a valid Ed25519 PKCS8 key" : e.message}`);
+  }
+  console.log("");
+  console.log(`  ${pc.green("✓")}  Signed ${result.files} file${result.files === 1 ? "" : "s"} with \`${kid}\` → ${SIG_FILE}`);
+  console.log(pc.dim(`     digest ${result.digest.slice(0, 16)}…  Commit ${SIG_FILE} with the files it covers.`));
+  if (!keys.some((k) => k.kid === kid)) console.log(pc.yellow(`     \`${kid}\` is not in bundleKeys yet — verify will fail until it is.`));
+  console.log("");
+}
+
+function doVerify(cwd, args) {
+  const r = verifyBundle(cwd);
+  // Trusting keys from a file the same pull request can edit means a PR can
+  // swap in its own key and re-sign. In CI, the anchor must come from outside.
+  if (process.env.CI && trustedKeys(cwd).source !== "AGENTMD_BUNDLE_KEYS") {
+    console.error(pc.yellow("  warning: verifying against bundleKeys from the repository itself — a pull request can replace the key and re-sign. Set AGENTMD_BUNDLE_KEYS from a CI secret."));
+  }
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(r, null, 2));
+  } else {
+    console.log("");
+    if (r.valid) {
+      console.log(`  ${pc.green("✓")}  Context bundle verified — signed by \`${r.kid}\` on ${r.signedAt.slice(0, 10)}, nothing changed since.`);
+    } else {
+      console.log(`  ${pc.red("✗")}  ${r.reason}`);
+      for (const f of r.modified) console.log(`     ${pc.yellow("modified")}    ${f}`);
+      for (const f of r.unapproved) console.log(`     ${pc.yellow("unapproved")}  ${f}`);
+      for (const f of r.missing) console.log(`     ${pc.yellow("missing")}     ${f}`);
+      if (r.modified.length + r.unapproved.length + r.missing.length) console.log(pc.dim(`\n  Review the changes, then: ${A} bundle sign --key <file>`));
+    }
+    console.log("");
+  }
+  if (!r.valid) process.exitCode = 1;
+}
+
+function doAttest(cwd) {
+  let commit = null;
+  try { commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  const r = verifyBundle(cwd);
+  console.log(JSON.stringify({
+    type: "agentmd-attestation",
+    v: 1,
+    at: new Date().toISOString(),
+    commit,
+    contextDigest: r.digest,
+    bundle: { valid: r.valid, kid: r.kid || null, signedAt: r.signedAt || null, reason: r.reason || null },
+  }, null, 2));
+}
+
+async function bundle(args) {
+  args = args || [];
+  const cwd = process.cwd();
+  const sub = args[0];
+  if (sub === "keygen") return doKeygen(cwd, args.slice(1));
+  if (sub === "sign") return doSign(cwd, args.slice(1));
+  if (sub === "verify") return doVerify(cwd, args.slice(1));
+  if (sub === "attest") return doAttest(cwd);
+  fail(`Usage: ${A} bundle <keygen|sign|verify|attest>`);
+}
+
+module.exports = { bundle };

package/src/commands/ci.js

@@ -81,6 +81,11 @@ jobs:
           key: agentmd-\${{ runner.os }}-\${{ hashFiles('.agentmd/manifest.json') }}
           restore-keys: agentmd-\${{ runner.os }}-
 
+      # Every file the agent reads, before the agent reads it: leaked keys,
+      # prompt injection, stale version pins. Fails the job on an error.
+      - name: Lint agent instruction files
+        run: npx --yes activate-agentmd lint
+
       - name: Review the diff against the installed standards
         run: npx --yes activate-agentmd review --base origin/\${{ github.base_ref }} --fast --fail-on=high --github
         env:
@@ -183,7 +188,7 @@ function local(args, cwd) {
   console.log(pc.dim(`     Commit it, open a pull request, and the pattern review runs on the diff.\n`));
 }
 
-const WAITLIST_URL = process.env.AGENTMD_PREVIEW_URL || "https://agent-dot-md.vercel.app/pro#cloud-ci";
+const WAITLIST_URL = process.env.AGENTMD_PREVIEW_URL || "https://agentmd.pages.dev/pro#cloud-ci";
 
 /**
  * What `--cloud` prints without `--preview`.

package/src/commands/lint.js

@@ -0,0 +1,84 @@
+/**
+ * lint.js
+ *
+ * `agentmd lint` — check every file your coding agent reads for leaked
+ * secrets, prompt injection, bloat, dead references and stale version pins.
+ *
+ * Works on any repository. No manifest, no account, no network: it reads the
+ * files and exits non-zero on an error, so it can sit in CI next to the tests.
+ *
+ *   agentmd lint             human-readable report; exit 1 on any error
+ *   agentmd lint --strict    warnings fail too
+ *   agentmd lint --json      machine-readable findings
+ *   agentmd lint --sarif     SARIF 2.1.0, for GitHub code scanning
+ */
+
+"use strict";
+
+const pc = require("picocolors");
+const { lintProject } = require("../lib/lint");
+const { cmd } = require("../lib/invocation");
+const pkg = require("../../package.json");
+
+const A = cmd();
+const ORDER = { error: 0, warning: 1, notice: 2 };
+const PAINT = { error: pc.red, warning: pc.yellow, notice: pc.dim };
+
+/** GitHub code scanning reads this. Levels map onto SARIF's three. */
+function toSarif(findings) {
+  const rules = [...new Set(findings.map((f) => f.rule))].map((id) => ({ id, name: id, shortDescription: { text: `Agent.md instruction-file check: ${id}` } }));
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [{
+      tool: { driver: { name: "agentmd", version: pkg.version, informationUri: "https://github.com/Aaditya1273/Agent.md", rules } },
+      results: findings.map((f) => ({
+        ruleId: f.rule,
+        level: f.severity === "notice" ? "note" : f.severity,
+        message: { text: f.message },
+        locations: [{ physicalLocation: { artifactLocation: { uri: f.file.split("\\").join("/") }, region: { startLine: f.line || 1 } } }],
+      })),
+    }],
+  };
+}
+
+async function lint(args) {
+  args = args || [];
+  const strict = args.includes("--strict");
+  const { files, findings } = lintProject(process.cwd());
+  findings.sort((a, b) => ORDER[a.severity] - ORDER[b.severity] || a.file.localeCompare(b.file) || a.line - b.line);
+
+  const errors = findings.filter((f) => f.severity === "error").length;
+  const warnings = findings.filter((f) => f.severity === "warning").length;
+  const failed = errors > 0 || (strict && warnings > 0);
+
+  if (args.includes("--sarif")) {
+    console.log(JSON.stringify(toSarif(findings), null, 2));
+  } else if (args.includes("--json")) {
+    console.log(JSON.stringify({ files, findings, errors, warnings, failed }, null, 2));
+  } else {
+    console.log("");
+    if (files.length === 0) {
+      console.log(`  ${pc.dim("No agent instruction files here (CLAUDE.md, AGENTS.md, .cursor/rules, .claude/…). Nothing to check.")}`);
+    } else if (findings.length === 0) {
+      console.log(`  ${pc.green("✓")}  ${files.length} instruction file${files.length === 1 ? "" : "s"} checked — no problems.`);
+    } else {
+      for (const f of findings) {
+        const sev = PAINT[f.severity](f.severity.toUpperCase().padEnd(7));
+        console.log(`  ${sev} ${pc.white(f.file)}${pc.dim(":" + f.line)}  ${pc.dim(f.rule)}`);
+        console.log(`          ${f.message}`);
+      }
+      console.log("");
+      const parts = [`${errors} error${errors === 1 ? "" : "s"}`, `${warnings} warning${warnings === 1 ? "" : "s"}`];
+      const notices = findings.length - errors - warnings;
+      if (notices) parts.push(`${notices} notice${notices === 1 ? "" : "s"}`);
+      console.log(`  ${parts.join(", ")} across ${files.length} instruction file${files.length === 1 ? "" : "s"}${strict ? pc.dim("  (--strict: warnings fail)") : ""}`);
+      if (findings.some((f) => f.rule === "stale-pins")) console.log(pc.dim(`  Fix stale pins with '${A} link'.`));
+    }
+    console.log("");
+  }
+
+  if (failed) process.exitCode = 1;
+}
+
+module.exports = { lint, toSarif };

package/src/commands/pins.js

@@ -0,0 +1,43 @@
+/**
+ * pins.js
+ *
+ * `agentmd pins` — print the breaking changes for the dependency majors this
+ * project actually runs, in the form an agent reads.
+ *
+ * Exists so a skill or a prompt can fetch current facts at the moment they
+ * are needed instead of carrying a copy that goes stale: the skill says
+ * "before using a pinned library, run `agentmd pins`", and the facts update
+ * whenever the package does. Reads manifests and node_modules; no network.
+ *
+ *   agentmd pins          markdown, as `link` writes it
+ *   agentmd pins --json   detected pins, with measured effect where it exists
+ */
+
+"use strict";
+
+const pc = require("picocolors");
+const { detectVersions, renderPins, proofOf } = require("../lib/versions");
+
+async function pins(args) {
+  args = args || [];
+  const found = detectVersions(process.cwd());
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(found.map((p) => ({ ...p, proof: proofOf(p.lib, p.version) })), null, 2));
+    return;
+  }
+  if (!found.length) {
+    console.log(pc.dim("No pinned dependency majors detected (package.json, node_modules, pyproject.toml, requirements.txt, go.mod)."));
+    return;
+  }
+  // The block is printed exactly as `link` writes it. Measurements are
+  // evidence for people, not instructions for the agent, so they are shown
+  // here and never written into CLAUDE.md.
+  console.log(renderPins(found));
+  const measured = found.map((p) => ({ p, proof: proofOf(p.lib, p.version) })).filter((x) => x.proof && x.proof.n);
+  for (const { p, proof } of measured) {
+    console.log(pc.green(`● measured  ${p.label} ${p.version}: old API in ${proof.without}/${proof.n} tasks without the pin, ${proof.with}/${proof.n} with it (${proof.model}, ${proof.date})`));
+  }
+}
+
+module.exports = { pins };

package/src/commands/review.js

@@ -28,7 +28,8 @@ const { readManifest, resolvePresetPath } = require("../lib/manifest");
 const { cmd } = require("../lib/invocation");
 const analytics = require("../lib/analytics");
 const { track, EVENTS } = require("../lib/telemetry");
-const { runPatterns } = require("../lib/patterns");
+const { PATTERNS, runPatterns } = require("../lib/patterns");
+const { detectVersions, pinPatterns } = require("../lib/versions");
 
 const A = cmd();
 const MODEL = process.env.AGENTMD_REVIEW_MODEL || "claude-opus-5";
@@ -147,7 +148,8 @@ async function review(args) {
   const installedIds = new Set(manifest.presets.map((p) => `${p.category}/${p.preset}`));
 
   // Fast-path: deterministic patterns, always, before any model.
-  const patternFindings = runPatterns(diff, installedIds);
+  // Plus the version checks for whatever majors this project actually runs.
+  const patternFindings = runPatterns(diff, installedIds, PATTERNS.concat(pinPatterns(detectVersions(cwd))));
 
   console.log(pc.bold(`\nReviewing ${pc.cyan(changedFiles.length)} changed file${changedFiles.length === 1 ? "" : "s"} against ${pc.cyan(kept.length)} standard${kept.length === 1 ? "" : "s"}`) + pc.dim(fast ? " (patterns only)" : ` (${modelName}${local ? ", local" : ""})`));
   if (dropped.length) console.log(pc.yellow(`  ${dropped.length} standard${dropped.length === 1 ? "" : "s"} left out to fit the request: ${dropped.join(", ")}`));

package/src/commands/test.js

@@ -12,6 +12,8 @@
  *   agentmd test --all --tasks 5          every installed standard, 5 tasks each
  *   agentmd test --fail-under 80          exit 1 below 80% (CI)
  *   agentmd test --json                   machine-readable results
+ *   agentmd test --baseline               also run every task WITHOUT the standard,
+ *                                         so you see what the standard changed
  *
  * Needs ANTHROPIC_API_KEY (or an `ant auth login` profile). Costs real API
  * calls: roughly N+2 per standard.
@@ -96,6 +98,9 @@ async function test(args) {
   const cwd = process.cwd();
   const all = args.includes("--all");
   const asJson = args.includes("--json");
+  // Without a baseline this measures obedience, not effect: a model that
+  // already writes the right thing "obeys" a standard it never needed.
+  const baseline = args.includes("--baseline");
   const model = flagValue(args, "model") || DEFAULT_MODEL;
   const tasksPer = Math.min(6, Math.max(1, parseInt(flagValue(args, "tasks") || "3", 10) || 3));
   const failUnder = flagValue(args, "fail-under");
@@ -170,26 +175,37 @@ async function test(args) {
       continue;
     }
 
-    // b. Attempts, with the standard exposed exactly as `link` would.
-    const attempts = await pool(tasks, CONCURRENCY, (t) => call(
-      [{ type: "text", text: "You are a coding agent working in this project. Follow the project's engineering standard below. Reply with code and the minimum prose needed." }, standardBlock],
+    // b. Attempts, with the standard exposed exactly as `link` would — and,
+    //    with --baseline, the same tasks with no standard at all.
+    const attempt = (withStandard) => pool(tasks, CONCURRENCY, (t) => call(
+      withStandard
+        ? [{ type: "text", text: "You are a coding agent working in this project. Follow the project's engineering standard below. Reply with code and the minimum prose needed." }, standardBlock]
+        : [{ type: "text", text: "You are a coding agent working in this project. Reply with code and the minimum prose needed." }],
       t.task, 8000));
 
-    // c. Judge strictly against the standard.
-    const transcript = tasks.map((t, i) => `<task n="${i + 1}" targets="${String(t.targets).replace(/"/g, "'")}">\n${t.task}\n</task>\n<attempt n="${i + 1}">\n${attempts[i]}\n</attempt>`).join("\n\n");
-    const judged = parseJSON(await call(
-      [{ type: "text", text: "You are a strict reviewer. Judge each attempt only against the rules in the standard — not general code quality, not taste. An attempt passes if it does not violate the standard. Reply with JSON only: {\"results\":[{\"task\":1,\"pass\":true,\"rule\":\"exact rule heading\",\"reason\":\"one sentence\"}]}. Cite the rule broken (or, on a pass, the rule most relevant)." }, standardBlock],
-      transcript, 4000));
-    const results = tasks.map((t, i) => {
-      const r = Array.isArray(judged?.results) ? judged.results.find((x) => Number(x.task) === i + 1) : null;
-      return { task: i + 1, prompt: t.task, targets: t.targets, pass: r ? !!r.pass : false, rule: r?.rule || t.targets, reason: r?.reason || "no verdict from judge" };
-    });
-    report.push({ id: s.id, tasks, results });
+    // c. Judge strictly against the standard. Both arms get the identical
+    //    judge, so any difference is the standard's, not the judge's.
+    const judge = async (attempts) => {
+      const transcript = tasks.map((t, i) => `<task n="${i + 1}" targets="${String(t.targets).replace(/"/g, "'")}">\n${t.task}\n</task>\n<attempt n="${i + 1}">\n${attempts[i]}\n</attempt>`).join("\n\n");
+      const judged = parseJSON(await call(
+        [{ type: "text", text: "You are a strict reviewer. Judge each attempt only against the rules in the standard — not general code quality, not taste. An attempt passes if it does not violate the standard. Reply with JSON only: {\"results\":[{\"task\":1,\"pass\":true,\"rule\":\"exact rule heading\",\"reason\":\"one sentence\"}]}. Cite the rule broken (or, on a pass, the rule most relevant)." }, standardBlock],
+        transcript, 4000));
+      return tasks.map((t, i) => {
+        const r = Array.isArray(judged?.results) ? judged.results.find((x) => Number(x.task) === i + 1) : null;
+        return { task: i + 1, prompt: t.task, targets: t.targets, pass: r ? !!r.pass : false, rule: r?.rule || t.targets, reason: r?.reason || "no verdict from judge" };
+      });
+    };
+
+    const results = await judge(await attempt(true));
+    const without = baseline ? await judge(await attempt(false)) : null;
+    report.push({ id: s.id, tasks, results, ...(without ? { without } : {}) });
 
     if (!asJson) {
       const passed = results.filter((r) => r.pass).length;
       const ok = passed === results.length;
-      console.log(`  ${ok ? pc.green("✓") : pc.red("✗")} ${pc.white(s.id.padEnd(24))} ${passed}/${results.length}`);
+      const base = without ? without.filter((r) => r.pass).length : null;
+      const effect = without ? pc.dim(`  · without the standard ${base}/${without.length}  `) + (passed - base > 0 ? pc.green(`+${passed - base}`) : pc.yellow(`${passed - base >= 0 ? "±" : ""}${passed - base}`)) : "";
+      console.log(`  ${ok ? pc.green("✓") : pc.red("✗")} ${pc.white(s.id.padEnd(24))} ${passed}/${results.length}${effect}`);
       for (const r of results.filter((x) => !x.pass)) {
         console.log(`  ${" ".repeat(30)}${pc.dim(`task ${r.task}: ignored "${r.rule}" — ${r.reason}`)}`);
       }
@@ -200,12 +216,16 @@ async function test(args) {
   const passed = report.reduce((n, r) => n + r.results.filter((x) => x.pass).length, 0);
   const pct = total ? Math.round((passed / total) * 100) : 0;
   const cost = usage.input * PRICE.input + usage.output * PRICE.output;
+  const basePassed = baseline ? report.reduce((n, r) => n + (r.without || []).filter((x) => x.pass).length, 0) : null;
+  const basePct = baseline && total ? Math.round((basePassed / total) * 100) : null;
 
   if (asJson) {
-    console.log(JSON.stringify({ model, score: { passed, total, pct }, standards: report, usage, estimatedCostUsd: +cost.toFixed(4) }, null, 2));
+    const effect = baseline ? { without: { passed: basePassed, total, pct: basePct }, deltaPoints: pct - basePct } : {};
+    console.log(JSON.stringify({ model, score: { passed, total, pct }, ...effect, standards: report, usage, estimatedCostUsd: +cost.toFixed(4) }, null, 2));
   } else {
     console.log("");
-    console.log(pc.bold(`Score: ${passed}/${total} (${pct}%)`));
+    console.log(pc.bold(`Score: ${passed}/${total} (${pct}%)`) + (baseline ? pc.dim(`  ·  without the standards ${basePassed}/${total} (${basePct}%)  ·  effect ${pct - basePct >= 0 ? "+" : ""}${pct - basePct} points`) : ""));
+    if (baseline && pct - basePct <= 0) console.log(pc.yellow("  The model did as well without these standards. They cost tokens on every prompt and changed nothing measurable here."));
     for (const r of report) {
       const failed = r.results.filter((x) => !x.pass);
       if (!failed.length) continue;
@@ -223,4 +243,4 @@ async function test(args) {
   }
 }
 
-module.exports = { test };
+module.exports = { test, pool, parseJSON };

package/src/detect.json

@@ -437,6 +437,7 @@
       ]
     }
   },
+  "pinProof": {},
   "categoryGlobs": {
     "Database": "**/*.sql,**/*.prisma,**/prisma/**,**/migrations/**,**/db/**,**/models/**,**/*repository*",
     "Frontend": "**/*.tsx,**/*.jsx,**/*.vue,**/*.svelte,**/*.css,**/app/**,**/components/**,**/pages/**",

package/src/lib/agents.js

@@ -55,67 +55,30 @@ const tokens = (text) => Math.ceil(String(text || "").length / 4);
 const ALWAYS_ON_BUDGET = 1500;
 
 /** Packages that earn a place in the core first when the budget is tight. */
-const CORE_PRIORITY = ["Security/owasp", "Review/code-review", "AI/agent-rules"];
-const CATEGORY_RANK = ["Security", "AI", "Review", "Backend", "Frontend", "Database", "API", "Testing", "Performance", "DevOps"];
-
 const idOf = (p) => `${p.category}/${p.preset}`;
 const posix = (file) => String(file).split(path.sep).join("/");
 
-function corePriority(p) {
-  const i = CORE_PRIORITY.indexOf(idOf(p));
-  if (i !== -1) return i;
-  const c = CATEGORY_RANK.indexOf(p.category);
-  return 100 + (c === -1 ? CATEGORY_RANK.length : c) * 10;
-}
-
 /**
- * A package's core: its hard rules and its checklist — the lines an agent
- * must hold on every prompt. Derived from the standard itself rather than
- * hand-written, so every package has one today; a canonical file can tighten
- * it by improving its own **Never** rules and checklist.
- */
-function coreOf(content, limit = 6) {
-  const body = String(content).replace(/^---[\s\S]*?---\s*/, "");
-  const lines = [];
-  for (const para of body.split(/\n\s*\n/)) {
-    const t = para.trim();
-    if (/^\*\*Never\*\*|^- \*\*Never/.test(t)) {
-      lines.push("- " + t.replace(/^[-*\s]*/, "").replace(/\*\*/g, "").replace(/\s*\n\s*/g, " "));
-    }
-  }
-  for (const m of body.match(/^- \[ \] .+$/gm) || []) {
-    if (lines.length >= limit) break;
-    lines.push("- " + m.replace(/^- \[ \] (Verify: )?/, ""));
-  }
-  if (lines.length) return lines.slice(0, limit);
-  // Older packages carry neither **Never** rules nor a checklist: fall back to
-  // their first substantive bullets so they still earn a place in the core.
-  return (body.match(/^- .{40,}$/gm) || []).slice(0, Math.min(4, limit)).map((l) => l.replace(/\*\*/g, ""));
-}
-
-/**
- * Decide what fits in the always-on block. Pins go first (they are the
- * highest-value lines in the file), then package cores in priority order
- * until the budget is spent. Without a `readPreset` there is nothing to
- * extract, and every package is listed as a link — the pre-budget shape.
+ * Decide what is always on. The answer is: the version pins, and nothing else.
+ *
+ * This used to fill the 1,500-token budget with the "core" of each installed
+ * standard — its **Never** rules and checklist — in a hand-ranked priority
+ * order. Three independent studies in 2026 then measured what always-on
+ * generic guidance does to a coding agent: no gain in task success, a cost
+ * increase above 20%, and a measurable drop when the instructions are noisy
+ * (Gloaguen et al., ETH Zurich, arXiv 2602.11988; Khatri, arXiv 2607.27250;
+ * "Why Does CLAUDE.md Keep Growing?", arXiv 2608.11095). Version-specific API
+ * facts were the exception, at +10–20 points (LibEvoBench, arXiv 2606.25402).
+ *
+ * So pins are always on, and every standard is on demand: linked from the
+ * block, and written as a path-scoped reference file for the agents that
+ * support one, so it loads when a matching file is open instead of on every
+ * prompt. The return shape is unchanged so callers that print it still work.
  */
 function planAlwaysOn(presets, pins = [], readPreset = null, budget = ALWAYS_ON_BUDGET) {
   const { renderPins } = require("./versions");
-  const core = [];
-  const demoted = [];
-  let used = tokens(renderPins(pins)) + 150; // header, section titles and footer
-  if (!readPreset) return { core, demoted: presets.slice(), used, budget };
-
-  for (const p of presets.slice().sort((a, b) => corePriority(a) - corePriority(b))) {
-    const content = readPreset(p);
-    const lines = content ? coreOf(content) : [];
-    if (!lines.length) { demoted.push(p); continue; }
-    const cost = tokens(lines.join("\n")) + tokens(idOf(p)) + 8;
-    if (used + cost > budget) { demoted.push(p); continue; }
-    used += cost;
-    core.push({ id: idOf(p), file: posix(p.file), lines });
-  }
-  return { core, demoted, used, budget };
+  const used = tokens(renderPins(pins)) + 150; // header, section titles and footer
+  return { core: [], demoted: presets.slice(), used, budget };
 }
 
 /**
@@ -298,4 +261,4 @@ function scopedRules(presets, readPreset) {
   return referenceRules(presets, readPreset, "cursor");
 }
 
-module.exports = { TARGETS, CATEGORY_GLOBS, REFERENCE_DIRS, ALWAYS_ON_BUDGET, applyToFile, renderBody, planAlwaysOn, coreOf, referenceRules, scopedRules, tokens, START, END };
+module.exports = { TARGETS, CATEGORY_GLOBS, REFERENCE_DIRS, ALWAYS_ON_BUDGET, applyToFile, renderBody, planAlwaysOn, referenceRules, scopedRules, tokens, START, END };

package/src/lib/analytics.js

@@ -46,10 +46,16 @@ function read(cwd = process.cwd()) {
 function record(cwd, { findings = [], standards = [], mode = "patterns", base = null } = {}) {
   try {
     const ledger = read(cwd);
+    // Which instructions were in force for this run — one hash over every
+    // file an agent reads. Lets a finding be traced to the exact context it
+    // was checked against, which is what an audit of agent-written code asks.
+    let contextHash = null;
+    try { contextHash = require("./bundle").contextDigest(cwd); } catch {}
     ledger.runs.push({
       at: new Date().toISOString(),
       mode,
       base,
+      contextHash,
       standards: standards.length,
       findings: findings.map((f) => ({
         severity: String(f.severity || "low"),