@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/lint_confusables.ts

@@ -34,86 +34,24 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
+import { TOKEN_RE, classifyToken } from './_lib/confusables.js';
 
 export const CHECK = 'mixed-script-confusable';
 
-const MIN_LETTERS = 3;
-
-// Unicode-script classifiers via property escapes (requires the `u` flag).
-const _LATIN = /\p{Script=Latin}/u;
-const _CYRILLIC = /\p{Script=Cyrillic}/u;
-const _GREEK = /\p{Script=Greek}/u;
-const _LETTER = /\p{L}/u;
-// A "token" is a maximal run of letters / combining marks / decimal digits.
-const _TOKEN = /[\p{L}\p{M}\p{Nd}]+/gu;
-
-// Cyrillic + Greek codepoints that have a basic-Latin lookalike (Unicode TR39
-// confusables, common subset). A foreign letter only counts toward the
-// confusable signal when it is in this set — Greek math operators with no Latin
-// twin (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ δ π ω …) are deliberately excluded so legit
-// notation does not false-positive.
-const _CONFUSABLE_FOREIGN: ReadonlySet<number> = new Set([
-    // Cyrillic lowercase ↔ Latin
-    0x0430 /*а→a*/, 0x0435 /*е→e*/, 0x043e /*о→o*/, 0x0440 /*р→p*/, 0x0441 /*с→c*/,
-    0x0443 /*у→y*/, 0x0445 /*х→x*/, 0x0455 /*ѕ→s*/, 0x0456 /*і→i*/, 0x0458 /*ј→j*/,
-    0x04bb /*һ→h*/, 0x0501 /*ԁ→d*/, 0x051b /*ԛ→q*/, 0x0577 /*no*/,
-    // Cyrillic uppercase ↔ Latin
-    0x0410 /*А→A*/, 0x0412 /*В→B*/, 0x0415 /*Е→E*/, 0x041a /*К→K*/, 0x041c /*М→M*/,
-    0x041d /*Н→H*/, 0x041e /*О→O*/, 0x0420 /*Р→P*/, 0x0421 /*С→C*/, 0x0422 /*Т→T*/,
-    0x0423 /*У→Y*/, 0x0425 /*Х→X*/, 0x0405 /*Ѕ→S*/, 0x0406 /*І→I*/, 0x0408 /*Ј→J*/,
-    // Greek lowercase ↔ Latin
-    0x03b1 /*α→a*/, 0x03b5 /*ε→e*/, 0x03bf /*ο→o*/, 0x03bd /*ν→v*/, 0x03c1 /*ρ→p*/,
-    0x03c5 /*υ→u*/, 0x03c7 /*χ→x*/, 0x03ba /*κ→k*/,
-    // Greek uppercase ↔ Latin (only those with a real Latin twin)
-    0x0391 /*Α→A*/, 0x0392 /*Β→B*/, 0x0395 /*Ε→E*/, 0x0396 /*Ζ→Z*/, 0x0397 /*Η→H*/,
-    0x0399 /*Ι→I*/, 0x039a /*Κ→K*/, 0x039c /*Μ→M*/, 0x039d /*Ν→N*/, 0x039f /*Ο→O*/,
-    0x03a1 /*Ρ→P*/, 0x03a4 /*Τ→T*/, 0x03a5 /*Υ→Y*/, 0x03a7 /*Χ→X*/, 0x0392 /*Β→B*/,
-]);
-
-type ScriptName = 'latin' | 'cyrillic' | 'greek' | 'other';
-
-function _script_of(ch: string): ScriptName {
-    if (_LATIN.test(ch)) return 'latin';
-    if (_CYRILLIC.test(ch)) return 'cyrillic';
-    if (_GREEK.test(ch)) return 'greek';
-    return 'other';
-}
+// The confusable table + the mixed-script decision rule live in ONE place so
+// this authoring-time linter and the runtime encoding scanner cannot drift apart
+// (road-to-runtime-encoding-hardening Phase 3). `_classify_token` stays exported
+// under its original name — it is this module's published surface and its tests
+// address it here.
+const _TOKEN = TOKEN_RE;
 
 /**
  * Classify a single token. Returns the offending mixed-script descriptor when
  * the token matches the homoglyph signature, else null.
+ *
+ * Thin re-export of the shared implementation — see `_lib/confusables.ts`.
  */
