flecto 3.0.0 → 3.0.2

package/src/packs/github-actions.json

@@ -0,0 +1,92 @@
+{
+  "id": "github-actions",
+  "expandSubtrees": true,
+  "rules": [
+    {
+      "id": "github-actions-pull-request-target",
+      "severity": "error",
+      "when": ["added"],
+      "match": { "pathEquals": "on.pull_request_target" },
+      "message": "A pull_request_target trigger was added. Do not run fork-controlled code in a privileged workflow; separate metadata checks from untrusted execution."
+    },
+    {
+      "id": "github-actions-permissions-removed",
+      "severity": "error",
+      "when": ["removed"],
+      "match": { "pathEquals": "permissions" },
+      "message": "The workflow permissions block was removed. GitHub may restore a broader default token scope; keep an explicit least-privilege block."
+    },
+    {
+      "id": "github-actions-permissions-write-all",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "pathEquals": "permissions" },
+      "afterEquals": "write-all",
+      "message": "The workflow token was widened to write-all. Scope permissions to the specific resources and operations required by the job."
+    },
+    {
+      "id": "github-actions-permission-write-scope",
+      "severity": "warn",
+      "when": ["added", "changed"],
+      "match": { "path": "^permissions\\.[^.]+$" },
+      "afterEquals": "write",
+      "messageTemplate": "Workflow permission {path} was widened to write. Confirm the job and its trigger need write access."
+    },
+    {
+      "id": "github-actions-unpinned-action",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.steps\\[[0-9]+\\]\\.uses$" },
+      "afterMatches": "^.+@(?![0-9a-fA-F]{40}$).+$",
+      "messageTemplate": "Action {after} is not pinned to a full commit SHA at {path}. Pin third-party actions to an immutable SHA and keep the release in a comment."
+    },
+    {
+      "id": "github-actions-pull-request-head-checkout",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.steps\\[[0-9]+\\]\\.with\\.ref$" },
+      "afterMatches": "^(?:github\\.event\\.pull_request\\.head\\.sha|\\$\\{\\{\\s*github\\.event\\.pull_request\\.head\\.sha\\s*\\}\\})$",
+      "message": "The workflow checks out the pull request head SHA. Recheck the trust boundary before combining this with pull_request_target or write permissions."
+    },
+    {
+      "id": "github-actions-secrets-in-run",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.steps\\[[0-9]+\\]\\.run$" },
+      "afterMatches": "\\$\\{\\{\\s*secrets\\.[^}]+\\}\\}",
+      "message": "A GitHub secret is interpolated into a run step. Prefer an environment boundary and ensure untrusted pull-request code cannot reach the step."
+    },
+    {
+      "id": "github-actions-self-hosted-runner",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.runs-on(?:\\.labels)?(?:\\[[0-9]+\\])?$" },
+      "anyOf": [
+        { "afterMatches": "(^|[ ,])self-hosted([ ,]|$)" },
+        { "afterAnyMatches": "(^|[ ,])self-hosted([ ,]|$)" }
+      ],
+      "message": "A self-hosted runner is reachable from this workflow. Confirm that fork-controlled changes cannot execute on a runner with persistent credentials."
+    },
+    {
+      "id": "github-actions-schedule-exposed",
+      "severity": "warn",
+      "when": ["added"],
+      "match": { "pathEquals": "on.schedule" },
+      "message": "A scheduled trigger was added. Review which jobs and secrets become reachable without a pull request review."
+    },
+    {
+      "id": "github-actions-workflow-dispatch-exposed",
+      "severity": "warn",
+      "when": ["added"],
+      "match": { "pathEquals": "on.workflow_dispatch" },
+      "message": "A manual workflow trigger was added. Document who may run it and which permissions or secrets it can reach."
+    },
+    {
+      "id": "github-actions-workflow-call-exposed",
+      "severity": "warn",
+      "when": ["added"],
+      "match": { "pathEquals": "on.workflow_call" },
+      "message": "A reusable workflow trigger was added. Review its caller permissions and secret inheritance before treating it as a trusted boundary."
+    }
+  ]
+}

