@pareto4/pp-core 1.11.1 → 1.12.0

package/scripts/lint-org-coordinates.allowlist.json

@@ -0,0 +1,35 @@
+{
+  "_doc": "Placeholder Azure DevOps orgs and org-profile package names exempted from the org-coordinate guard (scripts/lint-org-coordinates.cjs), each with a reason (D-09). `exempt_paths` holds the guard's single exemption and must contain exactly one entry (D-11). Pareto's own identities are listed individually, never by scope wildcard (D-07). Nothing in this file may name a real client or partner, and the CI name scan (TEN-09) enforces that independently.",
+  "exempt_paths": [".planning/milestones/"],
+  "orgs": [
+    { "value": "contoso", "reason": "Phase 37 canonical placeholder org; covers its Platform project, the Platform-Vault and shared-vault repos, the other-project fixture, and the HTTPS and SSH forms" },
+    { "value": "contoso-org", "reason": "Phase 37 canonical second placeholder org" },
+    { "value": "o", "reason": "pre-existing minimal placeholder" },
+    { "value": "org", "reason": "pre-existing generic placeholder, including the org/project/_git/repo worked example in docs, schemas, src and CHANGELOG" },
+    { "value": "my-org", "reason": "pre-existing placeholder" },
+    { "value": "x", "reason": "pre-existing minimal placeholder" },
+    { "value": "REPLACE-org", "reason": "template placeholder in packages/org-contoso.TEMPLATE/org-profile.json" },
+    { "value": "shared", "reason": "test-fixture fallback coordinate, a generic word and not an organisation" },
+    { "value": "pareto4", "reason": "Pareto's own organisation (D-07)" }
+  ],
+  "packages": [
+    { "value": "@pareto4/org-contoso", "reason": "canonical placeholder package" },
+    { "value": "@pareto4/org-pareto", "reason": "Pareto's own org profile (D-07)" },
+    { "value": "@pareto4/org-example", "reason": "neutral worked example" },
+    { "value": "@your-scope/org-your-slug", "reason": "docs worked example" },
+    { "value": "@your-org/org-profile-package", "reason": "docs worked example" },
+    { "value": "@pp-test/org-fixture", "reason": "test fixture scope" },
+    { "value": "@fixture-scope/org-fixture", "reason": "test fixture scope" },
+    { "value": "@ppfixture/org-test", "reason": "test fixture scope" },
+    { "value": "@packages/org-pareto", "reason": "a path into Pareto's own packages/org-pareto directory written with a leading @ (PLAN transclusion or a quoted mention), not an npm scope (D-07)" }
+  ],
+  "seed_notes": [
+    { "value": "contoso-shared-vault", "reason": "repository name, covered by org contoso" },
+    { "value": "org-contoso.TEMPLATE", "reason": "directory name, no scope" },
+    { "value": "<org>/<project>", "reason": "angle brackets never match" },
+    { "value": "acme-vault", "reason": "GitLab path, outside D-08" },
+    { "value": "pareto4-clients/acme/acme-vault", "reason": "GitLab path, outside D-08" },
+    { "value": "vault.example.com", "reason": "hostname, not an Azure shape" },
+    { "value": "client-host.example.com", "reason": "hostname, not an Azure shape" }
+  ]
+}

