@promptci/core 0.1.0 → 0.2.1

package/dist/action-pinning.d.ts

@@ -0,0 +1,37 @@
+import type { RepoContext } from './repo-context.js';
+import type { PromptCiIssue } from './types.js';
+export type ActionUse = {
+    /** The `uses:` value as written (quotes and trailing comment stripped). */
+    ref: string;
+    /** 1-based line number. */
+    line: number;
+};
+export type UnpinnedUse = ActionUse & {
+    /**
+     * False when the ref's text does not match the plain `owner/repo[/path]@ref`
+     * shape. Such a ref is still reported, but its raw text is never
+     * interpolated into titles, evidence, or the recommended `gh` command — it
+     * came from the scanned repo and may carry shell or Markdown metacharacters.
+     */
+    displayable: boolean;
+    /** `owner/repo[/path]` part before the `@` (only meaningful when displayable). */
+    action: string;
+    /** Git ref after the `@` (only meaningful when displayable). */
+    version: string;
+    owner: string;
+};
+/**
+ * Every step/job-level `uses:` reference in a workflow or composite-action
+ * file, in line order. Skipped: comments, lines inside block scalars (a
+ * `run: |` script that prints `uses: foo@v1`), and `uses` keys nested under
+ * data mappings such as `with:`.
+ */
+export declare function extractActionUses(content: string): ActionUse[];
+/**
+ * Classify one `uses:` value. Returns the parts for a remote ref that should
+ * be pinned but is not, or `undefined` when it is pinned, local, a container,
+ * or an expression.
+ */
+export declare function unpinnedUse(use: ActionUse): UnpinnedUse | undefined;
+export declare function detectActionPinning(context: RepoContext): PromptCiIssue[];
+//# sourceMappingURL=action-pinning.d.ts.map

package/dist/action-pinning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-pinning.d.ts","sourceRoot":"","sources":["../src/action-pinning.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAwDhD,MAAM,MAAM,SAAS,GAAG;IACtB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG;IACpC;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AA6DF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CA6C9D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAoBnE;AA6ED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,aAAa,EAAE,CAkBzE"}

package/dist/action-pinning.js