package/src/parser.js

@@ -5,8 +5,14 @@ import TOML from '@iarna/toml';
 import dotenv from 'dotenv';
 import { isArmoredAgeFile, normalizeEncrypted, opaqueFileState } from './encrypted.js';
 import { documentKeysOf, withDocumentKeys } from './documents.js';
+import { assertNotTerraformPlan } from './terraform.js';
 
-const SUPPORTED_EXT = ['.json', '.yaml', '.yml', '.toml', '.env', '.ini', '.age'];
+const SUPPORTED_EXT = ['.json', '.jsonc', '.yaml', '.yml', '.toml', '.env', '.ini', '.age'];
+
+// Upper bound on nodes produced when normalizing a parsed tree. Well above any
+// real config (a 5,000-key file is 5,000 nodes) and below where alias expansion
+// becomes a denial of service. See normalizeParsedValue.
+const MAX_NORMALIZED_NODES = 5_000_000;
 
 /**
  * True for dotenv-like names: `.env`, `.env.*`, `*.env`
@@ -25,24 +31,63 @@ export function isIniFilename(filepath) {
   return extname(filepath).toLowerCase() === '.ini';
 }
 
+/**
+ * Define an own data property, whatever the key is called.
+ *
+ * `target[key] = value` is not a property write when `key` is `"__proto__"`: it
+ * runs the `Object.prototype.__proto__` setter instead, which either reassigns
+ * the object's prototype or silently discards the value. `defineProperty` is the
+ * operation that was actually meant every time a parser writes a key it read out
+ * of a file, and it treats every key name the same.
+ * @param {Record<string, unknown>} target
+ * @param {string} key
+ * @param {unknown} value
+ */
+function defineOwn(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
+
 /**
  * Minimal INI parser: [section] + key=value.
  * Root keys are top-level; sectioned keys nest under the section name.
+ *
+ * Section and key names come out of the file, which in Flecto's threat model
+ * means they come out of a pull request. They are read and written as **own
+ * properties only**: `out[section]` on a section named `__proto__` resolves to
+ * `Object.prototype` — which passes `isPlainObject`, since its own prototype is
+ * `null` — and every key in that section would then be written onto the
+ * prototype of every object in the process. `Object.hasOwn` for the lookup and
+ * `defineOwn` for the write make a reserved name an ordinary key holding
+ * ordinary data, which is what a config file's `[__proto__]` section is.
  * @param {string} raw
  * @returns {Record<string, unknown>}
  */
 export function parseIni(raw) {
   /** @type {Record<string, unknown>} */
   const out = {};
-  let section = null;
+  /** @type {Record<string, unknown>} */
+  let bucket = out;
 
   for (const line of String(raw).split(/\r?\n/)) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith(';') || trimmed.startsWith('#')) continue;
     const sectionMatch = trimmed.match(/^\[([^\]]+)\]$/);
     if (sectionMatch) {
-      section = sectionMatch[1].trim();
-      if (!isPlainObject(out[section])) out[section] = {};
+      const section = sectionMatch[1].trim();
+      const existing = Object.hasOwn(out, section) ? out[section] : undefined;
+      if (isPlainObject(existing)) {
+        bucket = /** @type {Record<string, unknown>} */ (existing);
+      } else {
+        // A repeated section keeps accumulating; a section colliding with a
+        // root scalar replaces it, exactly as before.
+        bucket = {};
+        defineOwn(out, section, bucket);
+      }
       continue;
     }
     const eq = trimmed.indexOf('=');
@@ -55,17 +100,106 @@ export function parseIni(raw) {
     ) {
       value = value.slice(1, -1);
     }