package/scripts/lint-org-coordinates.cjs

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-org-coordinates.cjs — TEN-08 build-time organisation-coordinate guard.
+ *
+ * Design (D-07..D-11, .planning/phases/38-tenant-neutrality-planning-records-guards/38-CONTEXT.md):
+ *   D-08 "Real-looking organisation coordinate" = Azure DevOps shapes. The
+ *        organisation segment alone suffices after the Azure DevOps host —
+ *        under any subdomain (e.g. pkgs.dev.azure.com, feeds.dev.azure.com),
+ *        with any following path including `_`-prefixed service paths
+ *        (/_packaging, /_apis, a trailing slash, or nothing at all) — and in
+ *        the SSH form (ssh.dev.azure.com:v3/<org>). <org>.visualstudio.com
+ *        and <org>/<project>/_git/<repo> are also covered, as is the
+ *        @<scope>/org-<slug> org-profile package name shape. Host matching
+ *        is case-insensitive (dev.azure.com, Dev.Azure.com, VisualStudio.com
+ *        all match) and so is the `_git` segment. Every line is matched
+ *        through a normalised copy (WR-11, IN-13, IN-14). The normaliser
+ *        decodes exactly these spellings, case-insensitively, and nothing
+ *        else:
+ *          - up to three rounds of `%25` to `%` (never a loop until stable);
+ *          - `%2F` to `/` and `%3A` to `:`;
+ *          - the JSON escape (a backslash followed by `u002F`) and the hex
+ *            escape (a backslash followed by `x2F`), each to `/`;
+ *          - the decimal entity `&#47;` and the hex entity `&#x2F;`, each
+ *            with any number of leading zeros and with or without the
+ *            semicolon, except that a semicolon-less entity followed by
+ *            another digit of its base is left alone (a numeric reference
+ *            consumes every following digit, so it is a different character);
+ *          - the named entity `&sol;`;
+ *          - any run of backslashes directly before `/`, to `/`, in one
+ *            linear pass (IN-13).
+ *        On that copy azure_host accepts a
+ *        trailing-dot host, an explicit port and one or more slashes after
+ *        the host, and azure_ssh accepts a trailing-dot host and repeated
+ *        slashes. The allowlist comparison itself stays exact and
+ *        case-sensitive — a capitalised variant of an allowlisted org is still
+ *        a violation. A tracked line containing one of these shapes whose
+ *        org/package is not on the committed allowlist makes this guard exit
+ *        1. Columns refer to the raw line: the raw column of the match when
+ *        normalisation changed nothing before it, column 1 when it did.
+ *   D-09 The allowlist (scripts/lint-org-coordinates.allowlist.json) is a
+ *        committed JSON file of typed, exact-match placeholder values, each
+ *        with a reason — never a wildcard, never a client name.
+ *   D-07 Pareto's own identities are allowlisted individually; no
+ *        @pareto4/* scope wildcard, so a future real org-profile package
+ *        still requires an explicit, reviewed allowlist addition.
+ *   D-11 Scans tracked files only (`git ls-files`), with exactly one
+ *        explicitly-listed exemption path (.planning/milestones/) — a
+ *        near-miss prefix such as .planning/milestones-archive/ is still
+ *        scanned.
+ *
+ * Scope (IN-07): this guard scans only the tracked tree at HEAD. Git
+ * history, commit messages, branch and tag names, and MR titles are outside
+ * its reach — a name removed by a rewording or rename can still be present
+ * in history. If the repository is ever made public or mirrored, plan a
+ * separate history scan or rewrite.
+ *
+ * Residual (what the normalised copy above does not cover; deferred to
+ * .planning/todos/pending/neutrality-guard-review-deferred-findings.md): any
+ * spelling outside the decode list is not decoded — for example
+ * percent-encoded dots or `@`, numeric entities for characters other than `/`,
+ * more than four levels of percent-encoding, and look-alike Unicode — plus the
+ * deferred WR-07 and WR-08, and IN-12's quadratic worst case in the
+ * visualstudio and git_path patterns on long hyphen- or dot-separated lines.
+ * Lines are scanned in full by design: a line-length cap would let a
+ * coordinate at the end of a long line pass silently (fail open).
+ *
+ * A true positive is, by definition, a real organisation coordinate — so
+ * unlike scripts/verify-rename-guard.cjs's report line, this guard NEVER
+ * prints the matched text. It reports file:line:col and the shape only,
+ * keeping CI logs from spelling an organisation even when they catch one.
+ * Every example below uses `<org>`, never an alphanumeric org segment.
+ *
+ * Env overrides (test-only, mirrors ORG_COORD_GUARD_* in
+ * tests/lint-org-coordinates.test.cjs):
+ *   ORG_COORD_GUARD_REPO_ROOT       — redirect the whole-tree scan to a temp git repo
+ *   ORG_COORD_GUARD_ALLOWLIST_PATH  — redirect the allowlist file to a temp path
+ *
+ * Exit codes:
+ *   0 — no violation found
+ *   1 — one or more violations found, or the allowlist / git ls-files failed
+ *
+ * Usage:
+ *   node scripts/lint-org-coordinates.cjs
+ *
+ * Exports:
+ *   PATTERNS, normaliseForMatch(line), loadAllowlist(path), validateAllowlist(obj),
+ *   runScan({ repoRoot, allowlistPath } = {}), cliMain
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// SEG matches an Azure DevOps org/project/repo path segment.
+const SEG = '[A-Za-z0-9][A-Za-z0-9_.-]*';
+
+// HOST_TAIL follows an Azure DevOps host on the normalised line: an optional
+// trailing dot, an optional explicit port, and one or more slashes.
+const HOST_TAIL = '\\.?(?::\\d{1,5})?/+';
+
+/**
+ * normaliseForMatch(line) — the copy of a line every pattern runs against
+ * (WR-11). Bounded, never a loop-until-stable: at most three rounds of
+ * percent-25 decoding.
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+function normaliseForMatch(line) {
+  let s = line;
+  for (let round = 0; round < 3 && /%25/i.test(s); round++) {
+    s = s.replace(/%25/gi, '%');
+  }
+  s = s.replace(/%2F/gi, '/').replace(/%3A/gi, ':');
+  s = s.replace(new RegExp('\\\\' + 'u002F', 'gi'), '/');
+  s = s.replace(new RegExp('\\\\' + 'x2F', 'gi'), '/');
+  // A numeric reference consumes every following digit of its base, so a
+  // semicolon-less form must not be followed by another digit of that base.
+  s = s.replace(/&#0*47(?:;|(?![0-9]))|&#x0*2F(?:;|(?![0-9a-f]))|&sol;/gi, '/');
+  // IN-13: one linear pass — each maximal backslash run is matched once; a run
+  // followed by `/` collapses to `/`, any other run is kept as it is.
+  s = s.replace(/\\+(\/)?/g, (run, slash) => (slash ? '/' : run));
+  return s;
+}
+
+// D-08 pattern set. Object key order is part of this module's public
+// contract (tests assert Object.keys(PATTERNS) deep-equals this order).
+// azure_host / azure_ssh capture the organisation segment alone (CR-02): any
+// subdomain and any following path (including `_`-prefixed service paths)
+// matches, because the pattern is not anchored past the org segment. Both
+// carry the 'i' flag for case-insensitive host matching (WR-01); visualstudio
+// gains 'i' for the same reason. The allowlist comparison itself stays exact
+// and case-sensitive (see collectViolations below).
+const PATTERNS = {
+  azure_host: new RegExp('dev\\.azure\\.com' + HOST_TAIL + '(' + SEG + ')', 'gi'),
+  azure_ssh: new RegExp('ssh\\.dev\\.azure\\.com\\.?:v3/+(' + SEG + ')', 'gi'),
+  visualstudio: /\b([A-Za-z0-9][A-Za-z0-9-]*)\.visualstudio\.com\b/gi,
+  git_path: new RegExp('\\b(' + SEG + ')/(' + SEG + ')/_git/(' + SEG + ')', 'gi'),
+  org_pkg: /@([a-z0-9][a-z0-9-]*)\/org-([a-z0-9][a-z0-9._-]*)/g,
+};
+
+const VS_SUFFIX = '.visualstudio.com';
+
+// ORG_COORD_GUARD_REPO_ROOT lets tests redirect the guard to a temporary git
+// repo without touching the real working tree.
+const REPO_ROOT = process.env.ORG_COORD_GUARD_REPO_ROOT
+  ? path.resolve(process.env.ORG_COORD_GUARD_REPO_ROOT)
+  : path.resolve(__dirname, '..');
+
+// Default allowlist path lives next to this script.
+const DEFAULT_ALLOWLIST_PATH = path.join(__dirname, 'lint-org-coordinates.allowlist.json');
+const ALLOWLIST_PATH = process.env.ORG_COORD_GUARD_ALLOWLIST_PATH
+  ? path.resolve(process.env.ORG_COORD_GUARD_ALLOWLIST_PATH)
+  : DEFAULT_ALLOWLIST_PATH;
+
+/**
+ * isBinary(fullPath) — NUL-byte probe on the first 8 KiB.
+ *
+ * @param {string} fullPath  absolute path to probe
+ * @returns {boolean}
+ */
+function isBinary(fullPath) {
+  let fd;
+  try {
+    fd = fs.openSync(fullPath, 'r');
+    const buf = Buffer.allocUnsafe(8192);
+    const bytesRead = fs.readSync(fd, buf, 0, 8192, 0);
+    return buf.subarray(0, bytesRead).includes(0);
+  } catch {
+    return false;
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/**
+ * trimTrailing(str) — strips trailing `.`, `-`, `_` from a captured org or
+ * package slug before comparison, so a sentence-final period never causes a
+ * false violation.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function trimTrailing(str) {
+  return str.replace(/[._-]+$/, '');
+}
+
+/**
+ * loadAllowlist(allowlistPath) — read and JSON-parse the allowlist file. A
+ * read or parse failure is reported as an allowlist-invalid config error
+ * (exit 1), matching validateAllowlist()'s own failure shape.
+ *
+ * @param {string} allowlistPath
+ * @returns {object}
+ */
+function loadAllowlist(allowlistPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(allowlistPath, 'utf8');
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-org-coordinates: allowlist invalid — could not read allowlist file: ' + err.message);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-org-coordinates: allowlist invalid — invalid JSON: ' + err.message);
+  }
+}
+
+/**
+ * validateAllowlist(obj) — structural validation of a loaded allowlist.
+ *
+ * @param {object} obj
+ * @returns {{ ok: boolean, reason: string|null }}
+ */
+function validateAllowlist(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, reason: 'allowlist is not an object' };
+  }
+
+  if (!Array.isArray(obj.exempt_paths) || obj.exempt_paths.length !== 1) {
+    return { ok: false, reason: 'exempt_paths must be an array of exactly one string' };
+  }
+  const exemptPath = obj.exempt_paths[0];
+  if (typeof exemptPath !== 'string' || exemptPath === '' || !exemptPath.endsWith('/')) {
+    return { ok: false, reason: 'exempt_paths entry must be a non-empty string ending in "/"' };
+  }
+
+  for (const listName of ['orgs', 'packages', 'seed_notes']) {
+    const list = obj[listName];
+    if (!Array.isArray(list)) {
+      return { ok: false, reason: listName + ' must be an array' };
+    }
+    const seen = new Set();
+    for (const entry of list) {
+      if (
+        !entry ||
+        typeof entry !== 'object' ||
+        typeof entry.value !== 'string' ||
+        entry.value === '' ||
+        typeof entry.reason !== 'string' ||
+        entry.reason === ''
+      ) {
+        return { ok: false, reason: listName + ' has an entry missing a non-empty value or reason' };
+      }
+      if (entry.value.includes('*')) {
+        return { ok: false, reason: listName + ' entry "' + entry.value + '" contains a wildcard "*"' };
+      }
+      if (seen.has(entry.value)) {
+        return { ok: false, reason: listName + ' has a duplicate value "' + entry.value + '"' };
+      }
+      seen.add(entry.value);
+    }
+  }
+
+  const orgPkgShape = /^@[a-z0-9][a-z0-9-]*\/org-[a-z0-9][a-z0-9._-]*$/;
+  for (const entry of obj.packages) {
+    if (!orgPkgShape.test(entry.value)) {
+      return { ok: false, reason: 'packages entry "' + entry.value + '" does not match the org_pkg shape' };
+    }
+  }
+
+  return { ok: true, reason: null };
+}
+
+/**
+ * collectViolations(repoRoot, allowlist) — enumerate the whole tracked tree
+ * (minus the single exempt path prefix) and collect every PATTERNS hit whose
+ * resolved org/package is not on the allowlist.
+ *
+ * @param {string} repoRoot
+ * @param {object} allowlist  a validated allowlist object
+ * @returns {{ violations: Array<{file: string, line: number, col: number, shape: string}>, fileCount: number }}
+ */
+function collectViolations(repoRoot, allowlist) {
+  let trackedOutput;
+  try {
+    trackedOutput = execFileSync('git', ['ls-files', '-z'], { cwd: repoRoot, encoding: 'utf8' });
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-org-coordinates: git ls-files failed: ' + err.message);
+  }
+  const trackedFiles = trackedOutput.split('\u0000').filter(Boolean);
+
+  const exemptPaths = allowlist.exempt_paths;
+  const orgSet = new Set(allowlist.orgs.map((e) => e.value));
+  const packageSet = new Set(allowlist.packages.map((e) => e.value));
+
+  /** @type {Array<{file: string, line: number, col: number, shape: string}>} */
+  const violations = [];
+  const seen = new Set();
+
+  for (const relPath of trackedFiles) {
+    if (exemptPaths.some((ep) => relPath.startsWith(ep))) continue;
+
+    const fullPath = path.join(repoRoot, relPath);
+    if (isBinary(fullPath)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const rawLine = lines[i];
+      const matchLine = normaliseForMatch(rawLine);
+      for (const shape of Object.keys(PATTERNS)) {
+        const re = PATTERNS[shape];
+        re.lastIndex = 0;
+        let m = re.exec(matchLine);
+        while (m !== null) {
+          // Column refers to the raw line: exact when normalisation changed
+          // nothing before the match, otherwise column 1.
+          const col = matchLine.slice(0, m.index) === rawLine.slice(0, m.index) ? m.index + 1 : 1;
+          let allowed;
+
+          if (shape === 'org_pkg') {
+            const scope = m[1];
+            const slug = trimTrailing(m[2]);
+            const pkg = '@' + scope + '/org-' + slug;
+            allowed = packageSet.has(pkg);
+          } else {
+            let org = m[1];
+            if (shape === 'git_path' && org.toLowerCase().endsWith(VS_SUFFIX)) {
+              org = org.slice(0, -VS_SUFFIX.length);
+            }
+            org = trimTrailing(org);
+            allowed = orgSet.has(org);
+          }
+
+          if (!allowed) {
+            const key = relPath + ':' + (i + 1) + ':' + m.index + ':' + shape;
+            if (!seen.has(key)) {
+              seen.add(key);
+              violations.push({ file: relPath, line: i + 1, col, shape });
+            }
+          }
+
+          // Guard against a zero-length match causing an infinite loop.
+          if (m[0].length === 0) re.lastIndex += 1;
+          m = re.exec(matchLine);
+        }
+      }
+    }
+  }
+
+  return { violations, fileCount: trackedFiles.length };
+}
+
+/**
+ * runScan(opts?) — pure scan entry point (no process.exit, no stdout/stderr
+ * writes). Consumed by the CLI wrapper (cliMain) and directly by tests.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]       defaults to the module-level REPO_ROOT
+ * @param {string} [opts.allowlistPath]  defaults to the module-level ALLOWLIST_PATH
+ * @returns {{
+ *   violations: Array<{file: string, line: number, col: number, shape: string}>,
+ *   fileCount: number,
+ *   exemptPaths: string[],
+ *   repoRoot: string,
+ *   allowlistPath: string,
+ * }}
+ */
+function runScan(opts) {
+  const repoRoot = (opts && opts.repoRoot) || REPO_ROOT;
+  const allowlistPath = (opts && opts.allowlistPath) || ALLOWLIST_PATH;
+
+  const allowlist = loadAllowlist(allowlistPath);
+  const validation = validateAllowlist(allowlist);
+  if (!validation.ok) {
+    throw new ExitError(1, 'ERROR lint-org-coordinates: allowlist invalid — ' + validation.reason);
+  }
+
+  const { violations, fileCount } = collectViolations(repoRoot, allowlist);
+
+  return {
+    violations,
+    fileCount,
+    exemptPaths: allowlist.exempt_paths,
+    repoRoot,
+    allowlistPath,
+  };
+}
+
+// ── CLI entry ────────────────────────────────────────────────────────────────
+
+function cliMain() {
+  const { violations, fileCount, exemptPaths } = runScan();
+
+  if (violations.length === 0) {
+    process.stdout.write(
+      'ok lint-org-coordinates: ' + fileCount + ' tracked files scanned, 0 violations (single exemption: ' +
+        exemptPaths[0] + ')\n'
+    );
+    return 0;
+  }
+
+  process.stderr.write(
+    'FAIL lint-org-coordinates: ' + violations.length +
+      ' organisation coordinate(s) outside the placeholder allowlist\n'
+  );
+  for (const v of violations) {
+    process.stderr.write('  ' + v.file + ':' + v.line + ':' + v.col + ' — shape=' + v.shape + '\n');
+  }
+  process.stderr.write(
+    'use a placeholder from scripts/lint-org-coordinates.allowlist.json (e.g. org contoso, package ' +
+      '@pareto4/org-contoso) or add a placeholder entry with a reason\n'
+  );
+
+  throw new ExitError(1);
+}
+
+module.exports = { PATTERNS, normaliseForMatch, loadAllowlist, validateAllowlist, runScan, cliMain };
+
+if (require.main === module) {
+  runMain(cliMain);
+}

