@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/lint_budget_ownership.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env tsx
+/**
+ * lint_budget_ownership — every gate budget carries an owner and a review
+ * date (road-to-credible-install Phase 6.2, anti-ossification).
+ *
+ * A budget without a named owner and an annual review date fossilizes: the
+ * number outlives its rationale and the gate becomes ritual. This lint
+ * fails the build when any budget config under src/config/ lacks:
+ *   - `owner`     (non-empty string)
+ *   - `review_by` (YYYY-MM-DD; may be past — a PAST date is a WARN-level
+ *                  reminder printed to stderr, not a failure, so an overdue
+ *                  review never blocks unrelated PRs; a MISSING date fails)
+ *
+ * Scope: src/config/*budget*.json (top-level fields). Per-entry overrides
+ * are allowed but not required — the top-level owner/review_by covers the
+ * file.
+ *
+ * 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';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const CONFIG_DIR = path.join(REPO_ROOT, 'src', 'config');
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function checkBudgetDoc(relPath: string, doc: Record<string, unknown>): string[] {
+    const errors: string[] = [];
+    const owner = doc['owner'];
+    if (typeof owner !== 'string' || owner.trim() === '') {
+        errors.push(`${relPath}: missing non-empty top-level \`owner\``);
+    }
+    const review = doc['review_by'];
+    if (typeof review !== 'string' || !DATE_RE.test(review)) {
+        errors.push(`${relPath}: missing/invalid top-level \`review_by\` (YYYY-MM-DD)`);
+    }
+    return errors;
+}
+
+export function budgetFiles(dir: string = CONFIG_DIR): string[] {
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.json') && f.toLowerCase().includes('budget'))
+            .map((f) => path.join(dir, f));
+    } catch {
+        return [];
+    }
+}
+
+export function main(): number {
+    const files = budgetFiles();
+    if (files.length === 0) {
+        process.stdout.write('ℹ️  no budget configs under src/config/ — nothing to lint\n');
+        return 0;
+    }
+    const errors: string[] = [];
+    const today = new Date().toISOString().slice(0, 10);
+    for (const abs of files) {
+        const rel = path.relative(REPO_ROOT, abs);
+        let doc: Record<string, unknown>;
+        try {
+            doc = JSON.parse(fs.readFileSync(abs, 'utf-8')) as Record<string, unknown>;
+        } catch (e) {
+            errors.push(`${rel}: unparseable JSON (${(e as Error).message})`);
+            continue;
+        }
+        errors.push(...checkBudgetDoc(rel, doc));
+        const review = doc['review_by'];
+        if (typeof review === 'string' && DATE_RE.test(review) && review < today) {
+            process.stderr.write(
+                `⚠️  ${rel}: review_by ${review} is overdue — re-affirm or adjust the budget\n`,
+            );
+        }
+    }
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  budget ownership: ${e}\n`);
+        return 1;
+    }
+    process.stdout.write(`✅  budget ownership OK (${files.length} budget config(s))\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_command_routing.ts

@@ -34,6 +34,9 @@ const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 // anchors to string start and `.*?` is non-greedy across newlines.
 const FM_RE = /^---\n([\s\S]*?)\n---/;
 const VISIBLE_TIERS: ReadonlySet<number> = new Set([0, 1]);
+// ADR-090/092: `visibility` is the source of truth; the integer `tier` is the
+// back-compat alias kept only as a fallback until it is removed.
+const VISIBLE_VISIBILITIES: ReadonlySet<string> = new Set(['visible', 'advanced']);
 const MIN_CASES = 5; // roadmap Step 5: "5–10 example prompts"
 
 interface Violation {
@@ -41,6 +44,26 @@ interface Violation {
     reason: string;
 }
 
+/**
+ * Is this command part of the gated visible surface?
+ *
+ * Reads `visibility` first, falls back to the deprecated `tier` alias.
+ * `null` = NEITHER key present — the silent-default hole this linter used to
+ * have (absent tier → 2 → skipped), which callers must report rather than
+ * treat as internal.
+ */
+function _isVisible(fm: Record<string, unknown>): boolean | null {
+    const vis = fm['visibility'];
+    if (typeof vis === 'string') {
+        return VISIBLE_VISIBILITIES.has(vis);
+    }
+    const tier = fm['tier'];
+    if (typeof tier === 'number') {
+        return VISIBLE_TIERS.has(tier);
+    }
+    return null;
+}
+
 function _isDir(p: string): boolean {
     try {
         return fs.statSync(p).isDirectory();
@@ -170,11 +193,19 @@ function _isNonEmptyString(v: unknown): v is string {
 
 function check(md: string): Violation[] {
     const fm = _frontmatter(fs.readFileSync(md, 'utf-8'));
-    const tier = 'tier' in fm ? (fm['tier'] as unknown) : 2;
-    if (typeof tier !== 'number' || !VISIBLE_TIERS.has(tier)) {
+    const visible = _isVisible(fm);
+    const rel = _relTo(md, ROOT);
+    if (visible === null) {
+        return [
+            {
+                file: rel,
+                reason: 'missing `visibility` (and no `tier` alias) — cannot determine whether routing metadata is required',
+            },
+        ];
+    }
+    if (!visible) {
         return [];
     }
-    const rel = _relTo(md, ROOT);
     const vio: Violation[] = [];
 
     const intent = fm['intent'];
@@ -310,8 +341,7 @@ function main(): number {
             continue;
         }
         const fm = _frontmatter(fs.readFileSync(md, 'utf-8'));
-        const tier = 'tier' in fm ? (fm['tier'] as unknown) : 2;
-        if (typeof tier === 'number' && VISIBLE_TIERS.has(tier)) {
+        if (_isVisible(fm) === true) {
             visible += 1;
         }
         violations.push(...check(md));

package/src/scripts/lint_command_verbs.ts

@@ -10,7 +10,8 @@
  * visible command under `--all`), and the same sorted iteration order.
  * snake_case kept. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
- * A VISIBLE command (tier 0/1) must have a leading token drawn from the
+ * A VISIBLE command (`visibility: visible|advanced`, i.e. the legacy tier 0/1)
+ * must have a leading token drawn from the
  * approved verb allowlist in `src/config/discovery/command-verbs.yml`.
  * `create-*` is a banned leading token for new visible commands
  * (`create-pr` is grandfathered).
@@ -32,8 +33,13 @@ const VERBS_YML = path.join(ROOT, 'src', 'config', 'discovery', 'command-verbs.y
 const _CMD_PATH_RE = /\.agent-src\.uncondensed\/commands\/.+\.md$/;
 const NAME_RE = /^name:\s*(.*)$/m;
 const TIER_RE = /^tier:\s*(\d+)/m;
+const VISIBILITY_RE = /^visibility:\s*['"]?([A-Za-z-]+)/m;
 const SUB_RE = /^sub:\s*(.*)$/m;
 const VISIBLE_TIERS: ReadonlySet<number> = new Set([0, 1]);
+// ADR-090/092: `visibility` is the source of truth; the integer `tier` is the
+// back-compat alias. `visible`/`advanced` are the two gated (non-internal)
+// values — the named equivalent of VISIBLE_TIERS {0, 1}.
+const VISIBLE_VISIBILITIES: ReadonlySet<string> = new Set(['visible', 'advanced']);
 
 interface Violation {
     file: string;
@@ -109,15 +115,31 @@ function _git(args: string[], tolerant = false): string {
     return r.stdout;
 }
 
-/** (name, tier, sub) from frontmatter text; tier defaults to 2 (internal). */
-function _parse(text: string): { name: string | null; tier: number; sub: string | null } {
+/**
+ * (name, visible, sub) from frontmatter text.
+ *
+ * `visible` reads `visibility` first and falls back to the deprecated integer
+ * `tier` alias, which is what PAST git revisions carry — the promotion check
+ * below parses pre-ADR-090 blobs, so the alias fallback must stay until those
+ * revisions age out. `null` means NEITHER key was present: that is the
+ * silent-default hole this linter used to have (absent tier → 2 → skipped, so
+ * the gate quietly stopped gating), and callers must treat it as a violation
+ * rather than as "internal".
+ */
+function _parse(text: string): { name: string | null; visible: boolean | null; sub: string | null } {
     const nm = NAME_RE.exec(text);
     const name = nm ? _stripQuotes(nm[1]!.trim()) : null;
+    const vm = VISIBILITY_RE.exec(text);
     const tm = TIER_RE.exec(text);
-    const tier = tm ? parseInt(tm[1]!, 10) : 2;
+    let visible: boolean | null = null;
+    if (vm) {
+        visible = VISIBLE_VISIBILITIES.has(vm[1]!);
+    } else if (tm) {
+        visible = VISIBLE_TIERS.has(parseInt(tm[1]!, 10));
+    }
     const sm = SUB_RE.exec(text);
     const sub = sm ? _stripQuotes(sm[1]!.trim()) : null;
-    return { name, tier, sub };
+    return { name, visible, sub };
 }
 
 function changed_command_files(baseline: string): Record<string, string> {
@@ -223,16 +245,27 @@ function check(
     if (!_exists(abs_path)) {
         return []; // deleted
     }
-    const { name, tier, sub } = _parse(fs.readFileSync(abs_path, 'utf-8'));
-    if (name === null || !VISIBLE_TIERS.has(tier)) {
+    const { name, visible, sub } = _parse(fs.readFileSync(abs_path, 'utf-8'));
+    if (visible === null) {
+        // Neither `visibility` nor the `tier` alias — fail loudly instead of
+        // defaulting to internal, which would silently un-gate the command.
+        return [
+            {
+                file: relpath,
+                rule: 'visibility',
+                reason: 'missing `visibility` (and no `tier` alias) — cannot determine whether this command is gated',
+            },
+        ];
+    }
+    if (name === null || !visible) {
         return []; // internal / unnamed — not gated
     }
     if (kind === 'M') {
         // Only a PROMOTION into visibility counts as a new visible surface.
         const prev = _git(['show', `${baseline}:${relpath}`], true);
         if (prev) {
-            const { tier: prev_tier } = _parse(prev);
-            if (VISIBLE_TIERS.has(prev_tier)) {
+            const { visible: prev_visible } = _parse(prev);
+            if (prev_visible === true) {
                 return []; // already visible before — grandfathered
             }
         }

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.