-    if (section == null) {
-      out[key] = value;
-    } else {
-      /** @type {Record<string, string>} */
-      const bucket = /** @type {any} */ (out[section]);
-      bucket[key] = value;
-    }
+    defineOwn(bucket, key, value);
   }
   return out;
 }
 
+/**
+ * Parse JSON that may carry line and block comments and trailing commas —
+ * the JSONC dialect `tsconfig.json`, `.vscode/settings.json`, `jsconfig.json`,
+ * and `devcontainer.json` are written in by convention.
+ *
+ * Comments are blanked rather than removed: every stripped character is
+ * replaced by a space, and newlines inside a block comment are kept as
+ * newlines. That keeps byte offsets and line/column numbers identical to the
+ * original file, so the position `JSON.parse` reports on a real syntax error
+ * still points at the line the author has open. Deleting the spans instead
+ * would silently shift every error after the first comment.
+ *
+ * The scan tracks string state, because the naive strip is wrong on exactly
+ * the values config files are full of: `"https://example.com"` contains `//`,
+ * and a `/*` may sit inside a string just as legitimately. Backslash escapes
+ * are consumed as a pair so a `\"` never looks like the end of a string.
+ *
+ * Note that comments are not preserved on the parsed value. Flecto only ever
+ * reads config, so nothing is written back — but a snapshot records the parsed
+ * structure, not the file, and comments are not part of it.
+ * @param {string} raw
+ * @returns {unknown}
+ */
+export function parseJsonc(raw) {
+  return JSON.parse(stripJsonComments(raw));
+}
+
+/**
+ * Blank out JSONC comments and trailing commas, preserving every byte offset.
+ * Exported for tests; {@link parseJsonc} is the parsing entry point.
+ * @param {string} raw
+ * @returns {string}
+ */
+export function stripJsonComments(raw) {
+  const text = String(raw);
+  const out = text.split('');
+  const blank = (from, to) => {
+    for (let k = from; k < to; k += 1) {
+      // Keep line breaks so line numbers in parse errors stay true.
+      if (out[k] !== '\n' && out[k] !== '\r') out[k] = ' ';
+    }
+  };
+
+  // Index of a comma that has seen nothing but whitespace since, or -1. When a
+  // closing brace or bracket arrives it is a trailing comma and gets blanked.
+  let pendingComma = -1;
+  let i = 0;
+
+  while (i < text.length) {
+    const ch = text[i];
+
+    if (ch === '"') {
+      // A string is opaque: scan to its unescaped closing quote.
+      pendingComma = -1;
+      i += 1;
+      while (i < text.length) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === '"') { i += 1; break; }
+        i += 1;
+      }
+      continue;
+    }
+
+    if (ch === '/' && text[i + 1] === '/') {
+      let end = i + 2;
+      while (end < text.length && text[end] !== '\n' && text[end] !== '\r') end += 1;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+
+    if (ch === '/' && text[i + 1] === '*') {
+      const closed = text.indexOf('*/', i + 2);
+      // An unterminated block comment runs to end of input. Blanking it leaves
+      // JSON.parse to report the truncated document, which is the real error.
+      const end = closed === -1 ? text.length : closed + 2;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+
+    if (ch === ',') {
+      pendingComma = i;
+    } else if (ch === '}' || ch === ']') {
+      if (pendingComma !== -1) out[pendingComma] = ' ';
+      pendingComma = -1;
+    } else if (ch !== ' ' && ch !== '\t' && ch !== '\n' && ch !== '\r') {
+      pendingComma = -1;
+    }
+    i += 1;
+  }
+
+  return out.join('');
+}
+
 function isPlainObject(v) {
   if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
   const prototype = Object.getPrototypeOf(v);
@@ -98,18 +232,34 @@ export const CIRCULAR_SENTINEL = '<circular>';
  * rather than e.g. a back-reference path, so two files with the same cycle
  * shape normalize to the same tree and compare equal — the whole point of a
  * stable, readable diff path.
+ *
+ * A budget bounds the total nodes produced. YAML aliases resolve to shared
+ * object *references*, so a tiny file — `a: &a [x,…]`, `b: [*a,*a,…]`, repeated
+ * a handful of levels — parses to a small DAG that this function expands into an
+ * exponentially large *tree* (each alias reference is normalized independently,
+ * on purpose, so two files with the same shape compare equal). Without a bound,
+ * a few hundred bytes of nested aliases hang the process — a "billion laughs"
+ * denial of service reachable on any parsed file. The budget makes it fail with
+ * a clear error instead. The limit is far above any real config.
  * @param {unknown} value
  * @param {Set<object>} [ancestors] internal recursion state; omit when calling
+ * @param {{ n: number }} [budget] internal node counter; omit when calling
  * @returns {unknown}
  */
-function normalizeParsedValue(value, ancestors = new Set()) {
+function normalizeParsedValue(value, ancestors = new Set(), budget = { n: 0 }) {
+  if (++budget.n > MAX_NORMALIZED_NODES) {
+    throw new Error(
+      `document expands to too many nodes (limit ${MAX_NORMALIZED_NODES}); `
+      + 'this is usually YAML alias expansion (a "billion laughs" bomb)',
+    );
+  }
   if (typeof value === 'bigint') return String(value);
   if (typeof value === 'number' && !Number.isFinite(value)) return String(value);
   if (value instanceof Date) return value.toJSON();
   if (Array.isArray(value)) {
     if (ancestors.has(value)) return CIRCULAR_SENTINEL;
     ancestors.add(value);
-    const out = value.map((item) => normalizeParsedValue(item, ancestors));
+    const out = value.map((item) => normalizeParsedValue(item, ancestors, budget));
     ancestors.delete(value);
     return out;
   }
@@ -120,14 +270,14 @@ function normalizeParsedValue(value, ancestors = new Set()) {
   ) {
     const serialized = value.toJSON();
     if (serialized !== value && (serialized === null || typeof serialized !== 'object')) {
-      return normalizeParsedValue(serialized, ancestors);
+      return normalizeParsedValue(serialized, ancestors, budget);
     }
   }
   if (isPlainObject(value)) {
     if (ancestors.has(value)) return CIRCULAR_SENTINEL;
     ancestors.add(value);
     const out = Object.fromEntries(
-      Object.entries(value).map(([key, child]) => [key, normalizeParsedValue(child, ancestors)]),
+      Object.entries(value).map(([key, child]) => [key, normalizeParsedValue(child, ancestors, budget)]),
     );
     ancestors.delete(value);
     return out;
@@ -170,6 +320,25 @@ function documentIdentity(doc) {
   return scalarField(doc, 'id') ?? scalarField(doc, 'name');
 }
 
+/**
+ * True for a document that carries the Kubernetes resource markers `apiVersion`
+ * and `kind`. This is the signal used to decide whether a *single*-document file
+ * should be keyed by identity like a multi-document one (#124): a manifest that
+ * gains a second document beside it must keep the paths it had, and the only way
+ * to do that is to key it the same way whether it stands alone or not.
+ *
+ * Ordinary config that happens to have a `kind` but no `apiVersion` — a form
+ * field, say — is not treated as a manifest, so single-document config files are
+ * untouched.
+ * @param {unknown} doc
+ * @returns {boolean}
+ */
+function isKubernetesDocument(doc) {
+  return isPlainObject(doc)
+    && scalarField(doc, 'apiVersion') !== null
+    && scalarField(doc, 'kind') !== null;
+}
+
 /**
  * Keys for a multi-document file: identities when every document has a unique
  * one, otherwise document indices. It is all-or-nothing so keys within one file
@@ -194,10 +363,12 @@ function documentKeys(docs) {
 /**
  * Parse a YAML stream, supporting `---`-separated multi-document files.
  *
- * A file holding a single document parses to that document unchanged, so diff
- * paths for ordinary YAML are untouched. A file holding several documents
- * parses to an object keyed per document, which lets the differ walk it like
- * any other tree. Empty documents (a leading or trailing `---`, or a `null`
+ * A file holding a single *non-manifest* document parses to that document
+ * unchanged, so diff paths for ordinary YAML are untouched. A file holding
+ * several documents — or a single Kubernetes manifest — parses to an object
+ * keyed per document, which lets the differ walk it like any other tree and,
+ * crucially, keeps a manifest's paths stable when a second document is added
+ * beside it (#124). Empty documents (a leading or trailing `---`, or a `null`
  * document) are dropped, so a stray separator does not create a phantom entry.
  *
  * The keys it invents are recorded on the wrapper (see documents.js) so that
@@ -211,7 +382,20 @@ export function parseYamlStream(raw) {
   const docs = yaml.loadAll(raw).filter((doc) => doc != null);
 
   if (docs.length === 0) return withDocumentKeys({}, []);
-  if (docs.length === 1) return withDocumentKeys(docs[0], []);
+
+  // A lone document is normally returned bare, preserving ordinary YAML paths.
+  // The exception is a Kubernetes manifest with a resolvable identity: keying it
+  // now means adding a second document later leaves its paths unchanged, instead
+  // of re-pathing the whole file and reporting the untouched resource as
+  // removed-and-re-added. Ordinary single-document config is unaffected.
+  if (docs.length === 1) {
+    const [doc] = docs;
+    const identity = isKubernetesDocument(doc) ? documentIdentity(doc) : null;
+    if (identity == null || identity === '__proto__') {
+      return withDocumentKeys(doc, []);
+    }
+    return withDocumentKeys({ [identity]: doc }, [identity]);
+  }
 
   const keys = documentKeys(docs);
   /** @type {Record<string, unknown>} */
@@ -267,8 +451,8 @@ export function parseContent(filepath, raw) {
       parsed = dotenv.parse(raw);
     } else if (iniLike) {
       parsed = parseIni(raw);
-    } else if (ext === '.json') {
-      parsed = JSON.parse(raw);
+    } else if (ext === '.json' || ext === '.jsonc') {
+      parsed = parseJsonc(raw);
     } else if (ext === '.yaml' || ext === '.yml') {
       parsed = parseYamlStream(raw);
     } else if (ext === '.toml') {
@@ -282,6 +466,12 @@ export function parseContent(filepath, raw) {
     );
   }
 
+  // Guarded here, on the one path every generic command shares, rather than in
+  // each command: ci, watch, compare, report, and snapshot reads all land here,
+  // and so does a plan read out of git via --snapshot-ref. `flecto plan` reads
+  // through readTerraformPlanFile() instead and is unaffected (#113).
+  assertNotTerraformPlan(parsed, filepath);
+
   const keys = documentKeysOf(parsed) ?? [];
   return withDocumentKeys(normalizeEncrypted(normalizeParsedValue(parsed), keys), keys);
 }

package/src/policy-test.js

@@ -90,7 +90,7 @@ export function assertExpectedFindings(actual, expected) {
 /**
  * Run a policy fixture stored in a directory.
  * @param {string} fixtureDir
- * @param {{ configName?: string }} [options]
+ * @param {{ configName?: string, cwd?: string }} [options]
  */
 export async function testPolicyFixture(fixtureDir, options = {}) {
   const dir = resolve(fixtureDir);
@@ -117,6 +117,10 @@ export async function testPolicyFixture(fixtureDir, options = {}) {
     source: config.source ?? 'ci',
     policies: config.policies,
     plugins: config.plugins,
+    // A fixture's own policies/ still wins, so self-contained fixtures behave
+    // exactly as before. The invoking project is a fallback, which is where
+    // `flecto policies add` installs packs (#114).
+    packRoots: [options.cwd ?? process.cwd()],
   });
   assertExpectedFindings(findings, config.expected);
 

package/src/policy.js

@@ -29,6 +29,7 @@ import { containsSecret } from './secrets.js';
  *   beforeLooksSecret?: true,
  *   afterLooksSecret?: true,
  *   afterMatches?: string,
+ *   afterAnyMatches?: string,
  *   numericJump?: { minMultiple: number },
  *   numericDelta?: { min: number },
  *   allOf?: PolicyMatchClause[],
@@ -48,6 +49,7 @@ import { containsSecret } from './secrets.js';
  *   beforeLooksSecret?: true,
  *   afterLooksSecret?: true,
  *   afterMatches?: string,
+ *   afterAnyMatches?: string,
  *   numericJump?: { minMultiple: number },
  *   numericDelta?: { min: number }
  * }} PolicyMatchClause
@@ -74,6 +76,7 @@ import { containsSecret } from './secrets.js';
  *   source?: 'watch' | 'ci' | 'diff',
  *   policies?: string[],
  *   plugins?: string[],
+ *   packRoots?: string[],
  *   severityRemap?: Record<string, PolicySeverity | 'off'>
  * }} PolicyEvalOptions
  */