package/scripts/lint-skill-deps.cjs

@@ -5,7 +5,7 @@
  * Two checks:
  *
  * a) Frontmatter to body consistency:
- *    For each commands/gsd/*.md, parse requires: and walk the body for
+ *    For each commands/pp-*.md, parse requires: and walk the body for
  *    references to other GSD skills (pattern: /gsd:<stem> or gsd:<stem>).
  *    Fail if a skill body references a skill not listed in requires:.
  *
@@ -15,10 +15,14 @@
  *    the closure references a skill NOT in the closure, fail.
  *
  * Usage:
- *   node scripts/lint-skill-deps.cjs               # scans commands/gsd/
+ *   node scripts/lint-skill-deps.cjs               # scans commands/
  *   node scripts/lint-skill-deps.cjs --dir <path>  # scan a custom dir (testing)
  *
- * Exits 0 if all pass; exits 1 if any violation.
+ * Exits 0 if all pass; exits 1 if any violation, and exits 1 when the scanned
+ * directory is missing or holds no skills — a run that checked nothing must not
+ * report ok. (The default used to be a legacy nested commands subdirectory, which
+ * stopped existing at the D-12 flat-hyphen move; for that whole period lint:ci printed
+ * "0 skill(s) checked, 0 violations" and passed.)
  */
 
 'use strict';
