activate-agentmd 2.4.0 → 2.5.0

package/src/lib/bundle.js

@@ -0,0 +1,169 @@
+/**
+ * bundle.js
+ *
+ * Signed context bundles: a record, signed with the organisation's own key,
+ * of exactly which instruction files an agent in this repository reads —
+ * CLAUDE.md, AGENTS.md, rules, skills, hook settings, the installed
+ * standards — and the hash of each.
+ *
+ * Two questions it answers that nothing else does:
+ *
+ *   - Has anything an agent reads changed since it was approved? `verify`
+ *     names every modified, missing and unapproved file, so a PR that adds a
+ *     rule or edits a skill fails until someone with the key signs off.
+ *   - Which context was in play when this code was written? The digest is one
+ *     hash over every covered file; `attest` records it next to the commit,
+ *     which is the evidence an audit of agent-written code asks for.
+ *
+ * Agent Plugins 1.0 standardised how skills are packaged and explicitly left
+ * provenance and signing out. This is that missing piece, for the files an
+ * agent reads rather than the ones it installs.
+ *
+ * Trust: bundles are signed with the ORG's key, not Agent.md's — the license
+ * keyset is the wrong anchor for a customer's own context. Trusted public keys
+ * come from AGENTMD_BUNDLE_KEYS when set (use this in CI, from a secret, so a
+ * pull request cannot swap the key it is checked against), otherwise from
+ * `bundleKeys` in .agentmd/enterprise.json — which is itself covered, so
+ * editing the key list is a change that needs signing too.
+ *
+ * Limits, stated plainly: this is a gate in CI and in review, not runtime
+ * enforcement. Nothing here stops an agent from reading an unsigned file on a
+ * developer's machine; it stops that file from merging unnoticed.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { sign, verifySignature } = require("./license");
+const { findInstructionFiles } = require("./lint");
+
+const SIG_FILE = path.join(".agentmd", "bundle.sig");
+const TYPE = "agentmd-bundle";
+
+/** Per-developer files: never committed, so never part of the approved set. */
+const PERSONAL = /(^|\/)[^/]*\.local\.[^/]+$/;
+/** Written by the CLI as it runs — state, not instructions. */
+const NOT_CONTEXT = new Set([".agentmd/bundle.sig", ".agentmd/analytics.json"]);
+
+const posix = (p) => p.split(path.sep).join("/");
+const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
+
+function listFiles(dir) {
+  const out = [];
+  const walk = (d) => {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile()) out.push(full);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+/** Every file an agent reads as instructions, relative and POSIX, sorted. */
+function coveredFiles(cwd) {
+  const set = new Set(findInstructionFiles(cwd).map(posix));
+  for (const sub of ["presets", "overrides"]) {
+    for (const f of listFiles(path.join(cwd, ".agentmd", sub))) set.add(posix(path.relative(cwd, f)));
+  }
+  for (const f of [".agentmd/manifest.json", ".agentmd/enterprise.json"]) {
+    if (fs.existsSync(path.join(cwd, f))) set.add(f);
+  }
+  return [...set].filter((f) => !PERSONAL.test(f) && !NOT_CONTEXT.has(f)).sort();
+}
+
+/** The files and their hashes, plus one digest over the lot. */
+function snapshot(cwd) {
+  const files = coveredFiles(cwd).map((p) => ({ path: p, sha256: sha256(fs.readFileSync(path.join(cwd, p))) }));
+  const digest = sha256(files.map((f) => `${f.sha256}  ${f.path}\n`).join(""));
+  return { files, digest };
+}
+
+/** The current context digest, for audit records. Cheap: hashes a few files. */
+const contextDigest = (cwd) => snapshot(cwd).digest;
+
+/** A new Ed25519 key pair, base64 DER — the same format the license keyset uses. */
+function keygen() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  return {
+    publicKey: publicKey.export({ format: "der", type: "spki" }).toString("base64"),
+    privateKey: privateKey.export({ format: "der", type: "pkcs8" }).toString("base64"),
+  };
+}
+
+/** Sign what is on disk now and write .agentmd/bundle.sig. */
+function signBundle(cwd, privateKeyB64, kid, { days } = {}) {
+  const { files, digest } = snapshot(cwd);
+  const iat = Math.floor(Date.now() / 1000);
+  const claims = { type: TYPE, v: 1, iat, digest, files };
+  if (days) claims.exp = iat + days * 86400;
+  const token = sign(claims, privateKeyB64, kid);
+  const out = path.join(cwd, SIG_FILE);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, token + "\n", "utf-8");
+  return { files: files.length, digest, kid };
+}
+
+/** Trusted public keys: the environment wins, so CI can pin them from a secret. */
+function trustedKeys(cwd, env = process.env) {
+  let keys = null;
+  if (env.AGENTMD_BUNDLE_KEYS) {
+    try { keys = JSON.parse(env.AGENTMD_BUNDLE_KEYS); } catch { keys = null; }
+    if (keys && !Array.isArray(keys)) keys = keys.keys || null;
+    return { keys: Array.isArray(keys) ? keys : [], source: "AGENTMD_BUNDLE_KEYS" };
+  }
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(cwd, ".agentmd", "enterprise.json"), "utf-8"));
+    keys = Array.isArray(cfg.bundleKeys) ? cfg.bundleKeys : [];
+  } catch { keys = []; }
+  return { keys, source: ".agentmd/enterprise.json" };
+}
+
+/**
+ * Check the signature and compare the signed hashes to the files on disk.
+ * Returns { valid, reason?, kid?, signedAt?, digest, modified, missing, unapproved }.
+ */
+function verifyBundle(cwd, env = process.env) {
+  const current = snapshot(cwd);
+  const empty = { modified: [], missing: [], unapproved: [], digest: current.digest };
+
+  let token;
+  try { token = fs.readFileSync(path.join(cwd, SIG_FILE), "utf-8").trim(); } catch {
+    return { ...empty, valid: false, reason: `no ${posix(SIG_FILE)} — nothing has been signed` };
+  }
+  const { keys, source } = trustedKeys(cwd, env);
+  if (!keys.length) return { ...empty, valid: false, reason: `no trusted bundle keys in ${source}` };
+
+  const set = { keys: keys.map((k) => ({ alg: "ed25519", status: "active", ...k })), legacyKid: null };
+  const sig = verifySignature(token, set);
+  if (!sig.valid) return { ...empty, valid: false, kid: sig.kid, reason: `${posix(SIG_FILE)} ${sig.reason.replace(/^was not issued by Agent\.md/, "was not signed by a trusted key")}` };
+  const c = sig.claims;
+  if (c.type !== TYPE || !Array.isArray(c.files)) return { ...empty, valid: false, kid: sig.kid, reason: `${posix(SIG_FILE)} is not a context bundle` };
+  if (typeof c.exp === "number" && c.exp * 1000 < Date.now()) {
+    return { ...empty, valid: false, kid: sig.kid, reason: `the bundle expired on ${new Date(c.exp * 1000).toISOString().slice(0, 10)} — sign it again` };
+  }
+
+  const signed = new Map(c.files.map((f) => [f.path, f.sha256]));
+  const now = new Map(current.files.map((f) => [f.path, f.sha256]));
+  const modified = [...now].filter(([p, h]) => signed.has(p) && signed.get(p) !== h).map(([p]) => p);
+  const unapproved = [...now.keys()].filter((p) => !signed.has(p));
+  const missing = [...signed.keys()].filter((p) => !now.has(p));
+  const valid = !modified.length && !unapproved.length && !missing.length;
+
+  return {
+    valid,
+    reason: valid ? null : "the files an agent reads have changed since the bundle was signed",
+    kid: sig.kid,
+    signedAt: new Date(c.iat * 1000).toISOString(),
+    digest: current.digest,
+    signedDigest: c.digest,
+    modified, missing, unapproved,
+  };
+}
+
+module.exports = { coveredFiles, snapshot, contextDigest, keygen, signBundle, verifyBundle, trustedKeys, SIG_FILE };

