@linchpinagency/skills 0.1.10 → 0.1.11

package/README.md

@@ -12,7 +12,7 @@ GitHub Copilot, and other compatible coding agents.
 ![Zero dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)
 
 <!-- x-release-please-start-version -->
-### Latest release: 0.1.10
+### Latest release: 0.1.11
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |
@@ -66,9 +66,10 @@ Then start a new session in your project and ask for something real — "what ki
 is this?" should pull in `project-context` and get you a summary of the repo shape, local
 environment, and host.
 
-**Re-run the same command to update.** There's no upgrade command; the installer overwrites
-in place and always pulls the latest published version. Do it every few weeks, or when
-someone announces a new skill.
+**Re-run the same command to update.** There's no upgrade command — the installer diffs each
+skill's version against what you have, shows what would change, and asks before applying it.
+A run with nothing to change exits immediately, so re-running costs nothing. Do it every few
+weeks, or when someone announces a new skill.
 
 Full flag reference: [Install options](#install-options).
 
@@ -87,7 +88,7 @@ The fastest way to understand the library is to run one loop end to end:
 | Handle a client support ticket | "the client says their contact form isn't sending" | `support-triage` |
 | Add guardrails before touching prod | "careful mode — I'm on production" | `safety-hooks` |
 
-The full list is in [Available skills](#available-skills) — 20 of them, each with a
+The full list is in [Available skills](#available-skills) — 23 of them, each with a
 `When to use` section that says exactly when it applies and which skill to use instead.
 
 **When you want to be explicit**, name the skill: *"use the wp-audit skill on the homepage."*
@@ -177,6 +178,9 @@ npx @linchpinagency/skills --global
 
 # Install the Linchpin skills only, without the upstream base layer
 npx @linchpinagency/skills --skip-upstream
+
+# Audit every scope for duplicate installs; install nothing
+npx @linchpinagency/skills --check
 ```
 
 > Pin a version when you need reproducibility — `npx @linchpinagency/skills@0.1.1` — or omit
@@ -188,8 +192,38 @@ npx @linchpinagency/skills --skip-upstream
 > network access and a system `tar`; if either is missing it warns and still installs the
 > Linchpin skills. Pass `--skip-upstream` to install the Linchpin skills alone.
 
-**Updating:** re-run the same command. The installer overwrites each skill in place, so a
-fresh run always pulls the latest published version.
+**Updating:** re-run the same command — that *is* the update path. Rather than overwriting
+silently, the installer compares each skill's own `version` against what is installed,
+prints the diff, and asks before touching anything:
+
+```
+@linchpinagency/skills v0.2.0 — Claude Code
+
+  task-tracking        v1.3.0 -> v1.4.0   update
+  agent-capabilities            -> v1.0.0   new
+  quality-gates        v1.0.0             local edits will be lost
+  (20 unchanged)
+
+3 change(s): 1 update, 1 new, 1 modified
+
+Apply? [y/N]
+```
+
+A run with nothing to change says so and exits without prompting, so re-running is cheap
+and safe. `--dry-run` shows the diff and writes nothing; `--yes` skips the prompt;
+`--force` reinstalls everything regardless.
+
+> A **non-interactive** run — piped stdin, CI, a script — proceeds without prompting, so
+> existing automation keeps working. Use `--dry-run` when you want a preview rather than an
+> install.
+
+Three statuses are worth knowing:
+
+- **local edits will be lost** — the installed copy was hand-edited. Skills are owned by
+  this package; change them here and re-install rather than editing an install in place.
+- **DOWNGRADE** — the package you invoked is *older* than what is installed. Usually a
+  pinned `npx @linchpinagency/skills@0.1.1` you meant to drop.
+- **new** — the skill did not exist in your installed version.
 
 ### Keeping skills current
 
@@ -231,6 +265,34 @@ skips itself whenever `CI` is set.
 A project that wants skills in more than one agent's directory should run
 `--agent all` rather than copying directories around by hand.
 
+### One scope per skill
+
+Agents load **every** skills directory they find and **do not dedupe by name**. A skill
+installed both globally and in a project is listed twice, and its `description` is loaded
+twice in every session before any work starts.
+
+So the installer refuses to create the second copy:
+
+```
+Refusing to install: 22 of these skills are already installed at another scope.
+```
+
+It reports which directory, what would be duplicated, and the command to remove just the
+overlapping skills — never the whole directory, which usually holds skills from other
+sources too. `--force` overrides it for the rare case where you want both.
+
+```bash
+npx @linchpinagency/skills --check                  # audit; exits 1 if duplicates exist
+npx @linchpinagency/skills --check --agent codex    # a different agent's directories
+```
+
+`--check` also catches the accident that is easiest to miss: an install in a *parent* of the
+repo (running the installer from `~/GitHub` rather than inside a checkout), which shadows
+nothing and duplicates everything below it.
+
+Choosing a scope, the MCP-server equivalent of the same problem, and how to record the
+decision are covered by [`agent-capabilities`](skills/agent-capabilities/SKILL.md).
+
 > Skills are loaded by the **agent/harness**, not the model — so "Copilot running Claude"
 > still needs the skill installed in Copilot's own directory. The installer handles that.
 
@@ -251,6 +313,7 @@ A project that wants skills in more than one agent's directory should run
 | `wp-implementation-choice` | WordPress | Decide what a request should become — theme work, content, a custom block, a functionality plugin, or an existing plugin — before any code is written. |
 | `design-previews` | Design | Generate three genuinely different visual directions as self-contained HTML previews, screenshot them at desktop and mobile via the Chrome DevTools MCP (or Playwright), and get a pick before theme or block work starts. |
 | `project-context` | Workflow | Orient before acting — repo shape, local environment, host, ClickUp space, and release model, read from the project's own config rather than assumed. Referenced by other skills' Preflight. |
+| `agent-capabilities` | Workflow | Right-size what a project loads — audit skill installs for cross-scope duplicates (`--check`), decide which MCP servers the repo actually needs, and scope them so every session stops paying for all of them. |
 | `quality-gates` | Workflow | Run a project's own lint, PHPCS, PHPStan, and test gates before committing — detected from `composer.json`, `package.json`, `phpcs.xml.dist`, and `lint-staged`, never assumed. |
 | `web-qa` | Workflow | QA like a real user and fix what you find — front end, wp-admin, and block editor, with severity, evidence, one atomic commit per fix, and a report-only mode. |
 | `investigate` | Workflow | Root-cause a bug before changing anything — reproduce, read the real error, isolate the layer, explain the mechanism, with WordPress first checks. |

package/bin/install.mjs

@@ -9,6 +9,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -40,13 +42,28 @@ function resolveAgents(id) {
 }
 
 function parseArgs(argv) {
-  const opts = { agent: 'claude-code', global: false, list: false, help: false, skipUpstream: false, skills: [] };
+  const opts = {
+    agent: 'claude-code',
+    global: false,
+    list: false,
+    help: false,
+    skipUpstream: false,
+    force: false,
+    check: false,
+    yes: false,
+    dryRun: false,
+    skills: [],
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--global' || a === '-g') opts.global = true;
     else if (a === '--list' || a === '-l') opts.list = true;
     else if (a === '--help' || a === '-h') opts.help = true;
     else if (a === '--skip-upstream') opts.skipUpstream = true;
+    else if (a === '--force' || a === '-f') opts.force = true;
+    else if (a === '--check') opts.check = true;
+    else if (a === '--yes' || a === '-y') opts.yes = true;
+    else if (a === '--dry-run' || a === '-n') opts.dryRun = true;
     else if (a === '--agent') opts.agent = argv[++i];
     else if (a.startsWith('--agent=')) opts.agent = a.slice('--agent='.length);
     else if (a.startsWith('-')) {
@@ -78,6 +95,206 @@ function availableSkills() {
     .sort();
 }
 
+// --- Scope collisions ----------------------------------------------------------------
+// Agents load every skills directory they can see and do NOT dedupe by name. The same
+// skill installed at two scopes is therefore listed twice and its `description` is paid
+// for twice in the context window, every session, before any work starts. Installing on
+// top of an install at another scope is always waste, never a merge — so we stop.
+
+function installedSkillsIn(dir) {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function readStamp(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, STAMP_DIR, STAMP_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Every directory the selected agents also read, other than the ones we're about to write:
+// the opposite scope, plus any project-scope dir in a parent directory. That last case is
+// the one people hit by accident — running the installer from a checkouts folder like
+// ~/GitHub instead of inside a repo seeds a directory that shadows nothing and duplicates
+// everything.
+function rivalDirs(agentIds, opts) {
+  const home = os.homedir();
+  const seen = new Set();
+  const out = [];
+  const add = (dir, scope) => {
+    const resolved = path.resolve(dir);
+    if (seen.has(resolved)) return;
+    seen.add(resolved);
+    out.push({ dir: resolved, scope });
+  };
+
+  for (const id of agentIds) {
+    const opposite = opts.global ? AGENTS[id].project : AGENTS[id].global;
+    const oppositeRoot = opts.global ? process.cwd() : home;
+    for (const rel of opposite) add(path.join(oppositeRoot, rel), opts.global ? 'project' : 'global');
+
+    // Walk up to, but not into, home — home is the global scope, already covered above.
+    let cur = path.dirname(process.cwd());
+    while (cur.startsWith(home + path.sep)) {
+      for (const rel of AGENTS[id].project) add(path.join(cur, rel), 'ancestor');
+      const next = path.dirname(cur);
+      if (next === cur) break;
+      cur = next;
+    }
+  }
+  return out;
+}
+
+function findCollisions(agentIds, opts, wanted, targetDirs) {
+  const mine = new Set(targetDirs.map((d) => path.resolve(d)));
+  const want = new Set(wanted);
+  return rivalDirs(agentIds, opts)
+    .filter((r) => !mine.has(r.dir))
+    .map((r) => {
+      const present = installedSkillsIn(r.dir);
+      return { ...r, present, overlap: present.filter((n) => want.has(n)), stamp: readStamp(r.dir) };
+    })
+    .filter((r) => r.present.length);
+}
+
+function stampLine(stamp) {
+  if (!stamp) return 'no install stamp — copied by hand, or by a pre-0.2 installer';
+  return `v${stamp.version}, ${stamp.scope} scope, installed ${String(stamp.installedAt).slice(0, 10)}`;
+}
+
+const SCOPE_HINT = {
+  global: 'the user-global directory — loaded in every project',
+  project: 'a project directory — loaded when working in that repo',
+  ancestor: 'a parent of the current directory — almost certainly an installer run from the wrong folder',
+};
+
+// --- Update planning -----------------------------------------------------------------
+// Re-running the installer is the update path, so a re-run should say what it is about to
+// change before it changes it. Skills carry their own `version` in frontmatter, so the diff
+// is per skill rather than per package — a release usually touches two or three of them.
+
+function readSkillVersion(skillDir) {
+  try {
+    const md = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+    const fm = md.match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) return null;
+    const v = fm[1].match(/^version:\s*(.*)$/m);
+    return v ? v[1].replace(/^["']|["']$/g, '').trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+// Content fingerprint over every file in the skill, so we can tell "same version, edited
+// in place" from "same version, untouched". Hand-edits in a consuming project get silently
+// overwritten by an install; the least we can do is name them first.
+function hashSkillDir(dir) {
+  const h = crypto.createHash('sha1');
+  const walk = (cur, rel) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(cur, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const next = path.join(cur, e.name);
+      const nextRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(next, nextRel);
+      else {
+        h.update(nextRel);
+        h.update('\0');
+        try {
+          h.update(fs.readFileSync(next));
+        } catch {
+          /* unreadable file — its absence from the hash is itself a difference */
+        }
+      }
+    }
+  };
+  walk(dir, '');
+  return h.digest('hex');
+}
+
+function compareSemver(a, b) {
+  if (!a || !b) return null;
+  const pa = String(a).split('.').map((n) => parseInt(n, 10));
+  const pb = String(b).split('.').map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// What installing `wanted` into `base` would actually do, per skill.
+function planFor(base, wanted) {
+  return wanted.map((name) => {
+    const src = path.join(SKILLS_ROOT, name);
+    const dest = path.join(base, name);
+    const to = readSkillVersion(src);
+    if (!fs.existsSync(path.join(dest, 'SKILL.md'))) return { name, from: null, to, status: 'new' };
+
+    const from = readSkillVersion(dest);
+    const cmp = compareSemver(from, to);
+    if (cmp === -1) return { name, from, to, status: 'update' };
+    if (cmp === 1) return { name, from, to, status: 'downgrade' };
+    if (hashSkillDir(src) !== hashSkillDir(dest)) return { name, from, to, status: 'modified' };
+    return { name, from, to, status: 'unchanged' };
+  });
+}
+
+const PLAN_LABEL = {
+  new: 'new',
+  update: 'update',
+  downgrade: 'DOWNGRADE',
+  modified: 'local edits will be lost',
+  unchanged: 'unchanged',
+};
+
+function renderPlan(plan) {
+  const shown = plan.filter((p) => p.status !== 'unchanged');
+  const width = Math.max(0, ...shown.map((p) => p.name.length));
+  for (const p of shown) {
+    const ver =
+      p.status === 'new'
+        ? `        -> v${p.to}`
+        : p.from === p.to
+          ? `   v${p.from}`
+          : `   v${p.from} -> v${p.to}`;
+    console.log(`  ${p.name.padEnd(width)}${ver}   ${PLAN_LABEL[p.status]}`);
+  }
+  const same = plan.length - shown.length;
+  if (same) console.log(`  (${same} unchanged)`);
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      rl.close();
+      resolve(value);
+    };
+    // Ctrl-D or a closed stdin resolves as "no" — without this the promise never settles
+    // and the installer exits silently having done nothing.
+    rl.on('close', () => finish(false));
+    rl.question(question, (answer) => finish(/^y(es)?$/i.test(answer.trim())));
+  });
+}
+
 function readUpstreamManifest() {
   try {
     const m = JSON.parse(fs.readFileSync(UPSTREAM_MANIFEST, 'utf8'));
@@ -199,15 +416,35 @@ Arguments:
 
 Options:
   -l, --list        List available skills (Linchpin + pinned base layer) and exit
+      --check       Audit every scope this agent reads for duplicate skills; install nothing
   -g, --global      Install to the user-global skills dir instead of the project
       --agent <id>  Target agent: claude-code (default) | github-copilot | codex | cursor
                     | all  (installs into every agent's directory)
       --skip-upstream  Install only Linchpin skills; don't vendor the upstream base layer
+  -f, --force       Reinstall everything, and install even if these skills already exist
+                    at another scope
+  -y, --yes         Skip the confirmation prompt (implied when not a TTY)
+  -n, --dry-run     Show what would change and exit without writing anything
   -h, --help        Show this help
 
+Updating:
+  Re-running is the update path. The installer compares each skill's version against what
+  is installed, prints what would change, and asks before touching anything. A run with
+  nothing to change exits early. --dry-run shows the diff and writes nothing; note that a
+  non-interactive run (piped stdin, CI) proceeds without prompting.
+
+Scopes:
+  Agents load every skills directory they find and do not dedupe by name, so a skill
+  installed both globally and in a project is listed twice and costs its description
+  twice in every session. Installing over another scope aborts unless you pass --force.
+  Use --check to see what is already installed where.
+
 Examples:
   npx @linchpinagency/skills                    # Linchpin skills + base layer -> ./.claude/skills
   npx @linchpinagency/skills wp-studio-cli      # one Linchpin skill (+ base layer)
+  npx @linchpinagency/skills --check            # audit scopes, install nothing
+  npx @linchpinagency/skills --dry-run          # preview an update, write nothing
+  npx @linchpinagency/skills --yes              # update without the confirmation prompt
   npx @linchpinagency/skills --skip-upstream    # Linchpin skills only
   npx @linchpinagency/skills --agent github-copilot
   npx @linchpinagency/skills --agent all        # every agent dir in this project
@@ -263,16 +500,150 @@ async function main() {
   }
   if (!wanted.length && !sources.length) return console.log('No skills to install.');
 
+  const labels = agentIds.map((id) => AGENTS[id].label).join(', ');
+
+  if (opts.check) {
+    // An audit reports what is actually installed, not just what this package ships —
+    // duplicates seeded by an older version or another library still cost context.
+    const installedHere = new Set(targets.flatMap((t) => installedSkillsIn(t.dir)));
+    const audit = findCollisions(agentIds, opts, [...installedHere], bases);
+    console.log(`Skill directories ${labels} reads, for this project:\n`);
+    for (const t of targets) {
+      const have = installedSkillsIn(t.dir);
+      console.log(`  [target]  ${t.dir}`);
+      console.log(`            ${have.length} skill(s) — ${stampLine(readStamp(t.dir))}\n`);
+    }
+    for (const c of audit) {
+      console.log(`  [${c.scope}] ${c.dir}`);
+      console.log(`            ${c.present.length} skill(s) — ${stampLine(c.stamp)}`);
+      console.log(`            ${SCOPE_HINT[c.scope]}`);
+      if (c.overlap.length) console.log(`            ${c.overlap.length} duplicate(s): ${c.overlap.join(', ')}`);
+      console.log();
+    }
+    const dupes = audit.reduce((n, c) => n + c.overlap.length, 0);
+    if (!dupes) {
+      console.log('No duplicate skills across scopes.');
+      return;
+    }
+    console.log(`${dupes} duplicate skill copies across scopes. Each one's description is loaded`);
+    console.log('once per copy, every session. Remove whichever copy you do not want.');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Plan first: whether a collision is a problem depends on whether this run would be
+  // *creating* the second copy or merely maintaining one that already exists.
+  const version = packageVersion();
+  const plans = targets.map((t) => ({ target: t, plan: planFor(t.dir, wanted) }));
+  const changed = plans.flatMap((p) => p.plan).filter((p) => p.status !== 'unchanged');
+
+  // A skill that is 'new' in every target but already present at another scope is a
+  // duplicate about to be born — that we refuse. A skill already installed here is an
+  // update; refusing it would only strand someone on a stale copy without removing the
+  // duplication, so it warns instead.
+  const arriving = new Set(
+    plans.flatMap(({ plan }) => plan.filter((p) => p.status === 'new').map((p) => p.name))
+  );
+  const existing = new Set(
+    plans.flatMap(({ plan }) => plan.filter((p) => p.status !== 'new').map((p) => p.name))
+  );
+  const collisions = findCollisions(agentIds, opts, wanted, bases);
+  const wouldCreate = collisions
+    .map((c) => ({ ...c, overlap: c.overlap.filter((n) => arriving.has(n) && !existing.has(n)) }))
+    .filter((c) => c.overlap.length);
+  const preExisting = collisions
+    .map((c) => ({ ...c, overlap: c.overlap.filter((n) => existing.has(n)) }))
+    .filter((c) => c.overlap.length);
+
+  if (wouldCreate.length && !opts.force) {
+    const dupes = wouldCreate.reduce((n, c) => n + c.overlap.length, 0);
+    console.error(`Refusing to install: ${dupes} of these skills are already installed at another scope.\n`);
+    for (const c of wouldCreate) {
+      console.error(`  ${c.dir}`);
+      console.error(`    ${SCOPE_HINT[c.scope]}`);
+      console.error(`    ${stampLine(c.stamp)}`);
+      console.error(`    would duplicate: ${c.overlap.join(', ')}\n`);
+    }
+    console.error(`${labels} loads every directory it finds and does not dedupe by name, so each`);
+    console.error('duplicate is listed twice and costs its description twice in every session.\n');
+    console.error('Pick one scope:');
+    console.error('  - keep the existing copy — nothing to do here; this install would be redundant');
+    console.error('  - move them here         — drop just the duplicates at the other scope, then re-run:');
+    for (const c of wouldCreate) {
+      console.error(`      (cd ${c.dir} && rm -rf ${c.overlap.join(' ')})`);
+    }
+    console.error('  - keep both anyway       — re-run with --force');
+    console.error('\nRun with --check to audit every scope without installing.');
+    process.exit(1);
+  }
+
+  if (preExisting.length) {
+    const dupes = preExisting.reduce((n, c) => n + c.overlap.length, 0);
+    console.log(`! ${dupes} of these skills are also installed at another scope, and were before this run:`);
+    for (const c of preExisting) console.log(`    ${c.dir}  (${c.scope})`);
+    console.log('  Updating here does not fix that. Run --check for the duplicates and how to drop them.\n');
+  }
+
+  // A re-run is the update path, so most runs land here with a handful of skills to
+  // update and the rest already current.
+  if (!changed.length && !opts.force) {
+    console.log(`Already up to date — ${wanted.length} skill(s) for ${labels}, nothing to change.`);
+    if (!opts.dryRun) console.log('Re-run with --force to reinstall anyway.');
+    return;
+  }
+
+  if (changed.length) {
+    console.log(`@linchpinagency/skills v${version} — ${labels}\n`);
+    for (const { target, plan } of plans) {
+      if (plans.length > 1) console.log(`${target.dir}`);
+      renderPlan(plan);
+      if (plans.length > 1) console.log();
+    }
+
+    const edited = changed.filter((p) => p.status === 'modified');
+    if (edited.length) {
+      console.log(`\n! ${edited.length} skill(s) were edited in place and will be overwritten.`);
+      console.log('  Skills are owned by this package — change them in the library, not the install.');
+    }
+    const down = changed.filter((p) => p.status === 'downgrade');
+    if (down.length) {
+      console.log(`\n! ${down.length} skill(s) would go BACKWARDS — this package is older than what is installed.`);
+      console.log('  Check the version you invoked before continuing.');
+    }
+
+    const counts = ['new', 'update', 'downgrade', 'modified']
+      .map((k) => [k, changed.filter((p) => p.status === k).length])
+      .filter(([, n]) => n)
+      .map(([k, n]) => `${n} ${k}`)
+      .join(', ');
+    console.log(`\n${changed.length} change(s): ${counts}`);
+
+    if (opts.dryRun) {
+      console.log('\nDry run — nothing was written.');
+      return;
+    }
+
+    if (!opts.yes && !opts.force) {
+      if (!process.stdin.isTTY) {
+        console.log('Non-interactive — proceeding. Pass --yes to silence this notice.');
+      } else if (!(await confirm('\nApply? [y/N] '))) {
+        console.log('Nothing changed.');
+        return;
+      }
+    }
+    console.log();
+  }
+
+  const applied = new Set(changed.map((p) => p.name));
   for (const base of bases) {
     fs.mkdirSync(base, { recursive: true });
     for (const name of wanted) {
       const dest = path.join(base, name);
       fs.rmSync(dest, { recursive: true, force: true });
       fs.cpSync(path.join(SKILLS_ROOT, name), dest, { recursive: true });
-      console.log(`✓ ${name} -> ${dest}`);
+      if (applied.has(name) || opts.force) console.log(`✓ ${name} -> ${dest}`);
     }
   }
-  const labels = agentIds.map((id) => AGENTS[id].label).join(', ');
   console.log(`\nInstalled ${wanted.length} Linchpin skill(s) for ${labels}.`);
 
   const upstream = [];
@@ -286,7 +657,6 @@ async function main() {
   }
 
   // Stamp last, so `upstream` reflects what actually landed rather than what was intended.
-  const version = packageVersion();
   const stamped = targets.filter((t) => writeStamp(t, { version, opts, skills: wanted, upstream }));
   if (stamped.length && agentIds.includes('claude-code')) {
     const rel = path.join(STAMP_DIR, CHECKER);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linchpinagency/skills",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
   "type": "module",
   "bin": {

package/skills/agent-capabilities/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: agent-capabilities
+description: Right-size what an agent loads on a project — audit skill installs for cross-scope duplicates, work out which MCP servers this repo actually needs, and scope them so every session stops paying for all of them. Use when context feels full before any work starts, when the same skill appears twice in the skills list, when deciding whether an MCP server belongs globally or in one repo, when onboarding a repo, or when someone asks which skills or servers a project should have. Not for writing a skill — use `write-a-linchpin-skill`.
+version: 1.0.0
+---
+
+# Agent capabilities
+
+Skills and MCP servers are loaded by the **harness, not the model**, and they are loaded
+*before* the first message. Every installed skill spends its `description` on every session;
+every connected MCP server spends its full tool schemas. Neither is free, and neither asks
+permission.
+
+That cost is invisible until you look for it, which is why it drifts. The failure mode is
+not one bad skill — it is thirty fine skills installed at two scopes and nine MCP servers
+where a repo needed two.
+
+**The rule this skill enforces:** a project loads what it uses, once.
+
+## When to use
+
+- Context feels consumed before you have typed anything.
+- A skill appears **twice** in the skills list — a real symptom with a real cause.
+- Deciding where a new MCP server belongs: this repo, or every repo.
+- Onboarding a repo, or handing one to someone else.
+- Someone asks "which skills/servers should this project have?"
+
+**Not this skill:** authoring or reviewing a skill's content —
+[`write-a-linchpin-skill`](../write-a-linchpin-skill/SKILL.md). Identifying the project's
+shape — [`project-context`](../project-context/SKILL.md), whose orientation pass this
+extends.
+
+## Owns
+
+Canonical for: **which** capabilities a project should load and **at what scope**, and the
+MCP-server-per-project decision.
+
+Deliberately **not** owned here:
+
+- *Detecting* duplicate skill installs — the installer owns that (`--check`, below). This
+  skill decides what to do about the answer.
+- What any individual skill or server *does* — that's its own skill.
+
+## Preflight
+
+Orient first ([`project-context`](../project-context/SKILL.md)) — the right capability set
+follows from the project's shape, not its name. Then read what is actually loaded:
+
+```bash
+npx @linchpinagency/skills --check   # every skills dir this agent reads, and any duplicates
+claude mcp list                      # configured servers and their scope
+```
+
+`--check` installs nothing and exits non-zero when duplicates exist, so it also works as a
+CI or hook check.
+
+## Procedure
+
+### 1. Audit the skill installs
+
+Agents load **every** skills directory they find and **do not dedupe by name**. The same
+skill at two scopes is listed twice and billed twice, every session.
+
+`--check` reports each directory, its scope, and the overlap. Three scopes collide in
+practice — user-global, project, and a stray install in a *parent* directory (running the
+installer from a checkouts folder instead of inside a repo). Details, per-agent directory
+map, and the remediation commands: [`references/skills-audit.md`](references/skills-audit.md).
+
+Resolve to **one scope per skill**. The installer now refuses a colliding install rather
+than silently creating the second copy.
+
+### 2. Decide the skill set for this project
+
+Global is the wrong default for anything stack-specific. A WordPress skill installed
+globally is loaded on every Workers repo you open, forever.
+
+| Install at | What belongs there |
+| --- | --- |
+| **User-global** | Only what is true on *every* repo you touch — `task-tracking`, `commit-and-release`, `project-context` |
+| **Project** | Everything stack-specific — the `wp-*` set on WordPress repos, and nowhere else |
+
+If a skill would never fire in this repo, it should not be installed in this repo.
+
+### 3. Decide the MCP servers for this project
+
+Server schemas cost substantially more than skill descriptions — this is usually the larger
+half of the problem. Derive the set from the work, not from what is already configured.
+
+The skill→server dependency map, the scope table, and the per-project-shape recipes live in
+[`references/mcp-scoping.md`](references/mcp-scoping.md). The short version:
+
+| Tier | Servers |
+| --- | --- |
+| Baseline, user scope | `clickup` — every unit of work routes through it |
+| Per project | The one or two the repo's actual work needs |
+| Never global | Anything stack-specific (`wordpress-studio`, `pressable`, `shopify-dev-mcp`, `shadcn`) |
+
+**Prefer project scope (`.mcp.json`, committed).** It travels with the repo, so the next
+person gets the right set without being told, and it disappears when they leave the repo.
+
+### 4. Make the decision stick
+
+A decision nobody re-reads decays. Record it in the project, three complementary ways:
+
+1. **`.mcp.json`, committed** — the servers this repo needs, as config rather than prose.
+2. **A line in the project's `CLAUDE.md`/`AGENTS.md`** naming the intended capability set,
+   so a human or agent adding a server knows there was an intent to violate.
+3. **A `SessionStart` hook** running `npx @linchpinagency/skills --check` when you want
+   duplicates to surface on their own rather than when someone notices.
+
+The hook snippet and the honest tradeoff (it costs a subprocess on every session to catch a
+rare, sticky misconfiguration) are in
+[`references/skills-audit.md`](references/skills-audit.md).
+
+## Guardrails
+
+- **Never `rm -rf` a whole skills directory to fix an overlap.** Those directories hold
+  skills from several sources — remove the specific duplicated skill directories. `--check`
+  prints the exact list.
+- **Never hand-edit skills inside a consuming project's `.claude/skills/`** — the installer
+  overwrites them. Change them in this library and re-install.
+- **Never add an MCP server at user scope to solve a one-repo problem.** That is how nine
+  servers happen. Use `-s project` or `-s local`.
+- **Never remove a server or skill someone else's workflow depends on without saying so** —
+  scope is a shared decision on a shared repo.
+- Removing a server can silently disable a skill that needs it (`task-tracking` without
+  `clickup`). Check the dependency map before pruning.
+- If you cannot tell whether a capability is used, leave it and say so. Under-loading is a
+  cheaper mistake than a broken workflow, but a *silent* prune is worse than either.
+
+## Done
+
+- [ ] `--check` reports no cross-scope duplicates, or the remaining ones are deliberate.
+- [ ] Every installed skill could plausibly fire in this repo.
+- [ ] Stack-specific skills are at project scope, not user scope.
+- [ ] The MCP server set was derived from the repo's work, not inherited.
+- [ ] Project-scoped servers are in a committed `.mcp.json`.
+- [ ] The intended set is recorded where the next person will see it.
+- [ ] Nothing was pruned that a skill still depends on.

package/skills/agent-capabilities/references/mcp-scoping.md

@@ -0,0 +1,96 @@
+# MCP scoping — which servers a project needs, and where to put them
+
+An MCP server's cost is its **tool schemas**, loaded before the first message. A handful of
+servers outweighs the entire skills library. Servers are also the easier mistake to make:
+adding one is a single command, and the default scope makes it apply beyond the repo you
+were in.
+
+## Scopes
+
+`claude mcp add` defaults to **`local`** — private to you, tied to the current project.
+That default is fine for experiments and wrong for anything a teammate also needs.
+
+| Scope | Stored in | Applies to | Shared? | Use for |
+| --- | --- | --- | --- | --- |
+| `local` (default) | `~/.claude.json`, under this project | This repo, you only | No | Trying a server out; personal credentials |
+| `project` | `.mcp.json` in the repo root | This repo, everyone | **Yes, via git** | The servers the repo's work actually needs |
+| `user` | `~/.claude.json`, top level | **Every** repo you open | No | Only genuinely universal servers |
+
+Precedence when a name appears more than once: `local` > `project` > `user`.
+
+```bash
+claude mcp list                                  # what is configured, and where
+claude mcp get <name>                            # one server's details
+claude mcp add <name> -s project -- <command>    # committed, shared with the repo
+claude mcp remove <name> -s user                 # prune from the global scope
+```
+
+`.mcp.json` servers are approval-gated on first encounter — a repo cannot silently run a
+server on someone's machine. Approvals are recorded per project in `~/.claude.json`
+(`enabledMcpjsonServers` / `disabledMcpjsonServers`).
+
+**Prefer `project`.** It travels with the repo, documents itself, and disappears when you
+leave the directory. `user` scope is where sprawl accumulates, because nothing about
+working in an unrelated repo ever reminds you it is there.
+
+## Which skills need which servers
+
+Removing a server can silently disable a skill. Check here before pruning.
+
+| Skill | Needs | Degrades to |
+| --- | --- | --- |
+| [`task-tracking`](../../task-tracking/SKILL.md) | `clickup` | Manual task lookup; `NO-TASK` scope |
+| [`wp-studio-cli`](../../wp-studio-cli/SKILL.md) | `wordpress-studio` | The `studio` CLI |
+| [`browser-automation`](../../browser-automation/SKILL.md) | `chrome-devtools` | Playwright headless |
+| [`wp-pressable`](../../wp-pressable/SKILL.md) | `pressable`, `1password` | SSH + WP-CLI, manual credentials |
+| [`design-previews`](../../design-previews/SKILL.md) | `chrome-devtools` | Playwright headless |
+| [`wp-audit`](../../wp-audit/SKILL.md) | `chrome-devtools` | Lighthouse CLI |
+| [`web-qa`](../../web-qa/SKILL.md) | via `browser-automation` | as above |
+
+Every one of these has a fallback, which is the point: a missing server is a slower path,
+not a broken one. That makes pruning safer than it feels — but say what you pruned.
+
+## Deciding the set
+
+Derive from the work, not from what is already configured. Ask what this repo's tasks
+actually touch.
+
+| Server | Include when |
+| --- | --- |
+| `clickup` | Always — every unit of work routes through it (house rule) |
+| `chrome-devtools` | The repo has a UI someone looks at |
+| `wordpress-studio` | WordPress site repo with a registered Studio site |
+| `pressable` + `1password` | Pressable-hosted, and you operate the server |
+| `figma` | There is a Figma file in play for this project |
+| `playwright` | Scripted or CI browser runs — not needed alongside `chrome-devtools` for ad-hoc QA |
+| `shadcn` | React project using shadcn/ui — never on a WordPress repo |
+| `shopify-dev-mcp` | Shopify project |
+
+Then read it back against the repo's shape ([`project-context`](../../project-context/SKILL.md)):
+
+- **WordPress site repo, Pressable-hosted** — `clickup` (user) + `wordpress-studio`,
+  `pressable`, `chrome-devtools` (project). `1password` local, since credentials are personal.
+- **WordPress plugin/product repo** — `clickup` + `wordpress-studio`. No `pressable`; the
+  repo does not own a server.
+- **Cloudflare Workers service** — `clickup`, and `chrome-devtools` only if it serves a UI.
+  No WordPress servers at all.
+- **Design-phase project** — `clickup`, `figma`, `chrome-devtools`. Add the WordPress set
+  when build starts, not before.
+
+A server that is not on the list for this repo's shape is one you are paying for in every
+session and using in none.
+
+## Migrating a sprawling global set
+
+Servers accumulate at `user` scope because that is where they got added first. Moving them
+is mechanical:
+
+1. `claude mcp list` — write down what is at `user` scope.
+2. For each, name the repos that actually use it. If it is more than "all of them", it does
+   not belong at `user`.
+3. `claude mcp remove <name> -s user`, then `claude mcp add <name> -s project -- …` in each
+   repo that needs it.
+4. Commit each repo's `.mcp.json` so the next person inherits the decision.
+
+Do this per server, verifying as you go — not as one sweep. A server you remove and forget
+to re-add somewhere shows up as a skill mysteriously taking the slow path weeks later.

package/skills/agent-capabilities/references/skills-audit.md

@@ -0,0 +1,116 @@
+# Skills audit — scopes, duplicates, and the session hook
+
+Detection is owned by the installer (`npx @linchpinagency/skills --check`). This file
+explains what it reports and what to do about it.
+
+## Why duplicates happen
+
+Agents load **every** skills directory they can see and **do not dedupe by name**. Two
+copies of `task-tracking` means two entries in the skills list and two copies of its
+description in the context window, every session, forever.
+
+Nothing warns you. The installer is happy to write into any directory you point it at, and
+until v0.2 neither install knew the other existed.
+
+## The three colliding scopes
+
+| Scope | Path | How it happens |
+| --- | --- | --- |
+| **User-global** | `~/.claude/skills` | `--global` — loaded in *every* project |
+| **Project** | `<repo>/.claude/skills` | The default — loaded in that repo |
+| **Ancestor** | `<parent-of-repo>/.claude/skills` | Running the installer from a checkouts folder (`~/GitHub`) instead of inside a repo |
+
+The ancestor case is the sneaky one: it looks like a project install, sits above every
+sibling checkout, and is easy to create by pressing enter in the wrong terminal.
+
+## Per-agent directories
+
+Each agent reads its own directories, which is why the installer fans out. Only the
+directories for the agent you are *running* cost that agent context — a `.codex/skills` copy
+is invisible to Claude Code, and vice versa.
+
+| Agent | Project | Global |
+| --- | --- | --- |
+| Claude Code | `.claude/skills` | `~/.claude/skills` |
+| GitHub Copilot | `.agents/skills`, `.github/skills` | `~/.copilot/skills` |
+| Codex | `.codex/skills` | `~/.codex/skills` |
+| Cursor | `.cursor/skills` | `~/.cursor/skills` |
+
+So a repo carrying all four agents' copies is not wasting Claude's context — it is just
+using disk. Don't "clean up" another agent's directory to save context that was never spent.
+
+## Auditing
+
+```bash
+npx @linchpinagency/skills --check                    # Claude Code, this project
+npx @linchpinagency/skills --check --agent codex      # a different agent
+npx @linchpinagency/skills --check --global           # from the global scope's point of view
+```
+
+Reports every directory the agent reads, its skill count, its install stamp, and the exact
+overlapping skill names. Exits `1` when duplicates exist, so it composes into CI or a hook.
+
+## Fixing an overlap
+
+Decide which scope should own each duplicated skill, then remove the *other copy only*:
+
+```bash
+cd ~/.claude/skills && rm -rf task-tracking wp-studio-cli   # …the names --check printed
+```
+
+`--check` prints this command with the names filled in. **Never remove the whole
+directory** — it holds skills from several sources (upstream WordPress, Cloudflare, Figma),
+and the overlap is usually a subset.
+
+Then re-install into the scope you chose. The installer refuses a colliding install:
+
+```
+Refusing to install: 22 of these skills are already installed at another scope.
+```
+
+`--force` overrides it, for the rare case where you genuinely want both.
+
+## Choosing the scope
+
+| Install at | What belongs there |
+| --- | --- |
+| User-global | Only skills true on *every* repo — `task-tracking`, `commit-and-release`, `project-context` |
+| Project | Everything stack-specific — the `wp-*` set on WordPress repos, and nowhere else |
+
+Global feels convenient and is how the sprawl starts: a WordPress skill installed globally
+is loaded on every Workers repo you open. Project scope also means the skill set travels
+with the repo, so a teammate cloning it gets the right tools without being told.
+
+## SessionStart hook
+
+Surfaces duplicates on their own rather than when someone happens to notice. In
+`.claude/settings.json` (project) or `~/.claude/settings.json` (all projects):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y @linchpinagency/skills --check | tail -3"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**The honest tradeoff:** this spends a subprocess on every session to catch a rare,
+one-time misconfiguration. It earns its place on a machine where installs drift — several
+repos, several agents, more than one person running the installer. On a stable single-repo
+setup, run `--check` by hand when onboarding and skip the hook.
+
+`npx` resolves from cache after the first run. If session startup latency matters more than
+freshness, install once (`npm i -g @linchpinagency/skills`) and call `skills --check`.
+
+Hook mechanics and the destructive-command guard are owned by
+[`safety-hooks`](../../safety-hooks/SKILL.md) — this is one more `SessionStart` entry
+alongside it, not a competing configuration.

package/skills/commit-and-release/SKILL.md

@@ -39,6 +39,8 @@ write and what release-please generates. Defers task resolution **and branch nam
 | --- | --- |
 | `commitlint.config.js` → `type-enum` | The types **this** repo accepts — they are not the same everywhere |
 | `commitlint.config.js` → `parserOpts.headerPattern` | The exact header regex, including which scopes count (`NO-TASK`, sometimes `NO-JIRA`, `#123`) |
+| `commitlint.config.js` → `extends` | What is inherited but never written down locally. `@commitlint/config-conventional` is where `header-max-length` comes from — see below |
+| `.github/workflows/` → the commit-message job | Whether CI **also** lints the PR title, which the husky hook never sees |
 | `release-please-config.json` → `changelog-sections` | Which types appear in the changelog, and which are hidden |
 | `release-please-config.json` → `extra-files` | **Every file whose version string is machine-owned** — never hand-edit these |
 | `.release-please-manifest.json` | The current version (also machine-owned) |
@@ -67,10 +69,27 @@ fix(LINCHPIN-4980): Correct masthead gutter on columns children
 improve(NO-TASK): Tidy editorconfig and ignore rules
 ```
 
+**Length: 100 characters, and it is an error.** `header-max-length` is not in Linchpin's
+shared config — it arrives through `extends: ['@commitlint/config-conventional']`, at
+severity `error`, counting the whole header including `type(SCOPE): `. A task key plus a
+colon and a space is ~22 of the budget, so the subject has about 78. Count it before you
+push; a title that reads well in a PR form is easily 110.
+
 **Punctuation gotcha:** the header pattern accepts only letters, digits, spaces, commas and
-hyphens in the subject. Periods, colons, parentheses and slashes cut the parsed subject
-short — so `Update wp-scripts to v27.1` parses as `Update wp-scripts to v27`. Keep version
-numbers and punctuation out of subjects, or put them in the body.
+hyphens in the subject — `[\w\d\s,\-]`. Everything else cuts the parsed subject short at
+the first offender, silently, because what is left still matches. Periods, colons,
+parentheses and slashes are the obvious ones: `Update wp-scripts to v27.1` parses as
+`Update wp-scripts to v27`.
+
+The two that catch people writing a prose-y PR title are less obvious, because both are
+what a careful writer reaches for:
+
+- **The apostrophe.** `\w` is `[A-Za-z0-9_]`, so `WooCommerce's account menu` parses as
+  `WooCommerce`. Write `the WooCommerce account menu`.
+- **The em dash.** Not in the set either, so a title with a `—` clause keeps only the half
+  before it. Use a comma, or split the thought into the body.
+
+Keep version numbers, possessives, dashes and punctuation out of subjects entirely.
 
 **Breaking changes:** `feat(KEY)!: …` or a `BREAKING CHANGE: …` footer. This drives a major
 version bump, so use it deliberately.
@@ -90,6 +109,38 @@ use `main` as a scope for normal work.
 5. **Push the branch and open the PR.** Title follows the same convention (squash merges use
    the PR title as the commit message, so a malformed title breaks the changelog); body
    links the ClickUp task. → PR open against the base branch, never a push to `main`.
+
+   **The PR title is linted separately, and the husky hook never saw it.** The shared
+   workflow pipes `gh pr view --json title -q .title` through commitlint as its own step, so
+   every commit can pass locally and the PR still go red — the usual cause is the 100-char
+   limit, since a PR title is written in a web form with no counter. Check it before you
+   wait on CI:
+
+   Run these from inside the repo whose rules you are checking — commitlint resolves the
+   config from the working directory, and from anywhere else it reports
+   "Please add rules to your `commitlint.config.js`" rather than an answer about your title:
+
+   ```bash
+   # Before opening: is the title you are about to use legal?
+   title="feat(PROJ-123): Subject in sentence case"
+   printf '%s' "$title" | npx commitlint --verbose
+
+   # Already open: lint the live title, and see its length.
+   gh pr view <number> --json title -q .title | tee >(awk '{print length" chars"}' >&2) \
+     | npx commitlint --verbose
+   ```
+
+   Fixing it takes two steps, because the shared workflow runs on
+   `pull_request: types: [opened, synchronize, reopened]` — `edited` is not in that list, so
+   correcting the title does **not** re-run anything and the PR sits on a stale red check:
+
+   ```bash
+   gh pr edit <number> --title 'feat(PROJ-123): A legal subject'
+   gh run rerun <run-id> --job <job-id>   # both are in `gh pr checks <number>`
+   ```
+
+   `gh run rerun` is refused while the run is still in progress, so wait for it to finish
+   before retrying.
 6. **Let release-please do the release.** Merging to `main` opens or updates a release PR
    that bumps versions and writes `CHANGELOG.md`; merging *that* tags the release, which is
    what deploy workflows trigger from. → Confirm the release PR reflects your change under
@@ -131,6 +182,9 @@ release note — pick the type that reflects what actually changed.
 - [ ] Type is in **this** repo's `type-enum`; subject is sentence case with no trailing
       period or mid-subject punctuation.
 - [ ] Commit passed the husky/commitlint hook without `--no-verify`.
-- [ ] PR title follows the same convention and the body links the ClickUp task.
+- [ ] Header is under 100 characters, and carries no apostrophe, em dash or other
+      punctuation outside `[\w\d\s,\-]`.
+- [ ] PR title follows the same convention, was linted in its own right (not just the
+      commits), and the body links the ClickUp task.
 - [ ] No version string, `CHANGELOG.md`, manifest, or tag was written by hand.
 - [ ] The resulting release PR shows the change under the expected section.

package/skills/project-context/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: project-context
 description: Orient before acting on a Linchpin project — identify the repo and branch, the local environment (Studio, wp-env, LocalWP), the host (Pressable or Cloudflare), the ClickUp space, and the release model, from .linchpin.json, composer.json, package.json, and the git remote. Use when starting work on an unfamiliar repo, before running commands that assume an environment, when a skill's Preflight needs the project's shape, or when something behaves differently than expected. Not for running the checks themselves.
-version: 1.0.0
+version: 1.1.0
 ---
 
 # Project context
@@ -55,6 +55,21 @@ Then read what exists:
 | `commitlint.config.js` | This repo's allowed commit types — they differ between repos |
 | Deploy workflows referencing Pressable | Hosted on Pressable ([`wp-pressable`](../wp-pressable/SKILL.md)) |
 | Git remote name | Infers the ClickUp space ([`task-tracking`](../task-tracking/SKILL.md)) |
+| `.mcp.json` | The MCP servers this repo declares it needs ([`agent-capabilities`](../agent-capabilities/SKILL.md)) |
+
+## Capability surface
+
+Part of "what am I working in?" is what the agent itself loaded. If the project's shape and
+its capabilities disagree — WordPress skills on a Workers repo, no `.mcp.json` on a repo
+whose work needs one, the same skill listed twice — say so once and move on;
+[`agent-capabilities`](../agent-capabilities/SKILL.md) owns the fix.
+
+Worth a look on an unfamiliar repo, not every session:
+
+```bash
+npx @linchpinagency/skills --check   # duplicate skill installs across scopes
+claude mcp list                      # configured servers and their scope
+```
 
 ## What to report
 

package/skills/quality-gates/SKILL.md

@@ -11,7 +11,10 @@ scripts, `package.json` scripts, `phpcs.xml.dist`, `lint-staged.config.js`. Your
 **find those declarations and run them**, not to invent commands. Getting this right is
 what makes the difference between a clean PR and a red CI run.
 
-The gates are the same ones CI runs, so passing here means passing there.
+The gates are the same ones CI runs, so passing here almost always means passing there.
+Almost: see [Green locally, red in CI](#green-locally-red-in-ci) for the one way the
+shared lint workflow disagrees with a clean local run, which is not a difference in what
+is checked but in what counts as a failure.
 
 ## When to use
 
@@ -69,6 +72,55 @@ Full command matrix: [`references/toolchain.md`](references/toolchain.md).
    repo lacks a house script, propose it (see `references/toolchain.md`) and add it **only
    with approval**. → Then go to [`commit-and-release`](../commit-and-release/SKILL.md).
 
+## Green locally, red in CI
+
+The shared lint workflow (`linchpin/actions`) runs the same phpcs you do, and then does
+two things to the result that your terminal does not.
+
+**It sniffs only the files the PR changed.** `git diff --diff-filter=ACMRT <base>...HEAD`,
+which means **you inherit the debt of every file you touch**. A file carrying violations
+nobody has cleaned up becomes your problem the moment you edit one line of it.
+
+**It pipes the report through `cs2pr`, and `cs2pr` fails on warnings.** This is the part
+that surprises people:
+
+```bash
+phpcs -q --runtime-set ignore_warnings_on_exit 1 --report=checkstyle "${files[@]}" | cs2pr
+```
+
+`ignore_warnings_on_exit` does exactly what it says — **phpcs itself exits 0** on a
+warnings-only run. But the checkstyle report still lists every warning as
+`<error severity="warning">`, `cs2pr` turns each into an annotation and exits non-zero
+when there is one, and the step runs under `set -e` with the pipeline's exit code being
+the last command's. So `composer lint` is green, `phpcs` on its own is green, and the job
+is red.
+
+Put together: **one unfixed warning in a file makes every future PR that touches it red on
+arrival.** Seen twice on linchpin.com — `PSR1.Files.SideEffects` on the standard
+`defined( 'ABSPATH' ) || exit;` guard (which cost a PR merged red), and
+`WordPress.WP.Capabilities.Unknown` on two custom capabilities.
+
+Check the same thing CI checks — the count of annotations, warnings included, over the
+files the PR changed:
+
+```bash
+git diff --name-only --diff-filter=ACMRT "$(git merge-base HEAD origin/main)"...HEAD -- '*.php' \
+  | tr '\n' '\0' | xargs -0 vendor/bin/phpcs -q --report=checkstyle \
+  | grep -c 'severity='
+```
+
+Zero means the job will pass. Any other number is what CI will annotate, whether phpcs
+called them errors or not. (Piped through `xargs -0` rather than an unquoted `$files`
+because zsh does not word-split, so the obvious version passes phpcs one long filename
+and reports a file that does not exist.)
+
+Fixing it is the same rule as everywhere else in this skill — **fix the warning, do not
+silence the sniff.** Most are legitimately configuration rather than code: a custom
+capability belongs in `custom_capabilities` in `phpcs.xml.dist`, a text domain in
+`text_domain`. Register the real value and say in a comment where it comes from; a typo
+registered there hides exactly the bug the sniff exists to catch. Setting the sniff to
+`<severity>0</severity>` is the last resort, not the first.
+
 ## Guardrails
 
 - **Never** commit with `--no-verify`. The hook is the gate; if it blocks you, fix the code.
@@ -90,5 +142,6 @@ Full command matrix: [`references/toolchain.md`](references/toolchain.md).
 - [ ] PHP gate passed (or is correctly not applicable — no `phpcs.xml.dist`, no PHP changed).
 - [ ] JS/CSS gate passed in the owning workspace (or correctly not applicable).
 - [ ] Tests run for touched, covered code.
+- [ ] The changed-file annotation count is zero — warnings included, not just errors.
 - [ ] No suppressions, config widenings, or `--no-verify` were used to get green.
 - [ ] Skipped gates and missing house scripts are named in the report.