@@ -34,7 +38,8 @@ const { PROFILES, loadSkillsManifest, resolveProfile } = require(PROFILES_MODULE
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-let commandsDir = path.join(__dirname, '..', 'commands', 'gsd');
+// D-12 flat-hyphen: commands ship flat as commands/pp-<stem>.md (no nested subdir).
+let commandsDir = path.join(__dirname, '..', 'commands');
 const args = process.argv.slice(2);
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--dir' && args[i + 1]) {
@@ -67,20 +72,36 @@ function extractBody(content) {
 // Check a: frontmatter to body consistency
 // ---------------------------------------------------------------------------
 
+// The manifest keys are bare stems ('pp-progress.md' -> 'progress'), so the
+// file has to be found again: shipped commands are pp-<stem>.md, while bare
+// <stem>.md is kept for fixtures. Rebuilding the path as <stem>.md alone
+// matched no shipped file, and every read fell into the catch below.
+function resolveSkillFile(stem) {
+  for (const name of ['pp-' + stem + '.md', stem + '.md']) {
+    const candidate = path.join(commandsDir, name);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
 function checkFrontmatterBodyConsistency(manifest, allStems) {
   const violations = [];
+  let filesRead = 0;
+  let refsFound = 0;
 
   for (const [stem, declared] of manifest) {
     if (stem.startsWith('_calls_agents_')) continue;
-    const filePath = path.join(commandsDir, stem + '.md');
+    const filePath = resolveSkillFile(stem);
     let content;
     try {
       content = fs.readFileSync(filePath, 'utf8');
     } catch {
       continue;
     }
+    filesRead++;
     const body = extractBody(content);
     const referenced = extractBodyReferences(body);
+    refsFound += [...referenced].filter((ref) => ref !== stem).length;
     const declaredSet = new Set(declared);
     for (const ref of referenced) {
       if (ref === stem) continue;
@@ -104,7 +125,7 @@ function checkFrontmatterBodyConsistency(manifest, allStems) {
     }
   }
 
-  return violations;
+  return { violations, filesRead, refsFound };
 }
 
 // ---------------------------------------------------------------------------
@@ -149,14 +170,32 @@ function main() {
     [...manifest.keys()].filter((k) => !k.startsWith('_calls_agents_'))
   );
 
-  const consistencyViolations = checkFrontmatterBodyConsistency(manifest, allStems);
+  if (allStems.size === 0) {
+    process.stderr.write(
+      '\nERROR lint-skill-deps: no skills found in ' + commandsDir + '\n' +
+      'A run that checks zero skills proves nothing. Point --dir at a directory\n' +
+      'holding pp-<stem>.md command files (the default is commands/).\n\n'
+    );
+    return 1;
+  }
+
+  const consistency = checkFrontmatterBodyConsistency(manifest, allStems);
+  const consistencyViolations = consistency.violations;
   const closureViolations = checkProfileClosure(manifest);
 
   const totalViolations = consistencyViolations.length + closureViolations.length;
 
   if (totalViolations === 0) {
-    const checked = manifest.size;
-    process.stdout.write('ok lint-skill-deps: ' + checked + ' skill(s) checked, 0 violations\n');
+    // Count skills, not manifest entries: the manifest also holds one
+    // _calls_agents_<stem> key per skill, which doubled the old figure.
+    // The cross-reference count is printed so a pass with 0 references reads as
+    // what it is: check (a) scans for the gsd:<stem> form, which shipped bodies
+    // no longer use (todo: lint-skill-deps-check-a-scans-a-token-no-command-uses).
+    process.stdout.write(
+      'ok lint-skill-deps: ' + allStems.size + ' skill(s) checked (' +
+      consistency.filesRead + ' body file(s) read, ' + consistency.refsFound +
+      ' cross-reference(s) found), 0 violations\n'
+    );
     return 0;
   }
 

package/scripts/lint-test-file-count.cjs

@@ -11,6 +11,12 @@
  *
  * Verdicts: OK_UNDER_LIMIT | OK_IN_ALLOWLIST | FAIL_EXCEEDS_LIMIT |
  *           FAIL_NOVEL_FILES | FAIL_STALE_ALLOWLIST
+ *
+ * BUILD BEFORE LINT. Attribution reads the COMPILED production modules under
+ * pp-core/bin/lib/, so `npm run build:lib` must precede this gate: on an
+ * unbuilt tree the module a test belongs to does not exist yet, and the test
+ * is attributed to whichever coarser prefix happens to match instead — the
+ * gate then reports novel files that are only novel because nothing compiled.
  */
 'use strict';
 
@@ -70,10 +76,19 @@ function prodPrefix(filename) {
   return filename.replace(/\.(cjs|ts|js)$/, '');
 }
 
-// Strip .test.{cjs,ts} and .integration.test.ts, then strip issue stamps.
+// Strip the convention suffixes, then the bare .test.{cjs,ts}, then issue
+// stamps. Five forms are stripped: `.integration`, `.slow`, `.security`,
+// `.install` and the bare `.test`.
+//
+// `.property` is DELIBERATELY NOT stripped. The `vault` entry in
+// scripts/lint-test-file-count.allowlist.json documents
+// vault-practices.property.test.cjs as parked in that bucket precisely because
+// this function leaves the suffix on — stripping it would re-cluster the file
+// into `vault-practices` and turn that entry's own explanation into a false
+// statement. Changing it is a deliberate allowlist migration, not a tidy-up.
 function testEffectivePrefix(testName) {
   const bare = testName
-    .replace(/\.integration\.test\.(ts|cjs)$/, '')
+    .replace(/\.(integration|slow|security|install)\.test\.(ts|cjs)$/, '')
     .replace(/\.test\.(ts|cjs)$/, '');
   const m = bare.match(/^(?:feat|bug|enh|fix)-\d+(?:-\d+)*-(.+)$/);
   return m ? m[1] : bare;