-export function _classify_token(token: string): string | null {
-    let latin = 0;
-    let cyrillic = 0;
-    let greek = 0;
-    let letters = 0;
-    for (const ch of token) {
-        if (!_LETTER.test(ch)) continue; // skip combining marks / digits for script vote
-        letters += 1;
-        const script = _script_of(ch);
-        if (script === 'latin') {
-            latin += 1;
-        } else if (script === 'cyrillic' || script === 'greek') {
-            // Only confusable foreign letters (TR39) count — math operators with
-            // no Latin twin are ignored, so legit notation never trips.
-            if (_CONFUSABLE_FOREIGN.has(ch.codePointAt(0) as number)) {
-                if (script === 'cyrillic') cyrillic += 1;
-                else greek += 1;
-            }
-        }
-    }
-    if (letters < MIN_LETTERS) return null;
-    const foreign = cyrillic + greek;
-    if (latin === 0 || foreign === 0) return null; // single-script (or no Latin) → legit
-    if (latin <= foreign) return null; // majority must be Latin (foreign word ≠ attack)
-    const which = cyrillic > 0 && greek > 0
-        ? 'cyrillic+greek'
-        : cyrillic > 0
-            ? 'cyrillic'
-            : 'greek';
-    return `latin+${which} (${latin} latin / ${foreign} foreign-confusable)`;
-}
+export const _classify_token = classifyToken;
 
 export function _scan(sf: sl.ScannedFile): sl.Finding[] {
     if (sf.pragma_allows(CHECK)) {

package/src/scripts/lint_consumer_internal_refs.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env tsx
+/**
+ * lint_consumer_internal_refs — no maintainer-internal path/task references
+ * in consumer-projected skills.
+ *
+ * road-to-credible-install Phase 4 step 2: an external review claimed
+ * "84/281 skills reference package internals". Re-verification found the
+ * real count 17 after excluding two large classes of false positive the
+ * review's crude grep did not distinguish:
+ *
+ *   - Skills whose `workspaces:` frontmatter is EXCLUSIVELY
+ *     `agent-config-maintainer` (per ADR-013, "skills/rules/commands that
+ *     maintain THIS package") — referencing this repo's own Taskfile verbs,
+ *     dev scripts, or test suite is correct there, not a leak.
+ *   - Generic conventions this package ships to EVERY consumer project
+ *     (`agents/roadmaps/`, `agents/runtime/council/`, "check your project's
+ *     `Taskfile.yml`") — these are real, shipped, documented features, not
+ *     internal-only paths. (The `no-roadmap-references` /
+ *     `check_no_roadmap_refs.ts` lint already guards the narrower
+ *     specific-file-citation case for stable artifacts.)
+ *
+ * What DOES leak: a literal Taskfile verb invocation (`task ci`, `task
+ * sync`, …), the retired uncondensed legacy source tree (pre-ADR-051), maintainer-
+ * only docs (`docs/maintainers/`), a bare `src/scripts/<tool>.ts` reference
+ * with no `node_modules/@event4u/agent-config/` prefix (broken once the
+ * skill is installed — the relative distance from the installed file to
+ * this repo's `src/scripts/` no longer exists), a citation of this
+ * package's own test suite (`tests/scripts/*.test.ts`, never shipped), or
+ * the maintainer-only `./scripts-run` dispatch wrapper (not shipped —
+ * `package.json` `files` never lists the repo-root `scripts-run` file).
+ *
+ * Scope: every `dist/agent-src/skills/<name>/SKILL.md` — the consumer projection
+ * actually shipped in the npm package (mirrors the reviewer's own vantage
+ * point: `npm i` + read the installed skills).
+ *
+ * Carve-outs:
+ *   - Skill frontmatter `workspaces: [agent-config-maintainer]` (exclusive)
+ *     — entirely exempt, per the mechanism above.
+ *   - `SCRIPTS_RUN_ALLOWLIST` below — the `corpus-grounding` engine's own
+ *     documented consumer-runtime CLI convention (`./scripts-run
+ *     <skills-root>/<name>/scripts/<tool> …`, skill-bundled assets per
+ *     `docs/contracts/skill-bundled-assets.md`) — the invoked PATH is real
+ *     and reachable in every install; only the wrapper name is inherited
+ *     from the maintainer dispatcher. Tracked as a separate, larger-scope
+ *     naming-consistency item; out of scope for this lint's 17-skill sweep.
+ *
+ * Exit codes: 0 clean · 1 findings · 2 internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const SKILLS_DIR = path.join(REPO_ROOT, 'dist', 'agent-src', 'skills');
+
+/**
+ * Skills using `corpus-grounding`'s documented `./scripts-run
+ * <skills-root>/<name>/scripts/<tool>` consumer-runtime CLI convention
+ * (skill-bundled assets, `docs/contracts/skill-bundled-assets.md`) — the
+ * path is real and reachable once installed; only the wrapper name drifted
+ * from the contract's prescribed `node_modules/.bin/tsx` form. A single,
+ * uniform, cross-skill convention — renaming it is a separate, larger-scope
+ * follow-up, not one of this sweep's 17 leaky skills.
+ */
+const SCRIPTS_RUN_ALLOWLIST = new Set([
+    'accessibility-auditor',
+    'api-design',
+    'api-endpoint',
+    'authz-review',
+    'blade-ui',
+    'brand',
+    'brand-identity',
+    'brand-strategy',
+    'brand-to-tokens',
+    'corpus-grounding',
+    'dashboard-design',
+    'database',
+    'design-intelligence',
+    'design-tokens',
+    'flux',
+    'livewire',
+    'react-shadcn-ui',
+    'sql-writing',
+    'threat-modeling',
+    'typography-system',
+]);
+
+interface PatternDef {
+    readonly re: RegExp;
+    readonly label: string;
+    /** Skill names (by directory) exempt from this specific pattern. */
+    readonly allowlist?: ReadonlySet<string>;
+}
+
+const PATTERNS: readonly PatternDef[] = [
+    {
+        re: /`task [a-z][a-z0-9-]*`/,
+        label: 'literal Taskfile verb invocation (this repo’s own `task <verb>`, not shipped to consumers)',
+    },
+    {
+        re: /\.agent-src\.uncondensed\//,
+        label: 'reference to the retired uncondensed legacy source tree (pre-ADR-051)',
+    },
+    {
+        re: /docs\/maintainers\//,
+        label: 'reference to maintainer-only docs (`docs/maintainers/`)',
+    },
+    {
+        re: /(?<!node_modules\/@event4u\/agent-config\/)src\/scripts\//,
+        label: 'bare `src/scripts/` reference (broken once installed — prefix with `node_modules/@event4u/agent-config/` or drop)',
+    },
+    {
+        re: /tests\/scripts\//,
+        label: 'citation of this package’s own test suite (`tests/scripts/`, never shipped to consumers)',
+    },
+    {
+        re: /\.\/scripts-run\b/,
+        label: 'invocation of the maintainer-only `./scripts-run` dispatcher (not in `package.json` `files`, never reaches a consumer install)',
+        allowlist: SCRIPTS_RUN_ALLOWLIST,
+    },
+];
+
+/** `workspaces:` frontmatter list of a skill file ([] when untagged). */
+function skillWorkspaces(skillPath: string): string[] {
+    const src = fs.readFileSync(skillPath, 'utf-8');
+    const m = src.match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return [];
+    let meta: Record<string, unknown>;
+    try {
+        meta = (parseYaml(m[1] ?? '') ?? {}) as Record<string, unknown>;
+    } catch {
+        return [];
+    }
+    const ws = meta['workspaces'];
+    return Array.isArray(ws) ? ws.map((w) => String(w)) : [];
+}
+
+function isExclusivelyMaintainer(ws: readonly string[]): boolean {
+    return ws.length === 1 && ws[0] === 'agent-config-maintainer';
+}
+
+export function scanText(skillName: string, relPath: string, text: string): string[] {
+    const findings: string[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        for (const { re, label, allowlist } of PATTERNS) {
+            if (allowlist?.has(skillName)) continue;
+            // Fresh RegExp per line: lookbehind + no /g is safe to reuse via .test().
+            if (re.test(lines[i] as string)) {
+                findings.push(`${relPath}:${i + 1}: ${label}`);
+            }
+        }
+    }
+    return findings;
+}
+
+export function main(): number {
+    if (!fs.existsSync(SKILLS_DIR)) {
+        process.stderr.write(`lint_consumer_internal_refs: skills dir not found: ${SKILLS_DIR}\n`);
+        return 2;
+    }
+    let skillDirs: string[];
+    try {
+        skillDirs = fs
+            .readdirSync(SKILLS_DIR, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .sort();
+    } catch (err) {
+        process.stderr.write(`lint_consumer_internal_refs: failed to list ${SKILLS_DIR}: ${String(err)}\n`);
+        return 2;
+    }
+
+    const findings: string[] = [];
+    for (const name of skillDirs) {
+        const abs = path.join(SKILLS_DIR, name, 'SKILL.md');
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+        const ws = skillWorkspaces(abs);
+        if (isExclusivelyMaintainer(ws)) continue;
+        let text: string;
+        try {
+            text = fs.readFileSync(abs, 'utf-8');
+        } catch {
+            continue;
+        }
+        const relPath = path.relative(REPO_ROOT, abs);
+        findings.push(...scanText(name, relPath, text));
+    }
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stderr.write(`❌  consumer-internal reference: ${f}\n`);
+        }
+        process.stderr.write(
+            `\n${findings.length} consumer-internal reference(s) in the shipped skill projection. ` +
+                'Replace with the existing consumer-safe indirection (an `agent-config <verb>` CLI command, ' +
+                'the `node_modules/@event4u/agent-config/src/scripts/...` path, or a docs-site link) ' +
+                'or drop the reference (road-to-credible-install Phase 4 step 2).\n',
+        );
+        return 1;
+    }
+    process.stdout.write('✅  no consumer-internal references in the shipped skill projection\n');
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}

package/src/scripts/lint_discovery_vocabulary.ts

@@ -46,6 +46,8 @@ const ADR_PACKS: ReadonlySet<string> = new Set<string>([
     'ai-image', 'analysis-workbench',
     // road-to-legal-pack Phase 0 + road-to-legal-review-prep Phase 0 rename (ADR-013 amendments).
     'legal-review-prep',
+    // road-to-scale-and-history-discipline Phase 1/3 (ADR-013 amendment, same PR).
+    'scale-discipline', 'history-discipline',
 ]);
 
 // ADR-010 non-overlap reservations.