@@ -0,0 +1,277 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+/**
+ * GitHub Actions pinning detector (detect-only).
+ *
+ * Flags `uses:` references in `.github/workflows/*.yml` and in composite
+ * actions (`action.yml` at the repo root or under `.github/actions/`) that
+ * point at a tag or branch instead of a full commit SHA. A tag is a mutable
+ * pointer: whoever can push to the action's repository can move it, and every
+ * workflow referencing it runs the new code on its next run. A SHA cannot be
+ * repointed.
+ *
+ * Deliberately DETECT-ONLY: there is no fix recipe and `autoApplySafe` is never
+ * set. Resolving a tag to its SHA needs a network call, and this package makes
+ * none from detector code — pinning is left to the user (or Dependabot /
+ * Renovate, which keep a pinned SHA and its version comment in step).
+ *
+ * Exempt: local actions (`./path`) and container actions (`docker://…`), which
+ * have no git ref to pin. These files are read from `workflows.sources`, never
+ * from `context.files`, so they are never treated as instruction files.
+ *
+ * Deterministic and offline: line-oriented parsing of the YAML text, no clock,
+ * no network.
+ */
+/** A full git commit id: 40-hex SHA-1, or 64-hex for SHA-256 repositories. */
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+/** `owner/repo` or `owner/repo/sub/path` — the only action shape shown verbatim. */
+const ACTION_RE = /^[\w.-]+\/[\w.-]+(?:\/[\w./-]+)?$/;
+/** A plausible tag/branch name — the only version shape shown verbatim. */
+const VERSION_RE = /^[\w./+-]+$/;
+/**
+ * Owners whose actions GitHub itself maintains. An unpinned first-party ref is
+ * still a mutable pointer, but the account holding it is GitHub's own, so it
+ * is reported one severity lower than a third-party ref.
+ */
+const FIRST_PARTY_OWNERS = new Set(['actions', 'github']);
+/** A `key: value` mapping line, optionally the first key of a list item. */
+const KEY_LINE_RE = /^(\s*)(-\s+)?([\w.-]+)\s*:(?:\s+(.*))?$/;
+/** A list item whose value is a flow mapping: `- { uses: x@v1, with: {...} }`. */
+const FLOW_ITEM_RE = /^\s*-\s+(\{.*)$/;
+/** A block scalar indicator (`|`, `>-`, `|2+`), optionally followed by a comment. */
+const BLOCK_SCALAR_RE = /^[|>][+-]?\d*\s*(?:#.*)?$/;
+/**
+ * Keys whose block-mapping values are free-form data, not steps. A `uses:` key
+ * nested under them (e.g. an input literally named `uses`) is not a step.
+ */
+const DATA_MAPPING_KEYS = new Set(['with', 'env', 'secrets', 'inputs', 'outputs']);
+/** Strip a trailing ` # comment` and surrounding quotes from a scalar value. */
+function scalarValue(raw) {
+    let value = raw.trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+        const end = value.indexOf(quote, 1);
+        return end > 0 ? value.slice(1, end) : value.slice(1);
+    }
+    const comment = value.search(/(?:^|\s)#/);
+    if (comment >= 0)
+        value = value.slice(0, comment);
+    return value.trim();
+}
+/**
+ * The value of a top-level `uses` key in a single-line flow mapping, or
+ * undefined. Nested maps (`with: { uses: … }`) are depth > 1 and ignored.
+ */
+function flowMappingUses(flow) {
+    const entries = [];
+    let depth = 0;
+    let quote = '';
+    let current = '';
+    for (const c of flow) {
+        if (quote) {
+            if (c === quote)
+                quote = '';
+            if (depth === 1)
+                current += c;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            if (depth === 1)
+                current += c;
+            continue;
+        }
+        if (c === '{' || c === '[') {
+            depth++;
+            if (depth > 1)
+                current += c;
+            continue;
+        }
+        if (c === '}' || c === ']') {
+            depth--;
+            if (depth === 0)
+                break;
+            current += c;
+            continue;
+        }
+        if (c === ',' && depth === 1) {
+            entries.push(current);
+            current = '';
+            continue;
+        }
+        if (depth >= 1)
+            current += c;
+    }
+    entries.push(current);
+    for (const entry of entries) {
+        const m = /^\s*uses\s*:\s*(.*)$/.exec(entry);
+        if (m)
+            return scalarValue(m[1]);
+    }
+    return undefined;
+}
+/**
+ * Every step/job-level `uses:` reference in a workflow or composite-action
+ * file, in line order. Skipped: comments, lines inside block scalars (a
+ * `run: |` script that prints `uses: foo@v1`), and `uses` keys nested under
+ * data mappings such as `with:`.
+ */
+export function extractActionUses(content) {
+    const lines = content.split(/\r?\n/);
+    const uses = [];
+    // Lines indented deeper than this column belong to a block scalar or data
+    // mapping and are skipped; -1 = not inside one.
+    let skipDeeperThan = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '')
+            continue;
+        const indent = /^\s*/.exec(line)[0].length;
+        if (skipDeeperThan >= 0) {
+            if (indent > skipDeeperThan)
+                continue;
+            skipDeeperThan = -1;
+        }
+        if (/^\s*#/.test(line))
+            continue;
+        const flow = FLOW_ITEM_RE.exec(line);
+        if (flow) {
+            const ref = flowMappingUses(flow[1]);
+            if (ref)
+                uses.push({ ref, line: i + 1 });
+            continue;
+        }
+        const kv = KEY_LINE_RE.exec(line);
+        if (!kv)
+            continue;
+        const keyCol = kv[1].length + (kv[2]?.length ?? 0);
+        const key = kv[3];
+        const rawValue = kv[4] ?? '';
+        const value = rawValue.trim();
+        if (key === 'uses') {
+            const ref = scalarValue(rawValue);
+            if (ref)
+                uses.push({ ref, line: i + 1 });
+            continue;
+        }
+        if (BLOCK_SCALAR_RE.test(value)) {
+            skipDeeperThan = keyCol;
+            continue;
+        }
+        if ((value === '' || value.startsWith('#')) && DATA_MAPPING_KEYS.has(key)) {
+            skipDeeperThan = keyCol;
+        }
+    }
+    return uses;
+}
+/**
+ * Classify one `uses:` value. Returns the parts for a remote ref that should
+ * be pinned but is not, or `undefined` when it is pinned, local, a container,
+ * or an expression.
+ */
+export function unpinnedUse(use) {
+    const { ref } = use;
+    if (ref.startsWith('./') || ref.startsWith('.\\'))
+        return undefined; // local action
+    if (ref.startsWith('docker://'))
+        return undefined; // container action
+    if (ref.includes('${{'))
+        return undefined; // expression — not statically resolvable
+    const at = ref.lastIndexOf('@');
+    if (at <= 0 || !ref.slice(0, at).includes('/'))
+        return undefined; // not a remote action ref
+    const action = ref.slice(0, at);
+    const version = ref.slice(at + 1);
+    if (FULL_SHA_RE.test(version))
+        return undefined;
+    const displayable = ACTION_RE.test(action) && VERSION_RE.test(version);
+    return {
+        ...use,
+        displayable,
+        action,
+        version,
+        owner: displayable ? action.split('/')[0].toLowerCase() : '',
+    };
+}
+function shortHash(value) {
+    return crypto.createHash('sha1').update(value).digest('hex').slice(0, 12);
+}
+/** Belt and braces for text that is shown inside Markdown code spans. */
+function codeSafe(text) {
+    return text.replace(/`/g, "'");
+}
+function buildIssue(context, site) {
+    const { filePath, lines, use } = site;
+    const absPath = path.resolve(context.repoRoot, filePath);
+    const base = {
+        // One finding per (file, ref): pinning the ref in one workflow must not
+        // re-key the finding for the other files that still use it.
+        id: `action-pin-${shortHash(`action-pin:${filePath}:${use.ref}`)}`,
+        category: 'security',
+        // Absolute, like every other finding's paths; the JSON report relativizes.
+        filePaths: [absPath],
+        locations: lines.map((line) => ({ filePath: absPath, startLine: line, endLine: line })),
+        // The ref is certainly mutable; whether that matters for this repo is the
+        // heuristic part, so confidence stays below 1 and the score hit modest
+        // (and capped — see TAG_DEDUCTION_CAP in health-score.ts).
+        confidence: 0.8,
+        tags: ['supply-chain', 'github-actions'],
+    };
+    const why = "A tag or branch is a mutable pointer: whoever can push to the action's repository can move " +
+        "it, and the next run executes the new code with this repository's token and secrets.";
+    if (!use.displayable) {
+        // The raw value never reaches the title, evidence, or a shell command.
+        return {
+            ...base,
+            severity: 'warning',
+            title: 'GitHub Action reference is not pinned to a commit SHA',
+            summary: `${filePath} has a \`uses:\` reference (line ${lines.join(', ')}) that is not pinned to a full ` +
+                `commit SHA and does not look like a plain \`owner/repo@ref\` value. ${why}`,
+            // No line numbers (baseline fingerprints hash evidence); a hash of the
+            // raw value keeps two different refs in one file distinct.
+            evidence: [`${filePath}: unrecognised uses: value (sha1 ${shortHash(use.ref)})`],
+            recommendation: 'Review this `uses:` line by hand. Pin the action to the full 40-character commit SHA of a ' +
+                "release you trust (resolved from the action's own repository), keep the version in a trailing " +
+                'comment, and let Dependabot or Renovate update both. PromptCI reports this but does not rewrite ' +
+                'workflow files.',
+        };
+    }
+    const firstParty = FIRST_PARTY_OWNERS.has(use.owner);
+    const [repoOwner, repoName] = use.action.split('/');
+    const ref = codeSafe(use.ref);
+    return {
+        ...base,
+        severity: firstParty ? 'info' : 'warning',
+        title: `GitHub Action \`${ref}\` is not pinned to a commit SHA`,
+        summary: `${filePath} references \`${codeSafe(use.action)}\` at \`${codeSafe(use.version)}\`, which appears ` +
+            `to be a tag or branch rather than a full commit SHA. ${why} ` +
+            (firstParty
+                ? 'This action is maintained by GitHub, which lowers but does not remove the risk.'
+                : 'Consider pinning third-party actions to a reviewed commit.'),
+        evidence: [`${filePath}: uses: ${ref}`],
+        recommendation: 'Pin the action to the full commit SHA of the release you trust and keep the version in a ' +
+            `trailing comment, e.g. \`uses: ${codeSafe(use.action)}@<40-char-sha> # ${codeSafe(use.version)}\`. ` +
+            `Resolve the SHA from the action's own repository (\`gh api repos/${repoOwner}/${repoName}/commits/` +
+            `${use.version} --jq .sha\`), and let Dependabot or Renovate update the SHA and comment together. ` +
+            'PromptCI reports this but does not rewrite workflow files.',
+    };
+}
+export function detectActionPinning(context) {
+    const sources = context.workflows.sources ?? [];
+    // Group occurrences by (file, ref): several jobs in one workflow using the
+    // same unpinned action are one fix, and one finding.
+    const sites = new Map();
+    for (const source of sources) {
+        for (const use of extractActionUses(source.content)) {
+            const unpinned = unpinnedUse(use);
+            if (!unpinned)
+                continue;
+            const key = `${source.filePath}\u0000${unpinned.ref}`;
+            const site = sites.get(key) ?? { filePath: source.filePath, lines: [], use: unpinned };
+            site.lines.push(unpinned.line);
+            sites.set(key, site);
+        }
+    }
+    return [...sites.keys()].sort().map((key) => buildIssue(context, sites.get(key)));
+}
+//# sourceMappingURL=action-pinning.js.map