@@ -85,12 +88,12 @@ const RULE_FIELDS = new Set([
   'id', 'severity', 'when', 'match', 'beforeEquals', 'afterEquals',
   'beforeIn', 'afterIn', 'beforeTruthy', 'afterTruthy', 'numericJump',
   'beforeLooksSecret', 'afterLooksSecret',
-  'afterMatches', 'numericDelta', 'allOf', 'anyOf', 'message', 'messageTemplate',
+  'afterMatches', 'afterAnyMatches', 'numericDelta', 'allOf', 'anyOf', 'message', 'messageTemplate',
 ]);
 const CLAUSE_FIELDS = new Set([
   'match', 'beforeEquals', 'afterEquals', 'beforeIn', 'afterIn',
   'beforeTruthy', 'afterTruthy', 'beforeLooksSecret', 'afterLooksSecret',
-  'afterMatches', 'numericJump', 'numericDelta',
+  'afterMatches', 'afterAnyMatches', 'numericJump', 'numericDelta',
 ]);
 const MATCH_FIELDS = new Set(['path', 'pathFlags', 'pathEquals', 'pathPrefix']);
 // Community distribution convention: an npm package named flecto-pack-<id>
@@ -166,17 +169,34 @@ function validatePack(pack, path) {
 }
 
 /**
- * @param {string} cwd
+ * Every directory whose `policies/` is searched for a local pack, in order.
+ * The first entry is the primary cwd; later entries are fallbacks (the policy
+ * fixture harness runs from the fixture directory but packs are installed into
+ * the invoking project — see #114).
+ * @param {string | string[]} cwd
+ * @returns {string[]}
+ */
+function packRoots(cwd) {
+  const roots = (Array.isArray(cwd) ? cwd : [cwd])
+    .filter((root) => typeof root === 'string' && root)
+    .map((root) => resolve(root));
+  // Distinct roots only: a fixture run from the project root would otherwise
+  // search the same policies/ directory twice and report it twice on failure.
+  return [...new Set(roots)];
+}
+
+/**
+ * @param {string | string[]} cwd
  * @param {string} packId
  * @returns {string | null}
  */
 function resolvePackPath(cwd, packId) {
-  const localJson = resolve(cwd, 'policies', `${packId}.json`);
-  const localYaml = resolve(cwd, 'policies', `${packId}.yaml`);
-  const localYml = resolve(cwd, 'policies', `${packId}.yml`);
-  if (existsSync(localJson)) return localJson;
-  if (existsSync(localYaml)) return localYaml;
-  if (existsSync(localYml)) return localYml;
+  for (const root of packRoots(cwd)) {
+    for (const ext of ['.json', '.yaml', '.yml']) {
+      const localPath = resolve(root, 'policies', `${packId}${ext}`);
+      if (existsSync(localPath)) return localPath;
+    }
+  }
 
   const builtinJson = join(PACKS_DIR, `${packId}.json`);
   if (existsSync(builtinJson)) return builtinJson;
@@ -240,6 +260,7 @@ function validateRule(candidate, location, isClause = false) {
   validateTruthyPredicate(rule.beforeLooksSecret, 'beforeLooksSecret', location);
   validateTruthyPredicate(rule.afterLooksSecret, 'afterLooksSecret', location);
   validateRegexPredicate(rule.afterMatches, 'afterMatches', location);
+  validateRegexPredicate(rule.afterAnyMatches, 'afterAnyMatches', location);
   validateNumericPredicate(rule.numericJump, 'numericJump', 'minMultiple', location, true);
   validateNumericPredicate(rule.numericDelta, 'numericDelta', 'min', location, false);
   for (const name of ['message', 'messageTemplate']) {
@@ -359,13 +380,16 @@ function validateComposition(clauses, name, location) {
 const packCache = new Map();
 
 /**
- * @param {string} cwd
+ * @param {string[]} roots  already-resolved search roots, in order
  * @param {string} path
  * @param {number} mtimeMs
  * @returns {string}
  */
-function packCacheKey(cwd, path, mtimeMs) {
-  return `${resolve(cwd)}\u0000${path}\u0000${mtimeMs}`;
+function packCacheKey(roots, path, mtimeMs) {
+  // Roots are NUL-joined for the same reason the other fields are
+  // NUL-separated: two different root lists must never concatenate into the
+  // same key.
+  return `${roots.join('\u0000')}\u0000${path}\u0000${mtimeMs}`;
 }
 
 /**
@@ -385,11 +409,21 @@ export function loadPack(packId, cwd = process.cwd()) {
   if (!id) throw new Error('Policy pack id is required');
   const path = resolvePackPath(cwd, id);
   if (!path) {
-    throw new Error(`Unknown policy pack "${id}". Add policies/${id}.json or use a built-in pack.`);
+    // Name the directories actually searched. The old message always said
+    // "Add policies/<id>.json", which was actively misleading when the pack
+    // existed but in a directory this lookup never consulted (#114).
+    const searched = packRoots(cwd)
+      .map((root) => join(root, 'policies'))
+      .concat(PACKS_DIR)
+      .join(', ');
+    throw new Error(
+      `Unknown policy pack "${id}". Searched: ${searched}.`
+      + ` Add policies/${id}.json in one of these, or use a built-in pack.`,
+    );
   }
 
   const mtimeMs = statSync(path).mtimeMs;
-  const cacheKey = packCacheKey(cwd, path, mtimeMs);
+  const cacheKey = packCacheKey(packRoots(cwd), path, mtimeMs);
   const cached = packCache.get(cacheKey);
   if (cached) return cached;
 
@@ -700,15 +734,16 @@ export function addPolicyPackFromPackage(name, options = {}) {
 }
 
 /**
- * Compile each rule's `match.path` and `afterMatches` regular expressions
- * once, at pack-load time, storing them as non-enumerable properties on the
- * loaded rule/clause objects. matchClause() runs per change event — for a
- * rule with a path match, once per event per rule — so compiling here instead
- * of inside that loop turns a `new RegExp(...)` call into a property read.
+ * Compile each rule's `match.path`, `afterMatches`, and `afterAnyMatches`
+ * regular expressions once, at pack-load time, storing them as non-enumerable
+ * properties on the loaded rule/clause objects. matchClause() runs per change
+ * event — for a rule with a path match, once per event per rule — so compiling
+ * here instead of inside that loop turns a `new RegExp(...)` call into a
+ * property read.
  *
- * validatePack() has already proven, by this point, that every `match.path`
- * and `afterMatches` string constructs a valid RegExp, so construction here
- * cannot throw a new error the caller hasn't already seen.
+ * validatePack() has already proven, by this point, that every `match.path`,
+ * `afterMatches`, and `afterAnyMatches` string constructs a valid RegExp, so
+ * construction here cannot throw a new error the caller hasn't already seen.
  * @param {PolicyPack} pack
  */
 function compilePackRegexes(pack) {
@@ -733,6 +768,12 @@ function compileClauseRegexes(clause) {
       enumerable: false,
     });
   }
+  if (clause.afterAnyMatches !== undefined) {
+    Object.defineProperty(clause, '_afterAnyMatchesRegex', {
+      value: new RegExp(clause.afterAnyMatches),
+      enumerable: false,
+    });
+  }
 }
 
 /**
@@ -754,6 +795,29 @@ function afterMatchesRegexFor(clause) {
   return clause._afterMatchesRegex ?? new RegExp(clause.afterMatches);
 }
 
+/**
+ * @param {{ afterAnyMatches?: string, _afterAnyMatchesRegex?: RegExp }} clause
+ * @returns {RegExp}
+ */
+function afterAnyMatchesRegexFor(clause) {
+  return clause._afterAnyMatchesRegex ?? new RegExp(clause.afterAnyMatches);
+}
+
+/**
+ * True when `value` is an array carrying at least one string element that
+ * matches. Deliberately a flat scan: it does not descend into nested arrays or
+ * objects, because a rule's text should say what it matches without the reader
+ * having to reason about how deep the walk goes. Non-array values never match,
+ * which is what keeps `afterMatches` and this predicate from overlapping.
+ * @param {unknown} value
+ * @param {RegExp} regex
+ * @returns {boolean}
+ */
+function anyElementMatches(value, regex) {
+  return Array.isArray(value)
+    && value.some((element) => typeof element === 'string' && regex.test(element));
+}
+
 /**
  * @param {PolicyRule} rule
  * @param {import('./differ.js').ChangeEvent} change
@@ -791,6 +855,10 @@ function matchClause(clause, change) {
   if (clause.beforeLooksSecret && !containsSecret(change.before)) return false;
   if (clause.afterLooksSecret && !containsSecret(change.after)) return false;
   if (clause.afterMatches && (typeof change.after !== 'string' || !afterMatchesRegexFor(clause).test(change.after))) return false;
+  // The list counterpart, for the change that turns a scalar into a list in
+  // one edit -- reported as a single `changed` event whose `after` is an array,
+  // which no scalar predicate can see into.
+  if (clause.afterAnyMatches && !anyElementMatches(change.after, afterAnyMatchesRegexFor(clause))) return false;
 
   if (clause.numericJump) {
     const before = change.before;
@@ -1020,10 +1088,15 @@ export async function evaluatePolicies(changes, options = {}) {
   const packIds = options.policies?.length ? options.policies : ['default'];
   const plugins = options.plugins ?? [];
   const severityRemap = options.severityRemap ?? {};
+  // Packs may resolve from additional roots (the fixture harness adds the
+  // invoking project, #114). Plugin resolution deliberately stays anchored to
+  // the single `cwd` below: widening where executable code loads from is not
+  // the same decision as widening where declarative packs load from.
+  const packSearchRoots = options.packRoots?.length ? [cwd, ...options.packRoots] : cwd;
 
   /** @type {PolicyFinding[]} */
   const findings = [];
-  const packs = packIds.map((packId) => loadPack(packId, cwd));
+  const packs = packIds.map((packId) => loadPack(packId, packSearchRoots));
   const knownRuleIds = new Set(packs.flatMap((pack) => pack.rules.map((rule) => String(rule.id))));
   for (const ruleId of Object.keys(severityRemap)) {
     if (!knownRuleIds.has(ruleId)) {