package/src/lib/enterprise.js

@@ -40,6 +40,8 @@ const KNOWN = [
   "ssoProvider",
   "allowPublicRegistry",
   "pinnedStandards",
+  "bundleKeys",
+  "requireSignedContext",
   "$schema",
 ];
 
@@ -80,6 +82,9 @@ function load(cwd = process.cwd()) {
     // fetcher refuses one — this content becomes agent instructions.
     if (/^http:\/\//i.test(value)) problems.push(`${FILE}: \`${key}\` must be https, not http`);
   }
+  if (config.bundleKeys !== undefined && !(Array.isArray(config.bundleKeys) && config.bundleKeys.every((k) => k && typeof k.kid === "string" && typeof k.publicKey === "string"))) {
+    problems.push(`${FILE}: \`bundleKeys\` must be an array of { kid, publicKey }`);
+  }
   if (config.pinnedStandards !== undefined && !Array.isArray(config.pinnedStandards)) {
     problems.push(`${FILE}: \`pinnedStandards\` must be an array`);
   }
@@ -91,6 +96,7 @@ function load(cwd = process.cwd()) {
     privateRegistry: process.env.AGENTMD_PRIVATE_REGISTRY || config.privateRegistry || null,
     cloudUrl: process.env.AGENTMD_CLOUD_URL || config.cloudUrl || null,
     requireSso: config.requireSso === true,
+    requireSignedContext: config.requireSignedContext === true,
     allowPublicRegistry: config.allowPublicRegistry !== false,
   };
 
@@ -102,7 +108,7 @@ function init(cwd = process.cwd(), values = {}) {
   const file = path.join(cwd, FILE);
   if (fs.existsSync(file)) throw new Error(`${FILE} already exists`);
   const body = {
-    $schema: "https://agent-dot-md.vercel.app/schema/enterprise.json",
+    $schema: "https://agentmd.pages.dev/schema/enterprise.json",
     privateRegistry: values.privateRegistry || "https://standards.example.internal/agentmd",
     cloudUrl: values.cloudUrl || null,
     licenseKey: values.licenseKey || "",

package/src/lib/license.js

@@ -134,7 +134,13 @@ function publicKeyOf(record) {
  * not a stack trace. Reasons read as a predicate, because they are printed
  * after "That key …" and "The key from <source> …".
  */
-function verify(key, set = keyset()) {
+/**
+ * The signature half of verification, shared by licenses and context bundles:
+ * well-formed, signed by a key in `set`, and that key not revoked. What the
+ * claims must say is the caller's business — a license needs a paid plan, a
+ * bundle needs to match the files on disk.
+ */
+function verifySignature(key, set = keyset()) {
   if (typeof key !== "string" || !key.startsWith(PREFIX)) {
     return { valid: false, reason: "is not an Agent.md license key — one starts with `agmd_`" };
   }
@@ -186,6 +192,13 @@ function verify(key, set = keyset()) {
     ok = false;
   }
   if (!ok) return { valid: false, kid, reason: "was not issued by Agent.md — the signature does not match" };
+  return { valid: true, claims, kid };
+}
+
+function verify(key, set = keyset()) {
+  const sig = verifySignature(key, set);
+  if (!sig.valid) return sig;
+  const { claims, kid } = sig;
 
   if (!PAID_PLANS.includes(claims.plan)) {
     return { valid: false, kid, claims, reason: `is for the \`${claims.plan || "none"}\` plan, which does not include Pro features` };
@@ -229,6 +242,6 @@ function daysLeft(claims) {
 }
 
 module.exports = {
-  verify, sign, fingerprint, daysLeft, keyset, findKey, canSign,
+  verify, verifySignature, sign, fingerprint, daysLeft, keyset, findKey, canSign,
   PAID_PLANS, PREFIX, VERIFIES,
 };

package/src/lib/lint-text.js

@@ -0,0 +1,150 @@
+/**
+ * lint-text.js
+ *
+ * The content-only half of `agentmd lint`: the checks that need nothing but
+ * the text of one instruction file — secrets, prompt injection, invisible
+ * Unicode, hidden HTML-comment instructions, base64 payloads, bloat, /init
+ * fossils.
+ *
+ * It has no dependencies on purpose. The CLI runs it over files on disk; the
+ * website's /inspect page runs the very same function in the browser over a
+ * pasted CLAUDE.md. One implementation, so the two can never disagree about
+ * what counts as an injection. The checks that need the rest of the project
+ * (dead references, formatter config, version pins) stay in lint.js.
+ */
+
+"use strict";
+
+
+// ── Prose extraction ───────────────────────────────────────────────────────
+
+/**
+ * Lines with code stripped: fenced blocks blanked, inline code removed. Line
+ * numbers are preserved so findings point at the right place.
+ */
+function proseLines(text) {
+  let fence = false;
+  return text.split("\n").map((line) => {
+    if (/^\s*(```|~~~)/.test(line)) { fence = !fence; return ""; }
+    if (fence) return "";
+    return line.replace(/`[^`]*`/g, "").replace(/"[^"\n]{0,200}"/g, "\"\"");
+  });
+}
+
+/** A line that warns against something is teaching, not instructing. */
+const NEGATED = /\b(never|don['’]?t|do not|must not|avoid|forbid|forbidden|disallow|block|reject|prevent|attack|malicious|example of)\b|❌|🚫|✗/i;
+
+// ── Rules ──────────────────────────────────────────────────────────────────
+
+const SECRETS = [
+  { name: "Anthropic API key", re: /\bsk-ant-(?:api|admin)\d{2}-[A-Za-z0-9_-]{20,}/ },
+  { name: "OpenAI API key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{40,}/ },
+  { name: "GitHub token", re: /\bgh[pousr]_[A-Za-z0-9]{36,}/ },
+  { name: "GitHub fine-grained token", re: /\bgithub_pat_[A-Za-z0-9_]{60,}/ },
+  { name: "AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  { name: "Slack token", re: /\bxox[baprs]-[A-Za-z0-9-]{20,}/ },
+  { name: "Stripe live key", re: /\b[sr]k_live_[A-Za-z0-9]{20,}/ },
+  { name: "Google API key", re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { name: "private key", re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
+  // A generic assignment of a long opaque value to a secret-sounding name.
+  { name: "hard-coded secret", re: /\b(?:api[_-]?key|secret|password|passwd|token|auth[_-]?token)\b\s*[:=]\s*["']?[A-Za-z0-9_\-/+=]{24,}["']?/i },
+];
+
+/** Placeholders people write on purpose. */
+const PLACEHOLDER = /x{6,}|\*{4,}|<[A-Z_ -]+>|\$\{|\$[A-Z_]+|process\.env|os\.environ|getenv|your[-_ ]?(api[-_ ]?)?(key|token|secret)|example|placeholder|changeme|redacted|dummy|fake|test[-_]?key|\.\.\./i;
+
+// Zero-width, bidi overrides and Unicode tag characters: invisible to the
+// reviewer, read by the model. ZWJ (U+200D) is excluded — emoji use it.
+const INVISIBLE = /[\u200B\u200C\u200E\u200F\u202A-\u202E\u2060-\u2064]|[\u{E0000}-\u{E007F}]/u;
+
+const OVERRIDE_PHRASE = /\b(ignore|disregard|forget|override)\b[^.\n]{0,30}\b(previous|prior|above|earlier|all|system|your)\b[^.\n]{0,20}\b(instructions?|prompts?|rules?|guidelines?|context)\b/i;
+const PERMISSION_BYPASS = /--dangerously-skip-permissions\b|--yolo\b|"?\bbypassPermissions\b"?|--no-sandbox\b|\bauto[-_ ]?approve\s+(all|every)/i;
+const PIPE_TO_SHELL = /\b(curl|wget|iwr|Invoke-WebRequest)\b[^|\n]*\|\s*(sudo\s+)?(ba|z|da)?sh\b|\b(iex|Invoke-Expression)\b/i;
+const HIDDEN_DIRECTIVE = /\b(curl|wget|upload|exfiltrat|send\b[^.]{0,40}\bto\b|post\b[^.]{0,40}\bto\b|ignore|disregard|do not (tell|mention|reveal|show)|don['’]?t (tell|mention|reveal|show)|without (telling|asking|mentioning)|secretly|silently)\b/i;
+const BASE64_BLOB = /(?<!base64,)(?<![A-Za-z0-9+/])[A-Za-z0-9+/]{200,}={0,2}/;
+
+const FOSSIL = /This file provides guidance to Claude Code \(claude\.ai\/code\) when working with code in this repository/;
+
+function finding(file, line, severity, rule, message) {
+  return { file, line, severity, rule, message };
+}
+
+function lineOf(text, needle) {
+  const i = text.indexOf(needle);
+  return i === -1 ? 1 : text.slice(0, i).split("\n").length;
+}
+
+/**
+ * Check the text of one instruction file.
+ *
+ *   file      path shown in findings
+ *   alwaysOn  whether the agent loads it on every prompt (bloat applies only then)
+ *   budget    always-on token budget; bloat warns at twice it
+ */
+function lintText(text, { file = "CLAUDE.md", alwaysOn = true, budget = 1500 } = {}) {
+  const out = [];
+  const raw = text.split("\n");
+  const prose = proseLines(text);
+
+  raw.forEach((line, i) => {
+    const n = i + 1;
+
+    // Secrets: every line, code included — a key in a code block is still a key.
+    for (const s of SECRETS) {
+      const m = s.re.exec(line);
+      if (m && !PLACEHOLDER.test(m[0])) {
+        out.push(finding(file, n, "error", "secret", `Looks like ${/^[aeiou]/i.test(s.name) ? "an" : "a"} ${s.name}. Instruction files are sent to the model on every session — rotate it, then read it from the environment.`));
+        break;
+      }
+    }
+
+    // Invisible characters: every line, code included — there is no
+    // legitimate reason to hide text from the person reviewing the file.
+    // A BOM at the very start of the file is the one exception.
+    const scan = i === 0 ? line.replace(/^\uFEFF/, "") : line;
+    if (INVISIBLE.test(scan)) {
+      out.push(finding(file, n, "error", "injection", "Invisible Unicode (zero-width, bidi override or tag characters) — the model reads it, a reviewer does not. Remove it."));
+    }
+
+    // Hidden directives inside HTML comments: rendered invisible on GitHub,
+    // delivered verbatim to the agent. Our own managed-block markers are fine.
+    for (const c of line.matchAll(/<!--([\s\S]*?)-->/g)) {
+      if (/agentmd:(start|end)/.test(c[1])) continue;
+      if (HIDDEN_DIRECTIVE.test(c[1])) {
+        out.push(finding(file, n, "error", "injection", "An HTML comment carries an instruction. GitHub hides comments from reviewers but the agent reads them — move it into the visible text or delete it."));
+      }
+    }
+
+    if (BASE64_BLOB.test(line)) {
+      out.push(finding(file, n, "warning", "injection", "A long base64 run — an agent can decode and follow it, a reviewer cannot read it. Link to the file instead."));
+    }
+
+    const p = prose[i];
+    if (!p || NEGATED.test(p)) return;
+    if (OVERRIDE_PHRASE.test(p)) {
+      out.push(finding(file, n, "error", "injection", "Tells the agent to ignore its other instructions — the signature of a prompt injection. Remove it, or quote it if you are documenting the attack."));
+    }
+    if (PERMISSION_BYPASS.test(p)) {
+      out.push(finding(file, n, "error", "injection", "Tells the agent to bypass its permission prompts. An instruction file is untrusted input; it must not grant itself authority."));
+    }
+    if (PIPE_TO_SHELL.test(p)) {
+      out.push(finding(file, n, "warning", "injection", "Pipes a download into a shell. If the agent is meant to run this, pin the script in the repo instead."));
+    }
+  });
+
+  // Bloat: only files the agent reads on every prompt. Reference files and
+  // skills load on demand, so their size costs nothing until they are used.
+  if (alwaysOn) {
+    const t = Math.ceil(text.length / 4);
+    if (raw.length >= 200 || t > budget * 2) {
+      out.push(finding(file, 1, "warning", "bloat", `${raw.length} lines, ~${t} tokens, loaded on every prompt. Move task-specific sections into on-demand rules or skills; keep only what the agent cannot infer from the code.`));
+    }
+    if (FOSSIL.test(text)) {
+      out.push(finding(file, lineOf(text, "This file provides guidance"), "notice", "fossil", "`/init` boilerplate. Generated files that are never edited go stale while the code moves on — review it or delete the line."));
+    }
+  }
+
+  return out;
+}
+
+module.exports = { lintText, proseLines, finding, lineOf, PIPE_TO_SHELL };

package/src/lib/lint.js

@@ -0,0 +1,213 @@
+/**
+ * lint.js
+ *
+ * Checks the files a coding agent reads before it reads your code: CLAUDE.md,
+ * AGENTS.md, Cursor and Copilot rules, Claude skills and hook settings.
+ *
+ * Nothing else watches these. Secret scanners skip them, skill scanners stop
+ * at SKILL.md (snyk/agent-scan#301), and they go straight into the model's
+ * context — so a pasted key or a hidden instruction lands exactly where it
+ * does the most harm. The rules below come from what 2026 measured:
+ *
+ *   secrets     ~0.7% of public instruction files hold a live credential,
+ *               mostly pasted by hand (Radware, "The New .env", Aug 2026)
+ *   injection   rule files are a prompt-injection channel; a malicious rule
+ *               can exfiltrate while the agent still produces a correct patch
+ *               (Aletheia, arXiv 2609.39678)
+ *   bloat       always-on files grow +226% over their lifetime, and noise
+ *               costs instruction-following accuracy (arXiv 2608.11095)
+ *   smells      91 of the 100 most-starred repos carry at least one: blind
+ *               references, lint leakage, init fossils (arXiv 2606.15828)
+ *
+ * Precision over recall, everywhere. This runs as a CI gate, and one false
+ * positive teaches a team to ignore it. Injection rules therefore read prose
+ * only — not code fences, not inline code, not lines that warn *against* the
+ * thing ("never", "❌") — because security standards quote attacks to teach
+ * them, and ours do.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { TARGETS, ALWAYS_ON_BUDGET, START, END } = require("./agents");
+const { detectVersions, renderPins } = require("./versions");
+const { cmd } = require("./invocation");
+const { lintText, proseLines, finding, lineOf, PIPE_TO_SHELL } = require("./lint-text");
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "vendor", ".venv", "venv", "target", "coverage"]);
+const MAX_DEPTH = 4;
+
+/** Files read on every prompt. Bloat only matters for these. */
+const ALWAYS_ON_NAMES = new Set(["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", "AGENTS.override.md", "GEMINI.md", ".cursorrules", ".windsurfrules", "copilot-instructions.md"]);
+
+/** Instruction files anywhere in the tree (monorepos nest them). */
+const NESTED_NAMES = new Set(["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", "AGENTS.override.md", "GEMINI.md"]);
+
+// ── Discovery ──────────────────────────────────────────────────────────────
+
+function walk(dir, depth, visit) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name) || depth >= MAX_DEPTH) continue;
+      walk(full, depth + 1, visit);
+    } else if (e.isFile()) {
+      visit(full, e.name);
+    }
+  }
+}
+
+function listDir(dir, test) {
+  try { return fs.readdirSync(dir).filter(test).map((f) => path.join(dir, f)); } catch { return []; }
+}
+
+/** Every agent-instruction file in the project, relative paths, deduplicated. */
+function findInstructionFiles(cwd) {
+  const found = new Set();
+  const add = (abs) => { if (fs.existsSync(abs)) found.add(path.relative(cwd, abs)); };
+
+  for (const t of Object.values(TARGETS)) add(path.join(cwd, t.file));
+  for (const f of [".cursorrules", ".windsurfrules", "CLAUDE.local.md", "AGENTS.override.md"]) add(path.join(cwd, f));
+  for (const f of listDir(path.join(cwd, ".claude", "rules"), (n) => n.endsWith(".md"))) add(f);
+  for (const f of listDir(path.join(cwd, ".cursor", "rules"), (n) => n.endsWith(".mdc") || n.endsWith(".md"))) add(f);
+  for (const f of listDir(path.join(cwd, ".github", "instructions"), (n) => n.endsWith(".md"))) add(f);
+  for (const f of listDir(path.join(cwd, ".claude"), (n) => /^settings(\.local)?\.json$/.test(n))) add(f);
+
+  // Skills, at any depth under .claude/skills — they run scripts.
+  walk(path.join(cwd, ".claude", "skills"), 0, (abs, name) => { if (name === "SKILL.md") add(abs); });
+  // Nested instruction files in workspaces.
+  walk(cwd, 0, (abs, name) => { if (NESTED_NAMES.has(name)) add(abs); });
+
+  return [...found].sort();
+}
+
+const FORMATTER_FILES = [".prettierrc", ".prettierrc.json", ".prettierrc.js", ".prettierrc.cjs", ".prettierrc.yaml", ".prettierrc.yml", "prettier.config.js", "prettier.config.mjs", "biome.json", "biome.jsonc", ".editorconfig", "ruff.toml", ".ruff.toml", "rustfmt.toml", ".rustfmt.toml", "dprint.json", ".clang-format"];
+const LINT_LEAK = /\b(indent(ation)?\s+(with|of|using|is)|\d\s+spaces?\b|tabs?\s+(for|not|over|instead)|semicolons?|trailing commas?|single quotes|double quotes|(max(imum)?\s+)?line length|lines? (under|below|shorter than|no longer than) \d+)\b/i;
+
+
+
+function hasFormatter(cwd) {
+  if (FORMATTER_FILES.some((f) => fs.existsSync(path.join(cwd, f)))) return true;
+  try {
+    const py = fs.readFileSync(path.join(cwd, "pyproject.toml"), "utf-8");
+    if (/^\[tool\.(ruff|black)\b/m.test(py)) return true;
+  } catch {}
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
+    if (pkg.prettier) return true;
+  } catch {}
+  return false;
+}
+
+/** Hooks are commands the agent runs on its own: check what they execute. */
+function lintSettings(file, text) {
+  const out = [];
+  let json;
+  try { json = JSON.parse(text); } catch { return out; }
+  const commands = [];
+  const visit = (v) => {
+    if (Array.isArray(v)) v.forEach(visit);
+    else if (v && typeof v === "object") {
+      if (typeof v.command === "string") commands.push(v.command);
+      Object.values(v).forEach(visit);
+    }
+  };
+  visit(json.hooks);
+  for (const c of commands) {
+    if (PIPE_TO_SHELL.test(c)) {
+      out.push(finding(file, lineOf(text, c), "error", "injection", "A hook pipes a download straight into a shell. Hooks run without a prompt — pin the script in the repo and run it from there."));
+    }
+  }
+  if (json.permissions && Array.isArray(json.permissions.allow) && json.permissions.allow.some((r) => /^Bash\(\s*\*?\s*\)$|^Bash$/.test(String(r)))) {
+    out.push(finding(file, lineOf(text, "\"allow\""), "warning", "permissions", "`Bash` is allowed without a pattern, so any instruction file can make the agent run any command. Scope it, e.g. `Bash(npm test:*)`."));
+  }
+  return out;
+}
+
+
+/** Check one instruction file. `ctx` carries the project-level facts. */
+function lintFile(cwd, file, ctx) {
+  const abs = path.join(cwd, file);
+  let text;
+  try { text = fs.readFileSync(abs, "utf-8"); } catch { return []; }
+  if (file.endsWith(".json")) return lintSettings(file, text);
+
+  const out = [];
+  const raw = text.split("\n");
+  const prose = proseLines(text);
+  const base = path.basename(file);
+
+  // Everything that needs only the text: secrets, injection, bloat, fossils.
+  const alwaysOn = ALWAYS_ON_NAMES.has(base) || (file.endsWith(".mdc") && /^alwaysApply:\s*true/m.test(text));
+  out.push(...lintText(text, { file, alwaysOn, budget: ALWAYS_ON_BUDGET }));
+
+  // Blind references: `@file` imports and relative links that point nowhere.
+  prose.forEach((line, i) => {
+    const targets = [];
+    for (const m of line.matchAll(/(?:^|\s)@((?:[\w.-]+\/)*[\w.-]+\.[A-Za-z]{1,6})\b/g)) targets.push(m[1]);
+    for (const m of line.matchAll(/\]\((?!https?:|mailto:|#|\/)([^)\s]+)\)/g)) targets.push(m[1].split("#")[0]);
+    for (const t of targets) {
+      if (!t) continue;
+      const resolved = path.resolve(path.dirname(abs), decodeURI(t));
+      if (!fs.existsSync(resolved)) {
+        out.push(finding(file, i + 1, "warning", "blind-reference", `\`${t}\` does not exist. The agent will search for it, or guess.`));
+      }
+    }
+  });
+
+  // Lint leakage: formatting rules the formatter already enforces.
+  if (ctx.formatter && alwaysOn) {
+    prose.forEach((line, i) => {
+      if (LINT_LEAK.test(line)) {
+        out.push(finding(file, i + 1, "notice", "lint-leakage", "A formatting rule this project's formatter already enforces. It costs tokens on every prompt and changes nothing — delete it."));
+      }
+    });
+  }
+
+  // Stale pins: the managed block was written for different majors than the
+  // project now runs. This is the whole of "keep your agent's context in step
+  // with your dependencies" — a check in CI, not a bot.
+  const s = text.indexOf(START), e = text.indexOf(END);
+  if (s !== -1 && e > s && !file.endsWith(".mdc")) {
+    const block = text.slice(s, e);
+    const expected = ctx.pinBlock;
+    const stale = expected ? !block.includes(expected) : block.includes("### Version pins");
+    if (stale) {
+      out.push(finding(file, lineOf(text, START), "warning", "stale-pins", `The version pins in the agentmd block do not match the dependencies this project now runs. Run \`${cmd("link")}\`.`));
+    }
+  }
+
+  return out;
+}
+
+const contextFor = (cwd) => ({ formatter: hasFormatter(cwd), pinBlock: renderPins(detectVersions(cwd)) });
+
+/** Lint every instruction file in `cwd`. */
+function lintProject(cwd) {
+  const files = findInstructionFiles(cwd);
+  const ctx = contextFor(cwd);
+  const findings = [];
+  for (const f of files) findings.push(...lintFile(cwd, f, ctx));
+
+  // An org that requires signed context fails lint on any unsigned change.
+  // Required lazily: bundle.js depends on this module for file discovery.
+  let policy = {};
+  try { policy = JSON.parse(fs.readFileSync(path.join(cwd, ".agentmd", "enterprise.json"), "utf-8")); } catch {}
+  if (policy && policy.requireSignedContext === true) {
+    const r = require("./bundle").verifyBundle(cwd);
+    if (!r.valid) {
+      const changed = [...r.modified, ...r.unapproved, ...r.missing];
+      findings.push(finding(".agentmd/bundle.sig", 1, "error", "unsigned-context",
+        `This project requires signed context, and ${r.reason}${changed.length ? `: ${changed.join(", ")}` : ""}. Review, then \`${cmd("bundle sign")}\`.`));
+    }
+  }
+  return { files, findings };
+}
+
+/** Lint one file, given relative to `cwd`. Used by the editor hook. */
+const lintPath = (cwd, file) => lintFile(cwd, file, contextFor(cwd));
+
+module.exports = { lintProject, lintFile, lintPath, findInstructionFiles, proseLines };

package/src/lib/manifest.js

@@ -41,6 +41,14 @@ function resolvePresetPath(cwd, filename) {
   if (typeof filename !== "string" || filename.length === 0) {
     throw new Error("Invalid preset filename");
   }
+  // Manifest entries store `.agentmd/presets/<name>.md`, and callers hand
+  // that straight in. It used to resolve to `.agentmd/presets/.agentmd/...`,
+  // a file that never exists — so `test` found nothing to test and model
+  // `review` reviewed against zero standards, silently, on every real
+  // install. Strip exactly that prefix; anything else is still checked below.
+  const posix = filename.split("\\").join("/");
+  const prefix = PRESETS_DIR.split(path.sep).join("/") + "/";
+  if (posix.startsWith(prefix)) filename = posix.slice(prefix.length);
   const dir = path.resolve(getPresetsDir(cwd));
   const target = path.resolve(dir, filename);
   if (target !== path.join(dir, path.basename(target)) || !target.startsWith(dir + path.sep)) {