package/dist/action-pinning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-pinning.js","sourceRoot":"","sources":["../src/action-pinning.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAIlC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,GAAG,kCAAkC,CAAC;AAEvD,oFAAoF;AACpF,MAAM,SAAS,GAAG,mCAAmC,CAAC;AAEtD,2EAA2E;AAC3E,MAAM,UAAU,GAAG,aAAa,CAAC;AAEjC;;;;GAIG;AACH,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,GAAG,yCAAyC,CAAC;AAE9D,kFAAkF;AAClF,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAEvC,qFAAqF;AACrF,MAAM,eAAe,GAAG,2BAA2B,CAAC;AAEpD;;;GAGG;AACH,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAwBxG,gFAAgF;AAChF,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACpC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC1C,IAAI,OAAO,IAAI,CAAC;QAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,KAAK,KAAK;gBAAE,KAAK,GAAG,EAAE,CAAC;YAC5B,IAAI,KAAK,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC,CAAC;YAC9B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YAC3B,KAAK,GAAG,CAAC,CAAC;YACV,IAAI,KAAK,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC,CAAC;YAC9B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YAC3B,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YAC3B,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,CAAC;gBAAE,MAAM;YACvB,OAAO,IAAI,CAAC,CAAC;YACb,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,EAAE,CAAC;YACb,SAAS;QACX,CAAC;QACD,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC;YAAE,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,0EAA0E;IAC1E,gDAAgD;IAChD,IAAI,cAAc,GAAG,CAAC,CAAC,CAAC;IAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACvB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACjC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC5C,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;YACxB,IAAI,MAAM,GAAG,cAAc;gBAAE,SAAS;YACtC,cAAc,GAAG,CAAC,CAAC,CAAC;QACtB,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAEjC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC;YACtC,IAAI,GAAG;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACzC,SAAS;QACX,CAAC;QAED,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,EAAE;YAAE,SAAS;QAClB,MAAM,MAAM,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC;QACnB,MAAM,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAE9B,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;YAClC,IAAI,GAAG;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACzC,SAAS;QACX,CAAC;QACD,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,cAAc,GAAG,MAAM,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,KAAK,EAAE,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1E,cAAc,GAAG,MAAM,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAc;IACxC,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;IACpB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC,CAAC,eAAe;IACpF,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC,CAAC,mBAAmB;IACtE,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC,CAAC,yCAAyC;IAEpF,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC,CAAC,0BAA0B;IAC5F,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAClC,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAEhD,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvE,OAAO;QACL,GAAG,GAAG;QACN,WAAW;QACX,MAAM;QACN,OAAO;QACP,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE;KAC9D,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC5E,CAAC;AAED,yEAAyE;AACzE,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC;AAID,SAAS,UAAU,CAAC,OAAoB,EAAE,IAAU;IAClD,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG;QACX,wEAAwE;QACxE,4DAA4D;QAC5D,EAAE,EAAE,cAAc,SAAS,CAAC,cAAc,QAAQ,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE;QAClE,QAAQ,EAAE,UAAmB;QAC7B,2EAA2E;QAC3E,SAAS,EAAE,CAAC,OAAO,CAAC;QACpB,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACvF,0EAA0E;QAC1E,uEAAuE;QACvE,2DAA2D;QAC3D,UAAU,EAAE,GAAG;QACf,IAAI,EAAE,CAAC,cAAc,EAAE,gBAAgB,CAAC;KACzC,CAAC;IACF,MAAM,GAAG,GACP,6FAA6F;QAC7F,sFAAsF,CAAC;IAEzF,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACrB,uEAAuE;QACvE,OAAO;YACL,GAAG,IAAI;YACP,QAAQ,EAAE,SAAS;YACnB,KAAK,EAAE,uDAAuD;YAC9D,OAAO,EACL,GAAG,QAAQ,oCAAoC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC;gBAChG,uEAAuE,GAAG,EAAE;YAC9E,uEAAuE;YACvE,2DAA2D;YAC3D,QAAQ,EAAE,CAAC,GAAG,QAAQ,oCAAoC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;YAChF,cAAc,EACZ,4FAA4F;gBAC5F,gGAAgG;gBAChG,kGAAkG;gBAClG,iBAAiB;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,OAAO;QACL,GAAG,IAAI;QACP,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACzC,KAAK,EAAE,mBAAmB,GAAG,kCAAkC;QAC/D,OAAO,EACL,GAAG,QAAQ,iBAAiB,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,oBAAoB;YACpG,wDAAwD,GAAG,GAAG;YAC9D,CAAC,UAAU;gBACT,CAAC,CAAC,iFAAiF;gBACnF,CAAC,CAAC,4DAA4D,CAAC;QACnE,QAAQ,EAAE,CAAC,GAAG,QAAQ,WAAW,GAAG,EAAE,CAAC;QACvC,cAAc,EACZ,2FAA2F;YAC3F,kCAAkC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,oBAAoB,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM;YACrG,oEAAoE,SAAS,IAAI,QAAQ,WAAW;YACpG,GAAG,GAAG,CAAC,OAAO,qFAAqF;YACnG,4DAA4D;KAC/D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAoB;IACtD,MAAM,OAAO,GAAqB,OAAO,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC;IAElE,2EAA2E;IAC3E,qDAAqD;IACrD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACpD,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,QAAQ;gBAAE,SAAS;YACxB,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,QAAQ,SAAS,QAAQ,CAAC,GAAG,EAAE,CAAC;YACtD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;YACvF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,CAAC,CAAC;AACrF,CAAC"}

