@promptci/core 0.0.1

package/dist/agent-practices.js

@@ -0,0 +1,582 @@
+/**
+ * Agent-practices detector for PromptCI.
+ *
+ * Checks whether instruction files include key behavioral guidelines that
+ * reduce hallucination, silent failure, and scope creep in AI agents.
+ * Each check scans the combined content of ALL instruction files — guidance
+ * can legitimately live in any file, so we don't require it to be in a
+ * specific one.
+ *
+ * Checks:
+ *   - Verification loop     — "run lint/tests before saying done"
+ *   - Honesty policy        — "report failures, don't fake success"
+ *   - Read-before-edit      — "read a file before editing it"
+ *   - Scope control         — "prefer focused diffs, don't rewrite unrelated code"
+ *   - Plan-first guidance   — "outline the approach before coding"
+ *   - No contradictory "do not edit" header in human-maintained files
+ *
+ * All findings are info/warning severity — these are guidance gaps, not errors.
+ */
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+const CHECKS = [
+    {
+        id: 'no-verification-loop',
+        title: 'No verification loop instruction',
+        summary: 'No instruction found asking the agent to run lint, typecheck, or tests before marking work complete. ' +
+            'Without this, agents commonly report "done" without validating that changes compile or pass tests.',
+        patterns: [
+            /run\s+(pnpm|npm|yarn)\s+(lint|test|build|typecheck)/i,
+            // AP1: a bare command mention ("pnpm build outputs to dist/") describes
+            // WHAT the command does, not an instruction to run it before finishing —
+            // exclude when immediately followed by a descriptive verb.
+            /pnpm\s+(lint|test|build|typecheck)\b(?!\s+(?:outputs?|generates?|creates?|produces?|writes?|emits?|runs?)\b)/i,
+            // AP1: `\b` prevents "npm" from matching as a substring of "pnpm" —
+            // "pnpm build outputs to dist/" would otherwise vacuously satisfy this
+            // pattern via the embedded "npm build" substring.
+            /\bnpm\s+(run\s+)?(lint|test|build)/i,
+            /before\s+(you\s+)?(say|mark|call|consider|report)\s+(it\s+)?(done|complete|finished)/i,
+            /before\s+(finishing|completing|submitting|pushing|closing)/i,
+            /work\s+is\s+not\s+complete\s+until/i,
+        ],
+        recommendation: 'Add an explicit rule such as: "Before saying done, run pnpm lint && pnpm typecheck && pnpm test && pnpm build. ' +
+            'Work is not complete until all checks pass."',
+        severity: 'warning',
+        confidence: 0.75,
+        fixRecipe: 'Before saying work is complete, run pnpm lint, pnpm typecheck, pnpm test, and pnpm build. If any command fails, report the failure and stop.',
+    },
+    {
+        id: 'no-honesty-policy',
+        title: 'No "report failures honestly" instruction',
+        summary: 'No instruction found requiring the agent to report test failures, errors, or build breakage honestly. ' +
+            'Without this, agents may claim success when commands actually fail.',
+        patterns: [
+            /report\s+(the\s+)?(fail|error|break)/i,
+            /don.?t\s+(fake|claim|pretend)\s+success/i,
+            // AP1: word-boundary + exclude the common filler idiom "to be honest,
+            // ..." (a conversational hedge, not a directive about reporting truth),
+            // and no longer accidentally matches inside "dishonestly".
+            /(?<!to\s+be\s+)\bhonestly?\b/i,
+            /if\s+(a\s+)?(test|build|check)s?\s+(fail|break|error)/i,
+            /never\s+skip\s+(failing\s+)?test/i,
+            /never\s+hide\s+(error|fail)/i,
+        ],
+        recommendation: 'Add a rule such as: "If tests fail, report the failure. Never claim success when commands error or tests are skipped."',
+        severity: 'info',
+        confidence: 0.7,
+        fixRecipe: 'If tests or commands fail, report the failure honestly. Never claim success when checks are skipped or error.',
+    },
+    {
+        id: 'no-read-before-edit',
+        title: 'No "read before edit" instruction',
+        summary: "No instruction found requiring the agent to read a file before editing it. " +
+            "Agents that edit files they haven't read may clobber context or introduce inconsistencies.",
+        patterns: [
+            /read\s+(the\s+|a\s+|any\s+)?file\s+(fully\s+|first\s+)?before\s+(edit|modif|chang)/i,
+            /read\s+(the\s+|a\s+)?file.*before\s+(edit|modif|chang)/i,
+            /must\s+(first\s+)?read\s+(the\s+|a\s+|any\s+)?(file|source|code)/i,
+            /always\s+read\s+(the\s+|a\s+)?(file|source|code)/i,
+            /inspect\s+(the\s+|a\s+)?file\s+before/i,
+            /read.*before.*edit/i,
+            // AP5: reversed word order — "Before editing, read the relevant files."
+            // The rule reads before/edit FIRST and "read" second, so the read.*edit
+            // patterns above never matched this common phrasing.
+            /before\s+(?:you\s+)?(?:edit|modif|chang)\w*\b[^.\n]{0,40}\bread(?:ing)?\b/i,
+        ],
+        recommendation: 'Add a rule such as: "Always read a file fully before editing it."',
+        severity: 'info',
+        confidence: 0.7,
+        fixRecipe: 'Read a file before editing it. Preserve unrelated user changes.',
+    },
+    {
+        id: 'no-scope-control',
+        title: 'No scope-control instruction',
+        summary: 'No instruction found telling the agent to avoid rewriting unrelated systems or making sweeping changes. ' +
+            'Unconstrained agents often refactor things they were not asked to touch.',
+        patterns: [
+            /focused\s+(diff|change|edit|pr|commit)/i,
+            /don.?t\s+rewrite\s+unrelated/i,
+            /do\s+not\s+rewrite\s+unrelated/i,
+            /avoid\s+unrelated\s+(change|edit|refactor)/i,
+            /minimal\s+(change|diff|edit)/i,
+            /small\s+(change|diff|edit|pr|commit)/i,
+            /targeted\s+(change|edit|fix)/i,
+            /prefer\s+(small|focused|minimal)\s+(diff|change|pr)/i,
+        ],
+        recommendation: 'Add a rule such as: "Prefer focused, minimal diffs. Do not rewrite or refactor code unrelated to the current task."',
+        severity: 'info',
+        confidence: 0.65,
+        fixRecipe: 'Prefer focused, minimal diffs. Do not rewrite or refactor code unrelated to the current task.',
+    },
+    {
+        id: 'no-plan-first',
+        title: 'No "plan before implementing" instruction',
+        summary: 'No instruction found asking the agent to outline an approach for complex tasks before writing code. ' +
+            'Planning prompts significantly reduce wasted implementation effort on multi-file changes.',
+        patterns: [
+            /plan\s+(first|before|ahead)/i,
+            /outline\s+(the\s+)?(approach|plan|design|steps)\s+before/i,
+            /think\s+(?:through|it\s+through)\s+(?:the\s+)?(?:approach|plan|design|steps|task|problem)/i,
+            /propose\s+(a\s+)?(plan|approach|design)/i,
+            /before\s+implement\w+.*\b(plan|outline|design)\b/i,
+            /design\s+before\s+(implement|cod)/i,
+        ],
+        recommendation: 'Add a rule such as: "For complex or multi-file tasks, outline the approach and get confirmation before writing code."',
+        severity: 'info',
+        confidence: 0.65,
+        fixRecipe: 'For complex or multi-file tasks, outline the approach and get confirmation before writing code.',
+    },
+];
+// ── Do-not-edit header check ──────────────────────────────────────────────────
+// BUG-007: Broadened to match "DO NOT EDIT" anywhere in a line (not just at line
+// start) so "<!-- AUTO-GENERATED — DO NOT EDIT MANUALLY -->" is caught.
+const DO_NOT_EDIT_RE = /\bdo\s+not\s+(edit|modify|change)\b/im;
+// BUG-H1: Also explicitly match HTML-comment auto-generated headers:
+//   <!-- AUTO-GENERATED — DO NOT EDIT -->
+//   <!-- auto-generated -->
+// The existing DO_NOT_EDIT_RE handles "DO NOT EDIT" inside comments, but the
+// auto-generated marker alone (without "DO NOT EDIT" text) was not matched.
+const AUTO_GENERATED_RE = /<!--\s*auto[- ]?generated|auto[- ]?generated|<!--\s*generated\s*(?:by\s+\w+)?|this\s+file\s+is\s+generated|generated\s+by\s+\w+/i;
+/**
+ * BUG-003 / BUG-K1: Detect Claude-specific XML tags/blocks embedded in non-Claude
+ * instruction files.
+ *
+ * Covers:
+ *   1. <claude:thinking> / <claude:…> — namespaced XML (Claude 3 tool-use format)
+ *   2. </claude:thinking> — closing tags of the same form
+ *   3. <instructions-for-claude> — outer wrapper block format
+ *
+ * All forms are only meaningful to Claude; other tools treat them as literal text.
+ *
+ * BUG-K1: Broadened from `/<claude:[a-z]/` to `/<\/?claude:[\w-]+/` to reliably
+ * catch all `<claude:*>` namespace variants regardless of tag-name length or case.
+ */
+const CLAUDE_XML_TAG_RE = /<\/?claude:[\w-]+|<instructions-for-claude[\s>]/i;
+// AP6: a forwarding pointer only counts when it delegates to a *canonical
+// instruction file* (AGENTS.md / CLAUDE.md), so a stub can defer its behavioral
+// rules there. The target is restricted to those filenames (with an optional
+// `./` or `.github/` prefix and surrounding backtick/quote) — a pointer to an
+// arbitrary doc like `CONTRIBUTING.md` is NOT a behavioral-guidance delegation
+// 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;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function issueId(checkId) {
+    const hash = crypto.createHash('sha1').update(checkId).digest('hex').slice(0, 12);
+    return `agent-practice-${hash}`;
+}
+function doNotEditIssueId(filePath) {
+    const hash = crypto.createHash('sha1').update(`do-not-edit:${filePath}`).digest('hex').slice(0, 12);
+    return `do-not-edit-${hash}`;
+}
+function perFileBehaviorIssueId(filePath) {
+    const hash = crypto.createHash('sha1').update(`per-file-behavior:${filePath}`).digest('hex').slice(0, 12);
+    return `per-file-behavior-${hash}`;
+}
+/**
+ * B1: canonical-owner.ts independently derives an id via the exact same
+ * `behavior-duplication:${filePath}` hash input for a conceptually similar
+ * (but distinct) finding — the two detectors collide on id for the same
+ * file. Namespacing the hash input per-detector keeps the ids distinct even
+ * for the same file path; the public id PREFIX is unchanged so existing
+ * baselines/tooling that pattern-match on `behavior-duplication-` still work.
+ */
+function matchesAny(text, patterns) {
+    return patterns.some((p) => p.test(text));
+}
+/** AP2: 1-indexed line number containing character offset `index` in `content`. */
+function lineNumberAtOffset(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i++) {
+        if (content[i] === '\n')
+            line++;
+    }
+    return line;
+}
+/**
+ * BUG-002: Strip human-facing checklist items from content before running
+ * agent-practice pattern checks.
+ *
+ * Lines like "- [ ] Run pnpm test" or "* [ ] npm run build" are PR / human
+ * checklists, not agent behavioral rules. Matching them causes the
+ * verification-loop check to incorrectly conclude the rule is present.
+ *
+ * Strips lines that:
+ *   - start with optional whitespace + list marker (-, *, +, or digit.)
+ *   - followed by a GitHub-style checkbox `[ ]` or `[x]`
+ */
+function stripChecklistLines(content) {
+    return content
+        .split('\n')
+        .filter((line) => !/^\s*(?:[-*+]|\d+\.)\s+/.test(line) || !/\[[ x?]\]/.test(line))
+        .join('\n');
+}
+function stripCodeBlocks(content) {
+    const lines = content.split('\n');
+    const kept = [];
+    let inBlock = false;
+    let fenceChar = null;
+    let fenceLen = 0;
+    for (const line of lines) {
+        if (!inBlock) {
+            const openMatch = /^ {0,3}([`~]{3,})/.exec(line);
+            if (openMatch) {
+                inBlock = true;
+                fenceChar = openMatch[1][0] ?? null;
+                fenceLen = openMatch[1].length;
+                continue;
+            }
+            kept.push(line);
+        }
+        else {
+            const closeMatch = /^ {0,3}([`~]{3,})\s*$/.exec(line);
+            if (closeMatch && closeMatch[1][0] === fenceChar && closeMatch[1].length >= fenceLen) {
+                inBlock = false;
+                fenceChar = null;
+                fenceLen = 0;
+            }
+        }
+    }
+    return kept.join('\n');
+}
+function normalizedFilePath(filePath) {
+    return filePath.replace(/\\/g, '/').toLowerCase();
+}
+function isCopilotInstructionsFile(file) {
+    const normalizedPath = normalizedFilePath(file.path);
+    return (file.fileType === 'copilot' ||
+        normalizedPath === '.github/copilot-instructions.md' ||
+        normalizedPath.endsWith('/.github/copilot-instructions.md') ||
+        normalizedPath.includes('/.github/instructions/'));
+}
+function isCursorRulesFile(file) {
+    const normalizedPath = normalizedFilePath(file.path);
+    const baseName = path.basename(file.path).toLowerCase();
+    return (file.fileType === 'cursor' ||
+        baseName === '.cursorrules' ||
+        normalizedPath.includes('/.cursor/rules/'));
+}
+function isClaudeInstructionsFile(file) {
+    const normalizedPath = normalizedFilePath(file.path);
+    const baseName = path.basename(file.path).toLowerCase();
+    return (file.fileType === 'claude' ||
+        baseName === 'claude.md' ||
+        normalizedPath.includes('/.claude/'));
+}
+function perFileBehaviorTarget(file) {
+    if (isCursorRulesFile(file)) {
+        return { label: 'Cursor rules file', agent: 'Cursor agents' };
+    }
+    if (isClaudeInstructionsFile(file)) {
+        return { label: 'CLAUDE.md', agent: 'Claude' };
+    }
+    if (isCopilotInstructionsFile(file)) {
+        return { label: '.github/copilot-instructions.md', agent: 'GitHub Copilot' };
+    }
+    return undefined;
+}
+function isForwardingFile(file) {
+    // AP6: A header forwarding pointer near the top ("Follow AGENTS.md for the
+    // canonical instructions") delegates behavioral rules to the canonical file
+    // regardless of the stub's total length — this is the exact remedy the
+    // per-check gap findings recommend, so a file that already does it should not
+    // be flagged for "missing" guidance it forwards to.
+    const head = file.content.split(/\r?\n/).slice(0, 12).join('\n');
+    if (FORWARDING_RE.test(head))
+        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) {
+    if (files.length === 0)
+        return [];
+    const issues = [];
+    const combinedContent = files.map((f) => f.content).join('\n');
+    // BUG-002: For the verification-loop check, strip human-facing checklist items
+    // (lines like "- [ ] Run pnpm test") so that a PR checklist doesn't satisfy the
+    // requirement for an agent behavioral directive.
+    const combinedContentNoChecklists = stripChecklistLines(combinedContent);
+    const allFilePaths = files.map((f) => f.path);
+    // ── Per-practice checks (scan combined content) ───────────────────────────
+    for (const check of CHECKS) {
+        // BUG-002: Verification loop requires an imperative agent directive, not a checklist item.
+        const contentToSearch = check.id === 'no-verification-loop'
+            ? combinedContentNoChecklists
+            : combinedContent;
+        if (matchesAny(contentToSearch, check.patterns))
+            continue;
+        issues.push({
+            id: issueId(check.id),
+            severity: check.severity,
+            category: 'agent_practices',
+            title: check.title,
+            summary: check.summary,
+            filePaths: allFilePaths,
+            locations: [],
+            evidence: [`Pattern not found across ${files.length} instruction file(s).`],
+            recommendation: check.recommendation,
+            fixRecipe: check.fixRecipe,
+            confidence: check.confidence,
+        });
+    }
+    // ── Per-file behavioral gap check for tool-specific files ──────────────────
+    // Tool-specific files must stand alone. If CLAUDE.md has no behavioral rules
+    // while AGENTS.md has them, combined-content checks pass but Claude still lacks
+    // those instructions. Fires only when ALL key behavioral patterns are absent
+    // from the tool-specific file and present in at least one other file.
+    const KEY_BEHAVIORAL_PATTERNS = [
+        ...CHECKS.find((c) => c.id === 'no-verification-loop').patterns,
+        ...CHECKS.find((c) => c.id === 'no-honesty-policy').patterns,
+        ...CHECKS.find((c) => c.id === 'no-scope-control').patterns,
+        ...CHECKS.find((c) => c.id === 'no-read-before-edit').patterns,
+    ];
+    const hasBehavioralGuidance = (file) => matchesAny(stripChecklistLines(file.content), KEY_BEHAVIORAL_PATTERNS);
+    // AP4: files that already get the coarse "no behavioral guidance at all"
+    // finding below. The per-check loop further down skips these — without
+    // this, a file missing ALL guidance got the coarse warning PLUS up to 5
+    // 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) {
+        const target = perFileBehaviorTarget(file);
+        if (!target)
+            continue;
+        if (hasBehavioralGuidance(file)) {
+            // ── Duplication vs Forwarding Check ────────────────────────────────────
+            continue;
+        }
+        // It lacks behavioral guidance. Is it a forwarding file?
+        if (isForwardingFile(file))
+            continue;
+        // At least one OTHER file must have behavioral guidance — otherwise the
+        // combined-content check already fires and we'd be duplicating the finding.
+        const fileWithGuidance = files.find((f) => f !== file && hasBehavioralGuidance(f));
+        if (!fileWithGuidance)
+            continue;
+        filesWithNoGuidanceFinding.add(file.path);
+        issues.push({
+            id: perFileBehaviorIssueId(file.path),
+            severity: 'warning',
+            category: 'agent_practices',
+            title: `No behavioral guidance in ${target.label}`,
+            summary: `The ${target.label} contains no agent behavioral rules (verification loop, honesty policy, ` +
+                `scope control, read-before-edit). ${target.agent} may rely on this file, so they will have no behavioral ` +
+                `guidance even though another instruction file in the repo contains related rules.`,
+            filePaths: [file.path],
+            locations: [{ filePath: file.path }],
+            evidence: [
+                `No behavioral patterns found in ${path.basename(file.path)}.`,
+                `Some behavioral guidance appears in ${path.basename(fileWithGuidance.path)}.`,
+            ],
+            recommendation: `Add at minimum: a verification rule ("run tests before saying done"), a scope-control rule ` +
+                `("prefer focused diffs"), a read-before-edit rule, and an honesty policy directly to ` +
+                `${target.label} so behavioral guidance is available in the file this tool reads. ` +
+                `Alternatively, use a forwarding pointer if the tool supports it (e.g., "Follow AGENTS.md").`,
+            confidence: 0.8,
+        });
+    }
+    // ── Specific guidance cross-file gap check ──────────────────────────────────
+    // For each check in CHECKS, if the guidance exists in some file (like AGENTS.md),
+    // but is missing in a tool-specific file (which is not a forwarding file),
+    // emit a warning.
+    for (const check of CHECKS) {
+        const sourceFile = files.find((f) => matchesAny(stripChecklistLines(f.content), check.patterns));
+        if (!sourceFile)
+            continue;
+        for (const file of files) {
+            if (file === sourceFile)
+                continue;
+            const target = perFileBehaviorTarget(file);
+            if (!target)
+                continue;
+            if (isForwardingFile(file))
+                continue;
+            // AP4: already covered by the coarser "no behavioral guidance at all"
+            // finding above — don't also pile on a granular per-check issue.
+            if (filesWithNoGuidanceFinding.has(file.path))
+                continue;
+            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);
+                issues.push({
+                    id: `per-file-behavioral-gap-${hash}`,
+                    severity: 'warning',
+                    category: 'agent_practices',
+                    title: `Missing critical guidance "${check.title.replace('No ', '').replace(' instruction', '')}" in ${target.label}`,
+                    summary: `The ${target.label} lacks the critical behavioral guidance regarding "${checkName}" ` +
+                        `which is defined in ${path.basename(sourceFile.path)}. Since ${target.agent} reads ${target.label}, ` +
+                        `they will miss this rule.`,
+                    filePaths: [file.path, sourceFile.path],
+                    locations: [{ filePath: file.path }],
+                    evidence: [
+                        `Guidance pattern not found in ${path.basename(file.path)}.`,
+                        `Guidance defined in ${path.basename(sourceFile.path)}.`,
+                    ],
+                    recommendation: `Add the missing guidance to ${target.label} (e.g., "${check.recommendation.replace('Add a rule such as: ', '').replace(/"/g, '')}") ` +
+                        `or use a forwarding pointer (e.g., "Follow ${path.basename(sourceFile.path)}").`,
+                    fixRecipe: check.fixRecipe,
+                    confidence: 0.8,
+                });
+            }
+        }
+    }
+    // ── BUG-007: Agent-behavior section in copilot-instructions.md ──────────────
+    // Copilot-instructions.md is scoped to GitHub Copilot. When it contains a
+    // section heading like "## Agent Behavior" or "## Behavior Rules", the author
+    // likely intended it as an AGENTS.md-style file and mis-placed it. Flag this
+    // so the content can be moved or the structure clarified.
+    //
+    // Only fires when the section ALSO contains at least one agent-practice pattern —
+    // a heading alone could be a coincidence ("Behavior" in a broader context).
+    const AGENT_BEHAVIOR_HEADING_RE = /^#{1,4}\s+(?:agent\s+behavior|ai\s+behavior|agent\s+rules|behavior\s+rules|agent\s+instructions)\b/im;
+    const copilotAgentBehaviorId = (p) => {
+        const h = crypto.createHash('sha1').update(`copilot-agent-behavior:${p}`).digest('hex').slice(0, 12);
+        return `copilot-agent-behavior-${h}`;
+    };
+    const hasGeneralBehaviorOnlyInCopilot = () => {
+        const copilotFiles = files.filter(isCopilotInstructionsFile);
+        if (copilotFiles.length === 0)
+            return false;
+        const hasGuidanceInCopilot = copilotFiles.some(hasBehavioralGuidance);
+        if (!hasGuidanceInCopilot)
+            return false;
+        const otherFiles = files.filter(f => !isCopilotInstructionsFile(f) && f.fileType !== 'readme' && f.fileType !== 'docs');
+        return !otherFiles.some(hasBehavioralGuidance);
+    };
+    if (hasGeneralBehaviorOnlyInCopilot()) {
+        const copilotFile = files.find(isCopilotInstructionsFile);
+        issues.push({
+            id: copilotAgentBehaviorId(copilotFile.path),
+            severity: 'warning',
+            category: 'structure',
+            title: 'General behavioral guidance placed only in Copilot instructions',
+            summary: 'General agent behavioral rules (verification loop, honesty policy, etc.) appear only in ' +
+                'Copilot-specific instruction files. Other agents (Claude, Cursor, etc.) will likely ' +
+                'not see these rules.',
+            filePaths: [copilotFile.path],
+            locations: [{ filePath: copilotFile.path }],
+            evidence: ['Behavioral directives found only in Copilot-specific files.'],
+            recommendation: 'Move general agent behavior rules to AGENTS.md or CLAUDE.md so all agents benefit. ' +
+                'Keep copilot-instructions.md focused on Copilot-specific context.',
+            confidence: 0.7,
+        });
+    }
+    for (const file of files) {
+        if (file.fileType !== 'copilot')
+            continue;
+        if (!AGENT_BEHAVIOR_HEADING_RE.test(file.content))
+            continue;
+        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)))
+            continue;
+        issues.push({
+            id: copilotAgentBehaviorId(file.path),
+            severity: 'warning',
+            category: 'structure',
+            title: 'Agent-behavior section in copilot-instructions.md',
+            summary: 'copilot-instructions.md contains an "Agent Behavior" (or similar) heading with ' +
+                'agent-practice directives. This file is scoped to GitHub Copilot; agent behavioral ' +
+                'rules are typically placed in AGENTS.md or CLAUDE.md where all agents can read them.',
+            filePaths: [file.path],
+            locations: [{ filePath: file.path }],
+            evidence: ['Agent behavioral directives found inside a Copilot-specific instruction file.'],
+            recommendation: 'Move agent behavior rules to AGENTS.md or CLAUDE.md, or copy them there so all agents ' +
+                'benefit. Keep copilot-instructions.md focused on Copilot-specific context (repo structure, ' +
+                'technology stack, Copilot feature preferences).',
+            confidence: 0.65,
+        });
+    }
+    // ── "Do not edit" in human-maintained files ───────────────────────────────
+    // Flag instruction files that contain a "do not edit" / "auto-generated"
+    // header but are clearly human-maintained (no generator comment nearby).
+    for (const file of files) {
+        const first500 = file.content.slice(0, 500);
+        const doNotEditMatch = DO_NOT_EDIT_RE.exec(first500);
+        const hasDoNotEdit = !!doNotEditMatch;
+        const hasGeneratorNote = AUTO_GENERATED_RE.test(first500);
+        // AP2: DO_NOT_EDIT_RE searches the first 500 chars of the file, not just
+        // the first line — a header on line 8 was previously always reported at
+        // the hardcoded lines 1-3. Compute the REAL line the match landed on.
+        const doNotEditLine = doNotEditMatch ? lineNumberAtOffset(file.content, doNotEditMatch.index) : 1;
+        if (hasDoNotEdit && !hasGeneratorNote) {
+            // Case 1 (original): "do not edit" present but NO generator note.
+            issues.push({
+                id: doNotEditIssueId(file.path),
+                severity: 'warning',
+                category: 'agent_practices',
+                title: '"Do not edit" header in human-maintained instruction file',
+                summary: `This instruction file starts with a "do not edit" directive but does not appear to be auto-generated. ` +
+                    `Humans and agents need to update instruction files regularly — this header may prevent necessary edits.`,
+                filePaths: [file.path],
+                locations: [{ filePath: file.path, startLine: doNotEditLine, endLine: doNotEditLine }],
+                evidence: [doNotEditMatch[0].trim()],
+                recommendation: 'Remove the "do not edit" header, or add a clear generator comment explaining which tool generates this file.',
+                confidence: 0.8,
+            });
+        }
+        else if (hasDoNotEdit && hasGeneratorNote && file.lineCount > 5) {
+            // BUG-007 / BUG-H1: File claims to be AUTO-GENERATED + DO-NOT-EDIT, but is clearly
+            // long enough to be human-maintained (runbooks, conventions, etc.).
+            // Threshold lowered from 20 → 5 lines: even short instruction files (e.g. a brief
+            // QA.md) are human-maintained and should not carry a misleading auto-gen header.
+            const autoGenId = (p) => {
+                const hash = crypto.createHash('sha1').update(`auto-gen-header:${p}`).digest('hex').slice(0, 12);
+                return `auto-gen-header-${hash}`;
+            };
+            issues.push({
+                id: autoGenId(file.path),
+                severity: 'warning',
+                category: 'agent_practices',
+                title: 'Misleading auto-generated header on human-maintained instruction file',
+                summary: `This instruction file has an "AUTO-GENERATED — DO NOT EDIT" header, but with ${file.lineCount} lines ` +
+                    `of hand-written content it is clearly human-maintained. The header may prevent agents and humans ` +
+                    `from updating the file when needed.`,
+                filePaths: [file.path],
+                locations: [{ filePath: file.path, startLine: doNotEditLine, endLine: doNotEditLine }],
+                evidence: [doNotEditMatch[0].trim()],
+                recommendation: 'Remove the auto-generated header. If this file is genuinely generated, add a clear generator ' +
+                    'comment that names the tool and the source template so the origin is unambiguous.',
+                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,
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=agent-practices.js.map

package/dist/agent-practices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-practices.js","sourceRoot":"","sources":["../src/agent-practices.ts"],"names":[],"mappings":"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"}

package/dist/baseline.d.ts

@@ -0,0 +1,40 @@
+import type { PromptCiIssue, Baseline } from './types.js';
+/**
+ * Computes a stable fingerprint for an issue.
+ *
+ * Excluded from fingerprint:
+ *  - `id` (may change between versions)
+ *  - `severity` (tracked separately for worsening detection)
+ *  - `locations` / line numbers (unstable across minor file edits)
+ *  - `confidence` (heuristic, may fluctuate)
+ *
+ * Included:
+ *  - `category`, `title`, sorted `filePaths`, sorted `evidence`
+ */
+export declare function computeFingerprint(issue: PromptCiIssue, repoRoot?: string): string;
+/**
+ * Creates a baseline from a list of active issues.
+ * Produces deterministic JSON when sorted by fingerprint.
+ */
+export declare function createBaseline(issues: PromptCiIssue[], repoRoot?: string): Baseline;
+/**
+ * Type-guard that asserts a parsed JSON value is a valid Baseline array.
+ * Throws a descriptive error if the shape is unexpected.
+ */
+export declare function assertValidBaseline(value: unknown): asserts value is Baseline;
+/**
+ * Partitions a list of active issues into new and baselined issues.
+ *
+ * An issue is considered NEW (not baselined) if:
+ *  - Its fingerprint is not in the baseline, OR
+ *  - Its fingerprint IS in the baseline but its severity has worsened
+ *    (e.g. was `warning`, now `high`).
+ *
+ * Issues with the same fingerprint and equal-or-lesser severity are
+ * considered baselined (pre-existing) and do not fail `--fail-on-new` CI.
+ */
+export declare function filterNewIssues(issues: PromptCiIssue[], baseline: Baseline, repoRoot?: string): {
+    newIssues: PromptCiIssue[];
+    baselinedIssues: PromptCiIssue[];
+};
+//# sourceMappingURL=baseline.d.ts.map