@event4u/agent-config 8.10.0 → 8.12.0

package/src/scripts/knowledge_global_cli.ts

@@ -34,6 +34,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -71,7 +72,7 @@ function _list_cards(): string[] {
     return _globMdSorted(store).filter((p) => path.basename(p).toLowerCase() !== 'readme.md');
 }
 
-function _freshness_state(text: string, cfg: SettingsDict): string {
+export function _freshness_state(text: string, cfg: SettingsDict): string {
     const fresh = _isPlainObject(cfg['freshness']) ? (cfg['freshness'] as SettingsDict) : {};
     const hyp = _pyInt(fresh['hypothesis_after_days'], 90);
     const stale = _pyInt(fresh['stale_after_days'], 180);
@@ -105,10 +106,13 @@ function _disabled_notice(): number {
 // Subcommands
 // ---------------------------------------------------------------------------
 
-function cmd_list(args: { json: boolean }): number {
+function cmd_list(args: { json: boolean; revoked: boolean }): number {
     if (!kg.is_enabled()) {
         return _disabled_notice();
     }
+    if (args.revoked) {
+        return _list_revoked(args.json);
+    }
     const cfg = kg.load_global_sharing_config();
     const cards = _list_cards();
     const rows: Record<string, string>[] = [];
@@ -142,6 +146,24 @@ function cmd_list(args: { json: boolean }): number {
     return 0;
 }
 
+/** Render the revocation ledger (`list --revoked`) — table or `--json`. */
+function _list_revoked(json: boolean): number {
+    const trail = kgp.load_tombstones();
+    if (json) {
+        process.stdout.write(kg.pyJsonDumps(trail, 2, true) + '\n');
+        return 0;
+    }
+    if (trail.length === 0) {
+        process.stdout.write(`No revocations recorded in ${kg.global_store_dir()}.\n`);
+        return 0;
+    }
+    process.stdout.write(`${_ljust('REVOKED-AT', 12)} ${_ljust('CARD', 28)} REASON\n`);
+    for (const t of trail) {
+        process.stdout.write(`${_ljust(t.revoked_at, 12)} ${_ljust(t.card_id, 28)} ${t.reason}\n`);
+    }
+    return 0;
+}
+
 function cmd_show(args: { card: string }): number {
     if (!kg.is_enabled()) {
         return _disabled_notice();
@@ -185,37 +207,45 @@ function cmd_trace(args: { card: string; json: boolean }): number {
     return 0;
 }
 
-function _forget_one(card: string): boolean {
+/**
+ * Remove one global card + its usage entry. Writes an append-only tombstone
+ * to the revocation ledger BEFORE deleting anything — no silent deletes.
+ */
+function _forget_one(card: string, reason: string): boolean {
     const p = _card_path(card);
-    let removed = false;
-    if (fs.existsSync(p)) {
-        fs.unlinkSync(p);
-        removed = true;
-    }
     const cid = kgp.card_id_from({ card_name: card });
     const usage = kgp.load_usage();
     const cards = usage['cards'] as SettingsDict;
-    if (cid in cards) {
+    const has_card = fs.existsSync(p);
+    const has_usage = cid in cards;
+    if (!has_card && !has_usage) {
+        return false;
+    }
+    kgp.append_tombstone(cid, reason, { today: _today() });
+    if (has_card) {
+        fs.unlinkSync(p);
+    }
+    if (has_usage) {
         delete cards[cid];
         write_atomic(
             path.join(kg.global_store_dir(null, { create: true }), kgp.USAGE_FILENAME),
             kg.pyJsonDumps(usage, 2, true) + '\n',
         );
-        removed = true;
     }
-    return removed;
+    return true;
 }
 
-function cmd_forget(args: { card: string; tier: string }): number {
+function cmd_forget(args: { card: string; tier: string; reason: string }): number {
     if (!kg.is_enabled()) {
         return _disabled_notice();
     }
     if (args.tier) {
+        const reason = args.reason || `bulk forget (tier=${args.tier})`;
         let removed = 0;
         for (const p of _list_cards()) {
             const prov = kg.parse_provenance_footer(_readReplace(p));
             if (prov['tier'] === args.tier) {
-                if (_forget_one(_stem(p))) {
+                if (_forget_one(_stem(p), reason)) {
                     removed += 1;
                 }
             }
@@ -228,7 +258,7 @@ function cmd_forget(args: { card: string; tier: string }): number {
         process.exitCode = 1;
         return 1;
     }
-    if (_forget_one(args.card)) {
+    if (_forget_one(args.card, args.reason || 'manual forget')) {
         process.stdout.write(`Forgot global card '${args.card}'.\n`);
         return 0;
     }
@@ -237,7 +267,16 @@ function cmd_forget(args: { card: string; tier: string }): number {
     return 1;
 }
 
-function cmd_promote(args: { path: string; source: string; tier: string; manual: boolean }): number {
+function cmd_promote(args: {
+    path: string;
+    source: string;
+    tier: string;
+    manual: boolean;
+    sensitivity: string;
+    reason: string;
+    owner: string;
+    review_after: string;
+}): number {
     if (!kg.is_enabled()) {
         return _disabled_notice();
     }
@@ -258,13 +297,20 @@ function cmd_promote(args: { path: string; source: string; tier: string; manual:
     const allowed = [...kg.allowed_tiers()];
 
     const redaction = _isPlainObject(cfg['redaction']) ? (cfg['redaction'] as SettingsDict) : {};
+    const redaction_enabled = _pyBool(redaction['enabled'], true);
+    const halt_on_trigger = _pyBool(redaction['halt_on_trigger'], true);
+    // Computed once — feeds BOTH the existing tier gate below AND the new
+    // sensitivity auto-derivation, independent of `halt_on_trigger` (a
+    // `prohibited` override never depends on that unrelated config flag).
+    const violations = redaction_enabled ? kgr.redaction_scan(text) : [];
+
     const result = kgr.gate_card_for_global(text, {
         tier,
         source: args.source,
         card_name: path.basename(src_path),
         allowed_tiers: allowed,
-        redaction_enabled: _pyBool(redaction['enabled'], true),
-        halt_on_trigger: _pyBool(redaction['halt_on_trigger'], true),
+        redaction_enabled,
+        halt_on_trigger,
     });
     if (!result.eligible) {
         if (result.manual_only && !args.manual) {
@@ -282,8 +328,7 @@ function cmd_promote(args: { path: string; source: string; tier: string; manual:
             return 2;
         }
         // manual override of proprietary: still run redaction, never skip it.
-        const violations = kgr.redaction_scan(text);
-        if (violations.length > 0 && _pyBool(redaction['halt_on_trigger'], true)) {
+        if (violations.length > 0 && halt_on_trigger) {
             process.stderr.write(
                 'global-share BLOCKED (manual proprietary): redaction halt — ' +
                     violations.map((v) => `${v.category}: ${_pyRepr(v.snippet)}`).join('; ') +
@@ -294,6 +339,19 @@ function cmd_promote(args: { path: string; source: string; tier: string; manual:
         }
     }
 
+    // Sensitivity gate — layered ON TOP of the tier/redaction gate above.
+    const declared_sensitivity =
+        args.sensitivity || _frontmatter_sensitivity(text) || kg.DEFAULT_SENSITIVITY;
+    const sens = kgp.gate_sensitivity_for_promotion(declared_sensitivity, {
+        violations_present: violations.length > 0,
+        promotion_reason: args.reason,
+    });
+    if (!sens.eligible) {
+        process.stderr.write(`global-share BLOCKED: ${sens.reason}\n`);
+        process.exitCode = 2;
+        return 2;
+    }
+
     // Build provenance + usage.
     const cid = kgp.card_id_from({ card_name: path.basename(src_path), source: args.source });
     const slug = kgp.repo_slug();
@@ -306,6 +364,11 @@ function cmd_promote(args: { path: string; source: string; tier: string; manual:
         ? (entry['first_seen'] as SettingsDict)
         : { repo: slug, date: today };
 
+    const fresh = _isPlainObject(cfg['freshness']) ? (cfg['freshness'] as SettingsDict) : {};
+    const review_after =
+        args.review_after || _addDaysIso(today, _pyInt(fresh['stale_after_days'], 180));
+    const owner = args.owner || _defaultOwner();
+
     const footer = kg.render_provenance_footer({
         first_seen_repo: (first['repo'] as string) ?? slug,
         first_seen_date: (first['date'] as string) ?? today,
@@ -313,8 +376,13 @@ function cmd_promote(args: { path: string; source: string; tier: string; manual:
         last_verified: today,
         tier,
         seen_in,
+        source_repo: slug,
+        owner,
+        review_after,
+        promotion_reason: args.reason,
     });
-    let out_text = _ensure_tier_frontmatter(text, tier);
+    let out_text = _ensure_frontmatter_field(text, 'tier', tier);
+    out_text = _ensure_frontmatter_field(out_text, 'sensitivity', sens.sensitivity);
     out_text = _rstrip(kg.strip_provenance_footer(out_text)) + '\n\n' + footer;
     const dest = _card_path(cid);
     write_atomic(path.join(kg.global_store_dir(null, { create: true }), path.basename(dest)), out_text);
@@ -329,11 +397,11 @@ function cmd_promote(args: { path: string; source: string; tier: string; manual:
             kg.pyJsonDumps(usage, 2, true) + '\n',
         );
     }
-    process.stdout.write(`Promoted '${cid}' (tier=${tier}) → ${dest}\n`);
+    process.stdout.write(`Promoted '${cid}' (tier=${tier}, sensitivity=${sens.sensitivity}) → ${dest}\n`);
     return 0;
 }
 
-function cmd_purge(args: { confirm: boolean }): number {
+function cmd_purge(args: { confirm: boolean; reason: string }): number {
     // Remove the global store and strip provenance footers from project cards.
     if (!args.confirm) {
         process.stderr.write(
@@ -345,9 +413,30 @@ function cmd_purge(args: { confirm: boolean }): number {
     }
 
     const store = kg.global_store_dir();
+    const reason = args.reason || 'full store purge';
+    if (fs.existsSync(store)) {
+        // Tombstone every surviving card_id BEFORE deleting anything — no
+        // silent deletes, even on the biggest deletion event this CLI has.
+        const usage = kgp.load_usage();
+        const cards = usage['cards'] as SettingsDict;
+        const seen_ids = new Set<string>();
+        for (const p of _list_cards()) {
+            const cid = _stem(p);
+            seen_ids.add(cid);
+            kgp.append_tombstone(cid, reason, { today: _today() });
+        }
+        for (const cid of Object.keys(cards)) {
+            if (!seen_ids.has(cid)) {
+                kgp.append_tombstone(cid, reason, { today: _today() });
+            }
+        }
+    }
     let removed = 0;
     if (fs.existsSync(store)) {
         for (const p of _globAllSorted(store)) {
+            if (path.basename(p) === kgp.REVOCATIONS_FILENAME) {
+                continue; // the ledger survives its own purge entry — the audit trail persists
+            }
             if (_isFile(p)) {
                 fs.unlinkSync(p);
                 removed += 1;
@@ -356,7 +445,7 @@ function cmd_purge(args: { confirm: boolean }): number {
         try {
             fs.rmdirSync(store);
         } catch {
-            // non-empty (subdirs) — leave it
+            // non-empty (the ledger, or subdirs) — leave it
         }
     }
     process.stdout.write(`Purged global store (${removed} file(s)) at ${store}.\n`);
@@ -511,32 +600,43 @@ function cmd_lead_check(args: { report: string; strict: boolean }): number {
 // ---------------------------------------------------------------------------
 
 function _frontmatter_tier(text: string): string {
+    const val = _frontmatter_scalar(text, 'tier');
+    return kg.TIERS.includes(val) ? val : '';
+}
+
+function _frontmatter_sensitivity(text: string): string {
+    const val = _frontmatter_scalar(text, 'sensitivity');
+    return kg.SENSITIVITIES.includes(val) ? val : '';
+}
+
+/** Read a top-level scalar frontmatter field's raw (quote-stripped) value. */
+function _frontmatter_scalar(text: string, field: string): string {
     const m = _FRONTMATTER_RE.exec(text);
     if (!m) {
         return '';
     }
     for (const line of _splitlines(m[1] as string)) {
         const s = _strip(line);
-        if (s.startsWith('tier:')) {
-            const val = _stripQuotes(_strip(s.slice('tier:'.length)));
-            return kg.TIERS.includes(val) ? val : '';
+        if (s.startsWith(`${field}:`)) {
+            return _stripQuotes(_strip(s.slice(field.length + 1)));
         }
     }
     return '';
 }
 
-function _ensure_tier_frontmatter(text: string, tier: string): string {
-    // Ensure the card frontmatter carries an accurate `tier:` field.
+/** Ensure the card frontmatter carries an accurate `<field>: <value>` line. */
+function _ensure_frontmatter_field(text: string, field: string, value: string): string {
     const m = _FRONTMATTER_RE.exec(text);
     if (!m) {
         return text;
     }
     const block = m[1] as string;
+    const line_re = new RegExp(`^\\s*${field}:.*$`, 'm');
     let new_block: string;
-    if (/^\s*tier:/m.test(block)) {
-        new_block = _reSubFirst(block, /^\s*tier:.*$/m, `tier: ${tier}`);
+    if (line_re.test(block)) {
+        new_block = _reSubFirst(block, line_re, `${field}: ${value}`);
     } else {
-        new_block = `tier: ${tier}\n${block}`;
+        new_block = `${field}: ${value}\n${block}`;
     }
     // m.index of group 1: in Python `m.start(1)` / `m.end(1)`. The full match
     // starts at 0 (anchored `^`); group 1 begins after the leading `---\n`.
@@ -612,20 +712,23 @@ function _wrap<T>(cmd: string, rest: string[], parse: (rest: string[]) => T | nu
 
 // Per-subcommand argparse-faithful parsers.
 
-function _parseList(rest: string[]): { json: boolean } | number {
+function _parseList(rest: string[]): { json: boolean; revoked: boolean } | number {
     let json = false;
-    const usage = `${_PROG} list [-h] [--json]`;
+    let revoked = false;
+    const usage = `${_PROG} list [-h] [--json] [--revoked]`;
     for (const a of rest) {
         if (a === '-h' || a === '--help') {
             return _subHelp(usage);
         }
         if (a === '--json') {
             json = true;
+        } else if (a === '--revoked') {
+            revoked = true;
         } else {
             return _subError('list', `unrecognized arguments: ${a}`, usage);
         }
     }
-    return { json };
+    return { json, revoked };
 }
 
 function _parseShow(rest: string[]): { card: string } | number {
@@ -674,10 +777,11 @@ function _parseTrace(rest: string[]): { card: string; json: boolean } | number {
     return { card, json };
 }
 
-function _parseForget(rest: string[]): { card: string; tier: string } | number {
-    const usage = `${_PROG} forget [-h] [--tier {public,vendor,proprietary}] [card]`;
+function _parseForget(rest: string[]): { card: string; tier: string; reason: string } | number {
+    const usage = `${_PROG} forget [-h] [--tier {public,vendor,proprietary}] [--reason REASON] [card]`;
     let card = '';
     let tier = '';
+    let reason = '';
     let cardSet = false;
     for (let i = 0; i < rest.length; i += 1) {
         const a = rest[i] as string;
@@ -689,6 +793,10 @@ function _parseForget(rest: string[]): { card: string; tier: string } | number {
             tier = choice;
         } else if (a.startsWith('--tier=')) {
             tier = _choiceOrExit(a.slice('--tier='.length), ['public', 'vendor', 'proprietary'], '--tier', 'forget', usage);
+        } else if (a === '--reason') {
+            reason = (rest[++i] ?? '') as string;
+        } else if (a.startsWith('--reason=')) {
+            reason = a.slice('--reason='.length);
         } else if (a.startsWith('-')) {
             return _subError('forget', `unrecognized arguments: ${a}`, usage);
         } else if (!cardSet) {
@@ -698,15 +806,35 @@ function _parseForget(rest: string[]): { card: string; tier: string } | number {
             return _subError('forget', `unrecognized arguments: ${a}`, usage);
         }
     }
-    return { card, tier };
-}
-
-function _parsePromote(rest: string[]): { path: string; source: string; tier: string; manual: boolean } | number {
-    const usage = `${_PROG} promote [-h] [--source SOURCE] [--tier {public,vendor,proprietary}] [--manual] path`;
+    return { card, tier, reason };
+}
+
+function _parsePromote(
+    rest: string[],
+):
+    | {
+          path: string;
+          source: string;
+          tier: string;
+          manual: boolean;
+          sensitivity: string;
+          reason: string;
+          owner: string;
+          review_after: string;
+      }
+    | number {
+    const usage =
+        `${_PROG} promote [-h] [--source SOURCE] [--tier {public,vendor,proprietary}] ` +
+        '[--manual] [--sensitivity {prohibited,project,shareable}] [--reason REASON] ' +
+        '[--owner OWNER] [--review-after DATE] path';
     let p: string | null = null;
     let source = '';
     let tier = '';
     let manual = false;
+    let sensitivity = '';
+    let reason = '';
+    let owner = '';
+    let review_after = '';
     for (let i = 0; i < rest.length; i += 1) {
         const a = rest[i] as string;
         if (a === '-h' || a === '--help') {
@@ -722,6 +850,34 @@ function _parsePromote(rest: string[]): { path: string; source: string; tier: st
             tier = _choiceOrExit(a.slice('--tier='.length), ['public', 'vendor', 'proprietary'], '--tier', 'promote', usage);
         } else if (a === '--manual') {
             manual = true;
+        } else if (a === '--sensitivity') {
+            sensitivity = _choiceOrExit(
+                rest[++i],
+                ['prohibited', 'project', 'shareable'],
+                '--sensitivity',
+                'promote',
+                usage,
+            );
+        } else if (a.startsWith('--sensitivity=')) {
+            sensitivity = _choiceOrExit(
+                a.slice('--sensitivity='.length),
+                ['prohibited', 'project', 'shareable'],
+                '--sensitivity',
+                'promote',
+                usage,
+            );
+        } else if (a === '--reason') {
+            reason = (rest[++i] ?? '') as string;
+        } else if (a.startsWith('--reason=')) {
+            reason = a.slice('--reason='.length);
+        } else if (a === '--owner') {
+            owner = (rest[++i] ?? '') as string;
+        } else if (a.startsWith('--owner=')) {
+            owner = a.slice('--owner='.length);
+        } else if (a === '--review-after') {
+            review_after = (rest[++i] ?? '') as string;
+        } else if (a.startsWith('--review-after=')) {
+            review_after = a.slice('--review-after='.length);
         } else if (a.startsWith('-')) {
             return _subError('promote', `unrecognized arguments: ${a}`, usage);
         } else if (p === null) {
@@ -733,7 +889,7 @@ function _parsePromote(rest: string[]): { path: string; source: string; tier: st
     if (p === null) {
         return _subError('promote', 'the following arguments are required: path', usage);
     }
-    return { path: p, source, tier, manual };
+    return { path: p, source, tier, manual, sensitivity, reason, owner, review_after };
 }
 
 function _parseValidate(rest: string[]): { check_urls: boolean } | number {
@@ -774,20 +930,26 @@ function _parseLeadCheck(rest: string[]): { report: string; strict: boolean } |
     return { report, strict };
 }
 
-function _parsePurge(rest: string[]): { confirm: boolean } | number {
-    const usage = `${_PROG} purge [-h] [--confirm]`;
+function _parsePurge(rest: string[]): { confirm: boolean; reason: string } | number {
+    const usage = `${_PROG} purge [-h] [--confirm] [--reason REASON]`;
     let confirm = false;
-    for (const a of rest) {
+    let reason = '';
+    for (let i = 0; i < rest.length; i += 1) {
+        const a = rest[i] as string;
         if (a === '-h' || a === '--help') {
             return _subHelp(usage);
         }
         if (a === '--confirm') {
             confirm = true;
+        } else if (a === '--reason') {
+            reason = (rest[++i] ?? '') as string;
+        } else if (a.startsWith('--reason=')) {
+            reason = a.slice('--reason='.length);
         } else {
             return _subError('purge', `unrecognized arguments: ${a}`, usage);
         }
     }
-    return { confirm };
+    return { confirm, reason };
 }
 
 function _subHelp(usage: string): number {
@@ -1077,6 +1239,33 @@ function _dateDiffDays(a: YMD, b: YMD): number {
     return Math.round((ta - tb) / 86_400_000);
 }
 
+/** `YYYY-MM-DD` + N days → `YYYY-MM-DD` (UTC). Invalid input → the input unchanged. */
+function _addDaysIso(iso: string, days: number): string {
+    const parsed = _strptime(iso);
+    if (parsed === null) {
+        return iso;
+    }
+    const ms = Date.UTC(parsed.y, parsed.m - 1, parsed.d) + days * 86_400_000;
+    const d = new Date(ms);
+    const y = d.getUTCFullYear();
+    const mo = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(d.getUTCDate()).padStart(2, '0');
+    return `${y}-${mo}-${dd}`;
+}
+
+/** Default `owner` for a promoted card when `--owner` is not given. */
+function _defaultOwner(): string {
+    try {
+        const name = os.userInfo().username;
+        if (name) {
+            return name;
+        }
+    } catch {
+        // platform without a resolvable user (rare) — fall through
+    }
+    return process.env['USER'] ?? process.env['USERNAME'] ?? 'unknown';
+}
+
 /** Mirror Python `OSError`'s `str(exc)` for the read-failure message. */
 function _osErrorStr(exc: unknown): string {
     if (exc && typeof exc === 'object') {

package/src/scripts/lint_framework_leakage.ts

@@ -128,7 +128,7 @@ const LEAKAGE: Record<string, string[]> = {
     ],
     'JS-specific': [
         '\\bpackage\\.json\\b',
-        '\\bnpm (install|run|test|ci)\\b',
+        '\\bnpm (install|run|test|ci|update|audit|exec)\\b',
         '\\byarn (install|add|test)\\b',
         '\\bpnpm (install|add|run|test)\\b',
         '\\bnode_modules\\b',
@@ -147,20 +147,69 @@ const FAMILY: Record<string, string> = {
 const CROSS_STACK_HINTS: Record<string, string[]> = {
     ruby: ['\\bRails\\b', '\\bbin/rails\\b', '\\bGemfile\\b', '\\bbundle exec\\b'],
     python: ['\\bDjango\\b', '\\bFastAPI\\b', '\\bFlask\\b', '\\bpoetry\\b',
-        '\\buv (add|sync|run|pip)\\b', '\\bvenv\\b'],
+        '\\buv (add|sync|run|pip)\\b', '\\bvenv\\b', '\\bPydantic\\b', '\\bJinja\\b',
+        'docs\\.python\\.org'],
     node: ['\\bExpress\\b', '\\bNext\\.?js\\b', '\\bNode\\.?js\\b', '\\bnpx\\b',
-        '\\bvitest\\b', '\\bjest\\b', '\\beslint\\b', '\\bprettier\\b'],
-    go: ['\\bgo (test|build|run|mod)\\b', '\\bgolangci-lint\\b', '\\bGoLand\\b'],
+        '\\bvitest\\b', '\\bjest\\b', '\\beslint\\b', '\\bprettier\\b',
+        '\\bReact\\b', '\\bVue\\b', '\\bNestJS\\b', '\\bTypeScript\\b',
+        '\\btsc\\b', '\\bzod\\b', '\\bPrisma\\b', '\\bTailwind\\b',
+        '\\bTurborepo\\b', '\\bclass-validator\\b', '\\bInertia\\b',
+        '\\bJSX\\b', '\\bNx\\b',
+        '\\.tsx?\\b', 'typescriptlang\\.org'],
+    go: ['\\bgo (test|build|run|mod)\\b', '\\bgolangci-lint\\b', '\\bGoLand\\b',
+        '\\bGolang\\b', '\\bgo\\.dev\\b'],
     rust: ['\\bcargo (test|build|run|check|fmt|clippy|add|update)\\b',
-        '\\bClippy\\b', '\\brustfmt\\b', '\\bCargo\\.toml\\b'],
+        '\\bClippy\\b', '\\brustfmt\\b', '\\bCargo\\.toml\\b',
+        'rust-lang\\.org'],
     dotnet: ['\\bdotnet (test|build|run|add|restore)\\b', '\\b\\.NET\\b'],
     java: ['\\bSpring\\b', '\\bmvn (test|clean|install|package)\\b',
         '\\bgradle\\b', '\\bMaven\\b'],
+    // Additional hint vocabulary for the PHP family — the LEAKAGE patterns
+    // are hit patterns; these are window-only hints so a JS/Python hit next
+    // to plain-language PHP mentions self-suppresses as cross-stack docs.
+    php: ['\\bvendor/', '\\bPHP\\b'],
+    // Polyglot-runner pseudo-family: a Taskfile/Makefile mention marks the
+    // window as multi-stack tooling documentation (runner files are
+    // ecosystem-neutral by definition).
+    'polyglot-runner': ['\\bTaskfile(\\.ya?ml)?\\b', '\\bMakefile\\b'],
 };
+// Case-insensitive on purpose (fix G2): "Prettier" / "ESLint" in prose are
+// the same hint as their lowercase binary names.
 const CROSS_STACK_RE: Record<string, RegExp> = Object.fromEntries(
-    Object.entries(CROSS_STACK_HINTS).map(([fam, pats]) => [fam, new RegExp(pats.join('|'))]),
+    Object.entries(CROSS_STACK_HINTS).map(([fam, pats]) => [fam, new RegExp(pats.join('|'), 'i')]),
 );
 
+// Framework-name pair rule (fix G3): Laravel and Symfony share the `php`
+// family, so a genuine Laravel-vs-Symfony comparison never counted as
+// cross-stack. Two DISTINCT framework names in the window are documentation
+// of alternatives, not a mandate.
+const FRAMEWORK_NAMES: readonly string[] = [
+    'Laravel', 'Symfony', 'Django', 'Rails', 'NestJS', 'Next\\.js', 'Spring',
+    'Flask', 'FastAPI',
+];
+const FRAMEWORK_NAME_RES: readonly RegExp[] = FRAMEWORK_NAMES.map(
+    (n) => new RegExp(`\\b${n}\\b`),
+);
+
+// Carve-out-pointer suppression (fix G6): the neutrality rule's own
+// "Allowed: carve-out pointers" shape — a handoff line linking to a
+// framework-specific artifact, or the sanctioned `→ ` pointer prefix.
+const POINTER_LINK_RE = /\]\((?:\.\.\/)+([a-z0-9-]+)\//;
+function _is_carve_out_pointer_line(line: string): boolean {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith('→ ') || trimmed.startsWith('→')) {
+        return true;
+    }
+    const m = POINTER_LINK_RE.exec(line);
+    return m !== null && CARVE_OUT_RE.test(m[1] as string);
+}
+
+// Sanctioned single-stack annotation (fix G5): the corpus-wide
+// "(Laravel shape: …)" / "Laravel example:" marker on a generic mechanism
+// (road-to-configurable-modules Phase D decision).
+const SHAPE_EXAMPLE_RE =
+    /\((?:Laravel|Symfony|Django|Rails|Next\.js)[^)]*\b(?:shape|example)\b|\b(?:Laravel|Symfony|Django|Rails) (?:shape|example):/i;
+
 const FRONTMATTER_FRAMEWORK_RE = /^---\s*\n([\s\S]*?)\n---/m;
 const FRAMEWORK_KEY_RE = /^(?:framework|\s+framework)\s*:\s*(\S+)/m;
 
@@ -287,6 +336,22 @@ function _families_in_window(lines: string[], idx: number, radius = 10): Set<str
     return families;
 }
 
+/** Fix G3: count DISTINCT framework names in the window (pair rule). */
+function _framework_names_in_window(lines: string[], idx: number, radius = 10): number {
+    const lo = Math.max(0, idx - radius);
+    const hi = Math.min(lines.length, idx + radius + 1);
+    const seen = new Set<number>();
+    for (let j = lo; j < hi; j++) {
+        const line = lines[j] as string;
+        for (let k = 0; k < FRAMEWORK_NAME_RES.length; k++) {
+            if (!seen.has(k) && (FRAMEWORK_NAME_RES[k] as RegExp).test(line)) {
+                seen.add(k);
+            }
+        }
+    }
+    return seen.size;
+}
+
 export interface Hit {
     line: number;
     category: string;
@@ -310,13 +375,23 @@ export function scan_file(p: string): Hit[] {
             for (let i = 0; i < lines.length; i++) {
                 const line = lines[i] as string;
                 if (rx.test(line)) {
+                    // Sanctioned shapes suppress the hit outright (fixes G5/G6):
+                    // a carve-out pointer line or a "(Laravel shape/example)"
+                    // annotation on a generic mechanism is the neutrality
+                    // rule's OWN allowed form, not leakage.
+                    if (_is_carve_out_pointer_line(line) || SHAPE_EXAMPLE_RE.test(line)) {
+                        continue;
+                    }
                     const families = _families_in_window(lines, i);
+                    const cross =
+                        families.size >= 2 ||
+                        _framework_names_in_window(lines, i) >= 2;
                     hits.push({
                         line: i + 1,
                         category,
                         pattern: pat,
                         snippet: line.trim().slice(0, 160),
-                        cross_stack: families.size >= 2,
+                        cross_stack: cross,
                     });
                 }
             }
@@ -426,6 +501,12 @@ export function main(argv?: readonly string[]): number {
         if (has_framework_frontmatter(f)) {
             continue;
         }
+        // Self-exemption: the neutrality rule itself enumerates the forbidden
+        // tokens (frontmatter triggers + fix table) — it can never be clean
+        // by construction.
+        if (f.endsWith(`${path.sep}framework-neutrality-in-generic-skills.md`)) {
+            continue;
+        }
         const rel = relToRepo(f);
         const raw_hits = scan_file(f);
         if (raw_hits.length === 0) {