package/dist/agent-practices.d.ts

@@ -20,5 +20,5 @@
  * All findings are info/warning severity — these are guidance gaps, not errors.
  */
 import type { InstructionFile, PromptCiIssue } from './types.js';
-export declare function detectAgentPractices(files: InstructionFile[]): PromptCiIssue[];
+export declare function detectAgentPractices(files: InstructionFile[], aliases?: InstructionFile[]): PromptCiIssue[];
 //# sourceMappingURL=agent-practices.d.ts.map

package/dist/agent-practices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-practices.d.ts","sourceRoot":"","sources":["../src/agent-practices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+WjE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CA4T9E"}
+{"version":3,"file":"agent-practices.d.ts","sourceRoot":"","sources":["../src/agent-practices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAscjE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,OAAO,GAAE,eAAe,EAAO,GAAG,aAAa,EAAE,CAwS/G"}

package/dist/agent-practices.js

@@ -22,6 +22,8 @@
 import * as crypto from 'node:crypto';
 import * as path from 'node:path';
 import { stripCodeBlocks } from './markdown-fences.js';
+import { fileIdPath } from './finding-id.js';
+import { aliasesWithNewType, groupAliasesByTarget } from './alias-files.js';
 const CHECKS = [
     {
         id: 'no-verification-loop',
@@ -225,6 +227,12 @@ const CLAUDE_XML_TAG_RE = /<\/?claude:[\w-]+|<instructions-for-claude[\s>]/i;
 // and must not exempt the file. The `.md` extension is required so prose like
 // "use Claude to review" cannot match the bare word.
 const FORWARDING_RE = /(?:follow|use|see|refer\s+to|canonical\s+(?:source|instructions?)|pointer\s+to)\s+[`'"*]*(?:\.?\/)?(?:\.github\/)?(?:AGENTS|CLAUDE)\.md\b/i;
+// The same delegation phrased subject-first: "`AGENTS.md` is the single source
+// of truth for all agents" / "AGENTS.md is canonical". Common in the tool stubs
+// (GEMINI.md, .clinerules) that rule-sync setups generate next to AGENTS.md.
+// Same-line only, so an unrelated "canonical" further down cannot pair up; and
+// a file naming ITSELF as the source of truth is not delegating (see caller).
+const SOURCE_OF_TRUTH_RE = /\b(AGENTS|CLAUDE)\.md\b[^\n]{0,60}?\b(?:single\s+source\s+of\s+truth|canonical)\b/i;
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function issueId(checkId) {
     const hash = crypto.createHash('sha1').update(checkId).digest('hex').slice(0, 12);
@@ -313,6 +321,18 @@ function perFileBehaviorTarget(file) {
     if (isCopilotInstructionsFile(file)) {
         return { label: '.github/copilot-instructions.md', agent: 'GitHub Copilot' };
     }
+    // GEMINI.md and a single-file `.clinerules` are read standalone by their
+    // tool, exactly like the files above — the same BUG-19 reasoning as
+    // `.windsurfrules`. Files inside a `.clinerules/` DIRECTORY are not targets:
+    // Cline concatenates the whole directory, so one rule file lacking guidance
+    // that a sibling provides is not a gap. Persona files (SOUL.md etc.) are not
+    // tool-specific rule files, so they are not per-agent targets either.
+    if (file.fileType === 'gemini') {
+        return { label: 'GEMINI.md', agent: 'Gemini CLI' };
+    }
+    if (file.fileType === 'cline' && path.basename(file.path) === '.clinerules') {
+        return { label: '.clinerules', agent: 'Cline' };
+    }
     return undefined;
 }
 function isForwardingFile(file) {
@@ -324,13 +344,76 @@ function isForwardingFile(file) {
     const head = file.content.split(/\r?\n/).slice(0, 12).join('\n');
     if (FORWARDING_RE.test(head))
         return true;
+    const sourceOfTruth = SOURCE_OF_TRUTH_RE.exec(head);
+    if (sourceOfTruth && `${sourceOfTruth[1].toLowerCase()}.md` !== path.basename(file.path).toLowerCase()) {
+        return true;
+    }
     // Legacy: a short file with a forwarding pointer anywhere.
     return file.lineCount < 20 && FORWARDING_RE.test(file.content);
 }
 // ── Detector ─────────────────────────────────────────────────────────────────
-export function detectAgentPractices(files) {
+/**
+ * Symlink aliases whose OWN tool-specific name adds a per-agent target the real
+ * file does not have: `CLAUDE.md -> AGENTS.md` means Claude reads AGENTS.md's
+ * content, so the per-file behavior checks apply to it as the CLAUDE.md it is.
+ * An alias whose target is the same kind of file as the real one adds nothing.
+ */
+function aliasesWithNewTarget(files, aliases) {
+    return aliases.filter((alias) => {
+        const target = perFileBehaviorTarget(alias);
+        if (!target)
+            return false;
+        const canonical = files.find((f) => f.relativePath === alias.aliasOf);
+        return canonical === undefined || perFileBehaviorTarget(canonical)?.label !== target.label;
+    });
+}
+/** A Claude XML tag is only meaningful in a CLAUDE.md; README files document the tags as examples. */
+function isClaudeTagTarget(fileType) {
+    return fileType !== 'claude' && fileType !== 'readme';
+}
+/**
+ * BUG-007: Claude-specific XML tags in a non-Claude instruction file.
+ * <claude:thinking> and similar tags are Claude-specific features; embedding them
+ * in .cursorrules or AGENTS.md is tool-specific syntax in the wrong file type.
+ * Skip README files — they often document Claude XML tags as examples rather than using them
+ * Skip if the tag only appears inside fenced code blocks (documentation, not real usage)
+ */
+function claudeXmlTagIssue(names) {
+    // `names` is one real file, or every link to one real file (one finding listing them all, id from the first).
+    const file = names[0];
+    if (!isClaudeTagTarget(file.fileType))
+        return undefined;
+    const contentOutsideCode = stripCodeBlocks(file.content).replace(/`[^`\n]+`/g, '');
+    if (!CLAUDE_XML_TAG_RE.test(contentOutsideCode))
+        return undefined;
+    const hash = crypto.createHash('sha1').update(`claude-xml-tag:${fileIdPath(file)}`).digest('hex').slice(0, 12);
+    // AP3: search contentOutsideCode (the same text the gate above tested),
+    // not the raw file.content — otherwise an earlier occurrence of the
+    // tag that exists ONLY inside a code fence (documentation, not real
+    // usage) could be picked as evidence instead of the real match that
+    // actually made the gate fire.
+    const firstTag = (/<\/?claude:[\w-]+/i).exec(contentOutsideCode)?.[0] ?? '<claude:...>';
+    return {
+        id: `claude-xml-tag-${hash}`,
+        severity: 'warning',
+        category: 'structure',
+        title: 'Claude-specific XML tag in non-Claude instruction file',
+        summary: `This file contains a Claude-specific XML tag (${firstTag}) but is not a CLAUDE.md file. ` +
+            `Claude XML tags are only interpreted by Claude; other AI tools (Cursor, Copilot, etc.) ` +
+            `will treat them as literal text or ignore them.`,
+        filePaths: names.map((f) => f.path),
+        locations: names.map((f) => ({ filePath: f.path })),
+        evidence: [`Found: ${firstTag} in ${[...new Set(names.map((f) => f.fileType))].join(', ')} file`],
+        recommendation: 'Move Claude-specific directives to CLAUDE.md, or replace this tag with a plain-text ' +
+            'instruction that all tools can understand.',
+        confidence: 0.85,
+    };
+}
+export function detectAgentPractices(files, aliases = []) {
     if (files.length === 0)
         return [];
+    // Files the per-agent checks run over: every scanned file plus the symlink aliases that are a different tool's file.
+    const targetFiles = [...files, ...aliasesWithNewTarget(files, aliases)];
     const issues = [];
     const combinedContent = files.map((f) => f.content).join('\n');
     // BUG-002: For the verification-loop check, strip human-facing checklist items
@@ -378,7 +461,7 @@ export function detectAgentPractices(files) {
     // granular "missing critical guidance" issues (one per CHECKS entry),
     // inflating the health-score penalty ~6x for a single underlying gap.
     const filesWithNoGuidanceFinding = new Set();
-    for (const file of files) {
+    for (const file of targetFiles) {
         const target = perFileBehaviorTarget(file);
         if (!target)
             continue;
@@ -396,7 +479,7 @@ export function detectAgentPractices(files) {
             continue;
         filesWithNoGuidanceFinding.add(file.path);
         issues.push({
-            id: perFileBehaviorIssueId(file.path),
+            id: perFileBehaviorIssueId(fileIdPath(file)),
             severity: 'warning',
             category: 'agent_practices',
             title: `No behavioral guidance in ${target.label}`,
@@ -424,7 +507,7 @@ export function detectAgentPractices(files) {
         const sourceFile = files.find((f) => matchesAny(stripChecklistLines(f.content), check.patterns));
         if (!sourceFile)
             continue;
-        for (const file of files) {
+        for (const file of targetFiles) {
             if (file === sourceFile)
                 continue;
             const target = perFileBehaviorTarget(file);
@@ -439,7 +522,7 @@ export function detectAgentPractices(files) {
             const hasThisGuidance = matchesAny(stripChecklistLines(file.content), check.patterns);
             if (!hasThisGuidance) {
                 const checkName = check.title.toLowerCase().replace('no ', '').replace(' instruction', '');
-                const hash = crypto.createHash('sha1').update(`behavior-gap:${file.path}:${check.id}`).digest('hex').slice(0, 12);
+                const hash = crypto.createHash('sha1').update(`behavior-gap:${fileIdPath(file)}:${check.id}`).digest('hex').slice(0, 12);
                 issues.push({
                     id: `per-file-behavioral-gap-${hash}`,
                     severity: 'warning',
@@ -488,7 +571,7 @@ export function detectAgentPractices(files) {
     if (hasGeneralBehaviorOnlyInCopilot()) {
         const copilotFile = files.find(isCopilotInstructionsFile);
         issues.push({
-            id: copilotAgentBehaviorId(copilotFile.path),
+            id: copilotAgentBehaviorId(fileIdPath(copilotFile)),
             severity: 'warning',
             category: 'structure',
             title: 'General behavioral guidance placed only in Copilot instructions',
@@ -511,10 +594,10 @@ export function detectAgentPractices(files) {
         if (!matchesAny(file.content, KEY_BEHAVIORAL_PATTERNS))
             continue;
         // Check if we already flagged this via general-behavior-only check
-        if (issues.some(i => i.id === copilotAgentBehaviorId(file.path)))
+        if (issues.some(i => i.id === copilotAgentBehaviorId(fileIdPath(file))))
             continue;
         issues.push({
-            id: copilotAgentBehaviorId(file.path),
+            id: copilotAgentBehaviorId(fileIdPath(file)),
             severity: 'warning',
             category: 'structure',
             title: 'Agent-behavior section in copilot-instructions.md',
@@ -545,7 +628,7 @@ export function detectAgentPractices(files) {
         if (hasDoNotEdit && !hasGeneratorNote) {
             // Case 1 (original): "do not edit" present but NO generator note.
             issues.push({
-                id: doNotEditIssueId(file.path),
+                id: doNotEditIssueId(fileIdPath(file)),
                 severity: 'warning',
                 category: 'agent_practices',
                 title: '"Do not edit" header in human-maintained instruction file',
@@ -568,7 +651,7 @@ export function detectAgentPractices(files) {
                 return `auto-gen-header-${hash}`;
             };
             issues.push({
-                id: autoGenId(file.path),
+                id: autoGenId(fileIdPath(file)),
                 severity: 'warning',
                 category: 'agent_practices',
                 title: 'Misleading auto-generated header on human-maintained instruction file',
@@ -583,39 +666,20 @@ export function detectAgentPractices(files) {
                 confidence: 0.75,
             });
         }
-        // BUG-007: Detect Claude-specific XML tags in non-Claude instruction files.
-        // <claude:thinking> and similar tags are Claude-specific features; embedding them
-        // in .cursorrules or AGENTS.md is tool-specific syntax in the wrong file type.
-        // Skip README files — they often document Claude XML tags as examples rather than using them
-        // Skip if the tag only appears inside fenced code blocks (documentation, not real usage)
-        const contentOutsideCode = stripCodeBlocks(file.content).replace(/`[^`\n]+`/g, '');
-        if (file.fileType !== 'claude' && file.fileType !== 'readme' && CLAUDE_XML_TAG_RE.test(contentOutsideCode)) {
-            const claudeTagId = (p) => {
-                const hash = crypto.createHash('sha1').update(`claude-xml-tag:${p}`).digest('hex').slice(0, 12);
-                return `claude-xml-tag-${hash}`;
-            };
-            // AP3: search contentOutsideCode (the same text the gate above tested),
-            // not the raw file.content — otherwise an earlier occurrence of the
-            // tag that exists ONLY inside a code fence (documentation, not real
-            // usage) could be picked as evidence instead of the real match that
-            // actually made the gate fire.
-            const firstTag = (/<\/?claude:[\w-]+/i).exec(contentOutsideCode)?.[0] ?? '<claude:...>';
-            issues.push({
-                id: claudeTagId(file.path),
-                severity: 'warning',
-                category: 'structure',
-                title: 'Claude-specific XML tag in non-Claude instruction file',
-                summary: `This file contains a Claude-specific XML tag (${firstTag}) but is not a CLAUDE.md file. ` +
-                    `Claude XML tags are only interpreted by Claude; other AI tools (Cursor, Copilot, etc.) ` +
-                    `will treat them as literal text or ignore them.`,
-                filePaths: [file.path],
-                locations: [{ filePath: file.path }],
-                evidence: [`Found: ${firstTag} in ${file.fileType} file`],
-                recommendation: 'Move Claude-specific directives to CLAUDE.md, or replace this tag with a plain-text ' +
-                    'instruction that all tools can understand.',
-                confidence: 0.85,
-            });
-        }
+        const claudeTag = claudeXmlTagIssue([file]);
+        if (claudeTag)
+            issues.push(claudeTag);
+    }
+    // The Claude-tag check is gated by file type, and `AGENTS.md -> CLAUDE.md` is an AGENTS.md to every
+    // tool that reads that name: run it for such an alias, against the real content. (An alias of a file
+    // that is already "not Claude" would only repeat the real file's finding, so it is left out.) The
+    // other per-type content checks above are not repeated for aliases: "do not edit" is type-independent,
+    // and the Copilot agent-behavior check assumes copilot-instructions.md is Copilot-only, which a link
+    // to AGENTS.md is not. Several links to one file give ONE finding that lists every link.
+    for (const group of groupAliasesByTarget(aliasesWithNewType(files, aliases, isClaudeTagTarget))) {
+        const claudeTag = claudeXmlTagIssue(group);
+        if (claudeTag)
+            issues.push(claudeTag);
     }
     return issues;
 }