@event4u/agent-config 7.1.0 → 7.2.0

package/src/scripts/lint_output_slop.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * lint_output_slop — detect banned placeholder-prose patterns in generated
+ * code and UI output. Six zero-false-positive rules; exit 2 on any finding.
+ *
+ * Scans: src/skills/**\/SKILL.md, src/rules/*.md, docs/guidelines/*.md
+ * (i.e., the package's own authored artifacts). Consumer projects should
+ * run this against their own src/ directories.
+ *
+ * Rules (all zero-false-positive in the package tree):
+ *   P1 lorem-ipsum      — Lorem ipsum / dolor sit amet filler text
+ *   P2 bracket-placeholder — [Your ... here], <YourComponentName> patterns
+ *   P3 impl-placeholder — // rest of component, // ... (unchanged), etc.
+ *   P4 for-brevity      — "for brevity" inside code content
+ *   P5 ellipsis-trunc   — … or ... as standalone code-continuation markers
+ *   P6 todo-implement   — // TODO.*implement (unimplemented stubs)
+ *
+ * Inline-ignore: add a comment on the same or previous line:
+ *   lint-output-slop-disable-next-line <rule-id> [-- reason]
+ *   lint-output-slop-disable-line <rule-id> [-- reason]
+ *   lint-output-slop-disable-file <rule-id> [-- reason]  (top of file)
+ *
+ * Exit codes: 0 = clean, 2 = findings present, 1 = internal error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, "..", "..");
+
+interface Finding {
+  rule: string;
+  file: string;
+  line: number;
+  snippet: string;
+}
+
+// ---------------------------------------------------------------------------
+// Rule definitions — each is (id, label, regex-on-a-line-of-content)
+// We only scan INSIDE fenced code blocks in markdown, and in plain .ts/.tsx
+// source files. This prevents false positives from inline-ignore comments,
+// documentation paragraphs, or test descriptions.
+// ---------------------------------------------------------------------------
+const RULES: Array<{ id: string; label: string; pattern: RegExp }> = [
+  {
+    id: "lorem-ipsum",
+    label: "Filler text: Lorem ipsum / dolor sit amet",
+    pattern: /Lorem\s+ipsum|dolor\s+sit\s+amet/i,
+  },
+  {
+    id: "bracket-placeholder",
+    label: "Bracket placeholder: [Your ... here] or <YourComponentName>",
+    pattern: /\[Your\s+\w[\w\s]*here\]|<Your\w+Name>/,
+  },
+  {
+    id: "impl-placeholder",
+    label: "Implementation placeholder: // rest of component / // ... (unchanged)",
+    pattern:
+      /\/\/\s*(rest\s+of\s+(component|implementation|code)|\.{3}\s*\(unchanged\)|same\s+pattern\s+follows)/i,
+  },
+  {
+    id: "for-brevity",
+    label: "Truncation excuse: 'for brevity' inside code",
+    pattern: /\/\/.*for\s+brevity|\/\*.*for\s+brevity.*\*\//i,
+  },
+  {
+    id: "ellipsis-trunc",
+    label: "Ellipsis-as-truncation: standalone … (Unicode) as a continuation placeholder",
+    // Match lines that are ONLY a Unicode ellipsis character (not `// ...`
+    // which is a legitimate code-documentation shorthand in SKILL.md examples).
+    pattern: /^\s*…\s*$/,
+  },
+  {
+    id: "todo-implement",
+    label: "Unimplemented stub: // TODO.*implement",
+    pattern: /\/\/\s*TODO[:\s].*implement/i,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// File discovery
+// ---------------------------------------------------------------------------
+function* walkDir(dir: string, ext: RegExp): Generator<string> {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkDir(full, ext);
+    } else if (ext.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+function collectFiles(): string[] {
+  const files: string[] = [];
+  // Package-authored markdown (skills, rules, guidelines)
+  for (const f of walkDir(path.join(REPO_ROOT, "src", "skills"), /SKILL\.md$/)) files.push(f);
+  for (const f of walkDir(path.join(REPO_ROOT, "src", "rules"), /\.md$/)) files.push(f);
+  for (const f of walkDir(path.join(REPO_ROOT, "docs", "guidelines"), /\.md$/)) files.push(f);
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// Inline-ignore parsing
+// ---------------------------------------------------------------------------
+type IgnoreScope = "file" | "line" | "next-line";
+interface Ignore {
+  scope: IgnoreScope;
+  rules: string[]; // empty = all rules
+  lineNum?: number;
+}
+
+function parseIgnores(lines: string[]): Ignore[] {
+  const ignores: Ignore[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const fileMatch = /lint-output-slop-disable-file\s*([\w-]+(?:,\s*[\w-]+)*)?/i.exec(line);
+    if (fileMatch) {
+      const rules = fileMatch[1] ? fileMatch[1].split(",").map((r) => r.trim()) : [];
+      ignores.push({ scope: "file", rules });
+    }
+    const lineMatch = /lint-output-slop-disable-line\s*([\w-]+(?:,\s*[\w-]+)*)?/i.exec(line);
+    if (lineMatch) {
+      const rules = lineMatch[1] ? lineMatch[1].split(",").map((r) => r.trim()) : [];
+      ignores.push({ scope: "line", rules, lineNum: i + 1 });
+    }
+    const nextMatch = /lint-output-slop-disable-next-line\s*([\w-]+(?:,\s*[\w-]+)*)?/i.exec(line);
+    if (nextMatch) {
+      const rules = nextMatch[1] ? nextMatch[1].split(",").map((r) => r.trim()) : [];
+      ignores.push({ scope: "next-line", rules, lineNum: i + 2 }); // 1-indexed, next line
+    }
+  }
+  return ignores;
+}
+
+function isIgnored(ignores: Ignore[], ruleId: string, lineNum: number): boolean {
+  for (const ig of ignores) {
+    const ruleMatch = ig.rules.length === 0 || ig.rules.includes(ruleId);
+    if (!ruleMatch) continue;
+    if (ig.scope === "file") return true;
+    if (ig.scope === "line" && ig.lineNum === lineNum) return true;
+    if (ig.scope === "next-line" && ig.lineNum === lineNum) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Scanning — only within fenced code blocks in markdown
+// ---------------------------------------------------------------------------
+function scanFile(filePath: string): Finding[] {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  const ignores = parseIgnores(lines);
+  const findings: Finding[] = [];
+
+  let inCodeBlock = false;
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const line = lines[i] ?? "";
+
+    // Toggle code-fence state
+    if (/^```/.test(line) || /^~~~/.test(line)) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+
+    // Only scan inside code fences in markdown
+    if (!inCodeBlock) continue;
+
+    for (const rule of RULES) {
+      if (rule.pattern.test(line) && !isIgnored(ignores, rule.id, lineNum)) {
+        findings.push({
+          rule: rule.id,
+          file: path.relative(REPO_ROOT, filePath),
+          line: lineNum,
+          snippet: line.trim().slice(0, 120),
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main(): void {
+  const jsonMode = process.argv.includes("--json");
+  const quiet = process.argv.includes("--quiet");
+
+  const files = collectFiles();
+  const allFindings: Finding[] = [];
+
+  for (const file of files) {
+    try {
+      allFindings.push(...scanFile(file));
+    } catch (err) {
+      if (!quiet) process.stderr.write(`[lint_output_slop] error reading ${file}: ${err}\n`);
+    }
+  }
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(allFindings, null, 2) + "\n");
+    process.exit(allFindings.length > 0 ? 2 : 0);
+  }
+
+  if (allFindings.length === 0) {
+    if (!quiet) process.stdout.write("✅  lint_output_slop: clean — no placeholder-prose patterns found.\n");
+    process.exit(0);
+  }
+
+  for (const f of allFindings) {
+    process.stdout.write(`❌  ${f.file}:${f.line} [${f.rule}] ${f.snippet}\n`);
+  }
+  process.stdout.write(
+    `\nlint_output_slop: ${allFindings.length} finding(s). Fix or use lint-output-slop-disable-next-line <rule> -- reason.\n`,
+  );
+  process.exit(2);
+}
+
+main();

package/src/scripts/lint_pack_risk_class.ts

@@ -0,0 +1,79 @@
+/**
+ * Lint the `risk_class` invariant on packs (road-to-capability-governance Phase 2).
+ *
+ * `risk_class: high` is the regulated-advice-adjacent tier. A high-risk pack MUST
+ * ship conservatively — off by default, consent-gated, lab-tier — or it is a
+ * governance hole. This linter makes that invariant a hard CI failure.
+ *
+ *   high  ⇒ default_install: false  AND  requires_explicit_consent: true  AND  surface_tier: lab
+ *
+ * `medium` / `low` carry no structural requirement here (their disclaimers live
+ * in the domain safety floors). Absent `risk_class` = `low`.
+ *
+ * Pure core (`riskClassViolations`) takes the packs.yml text so it is unit-testable
+ * without the filesystem. Exit 0 = clean, 1 = at least one violation.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const QUIET = process.argv.includes('--quiet');
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const PACKS_YML = path.join(REPO, 'src', 'config', 'discovery', 'packs.yml');
+
+export interface RiskViolation {
+    pack: string;
+    msg: string;
+}
+
+function _field(block: string, key: string): string | undefined {
+    return new RegExp(`(^|\\n)\\s*${key}:\\s*([^\\n#]+)`).exec(block)?.[2]?.trim();
+}
+
+/** Pure invariant check over packs.yml text. */
+export function riskClassViolations(packsYml: string): RiskViolation[] {
+    const out: RiskViolation[] = [];
+    // Split into per-pack blocks on top-level `- id:` entries.
+    const re = /(^|\n)- id:\s*([^\n#]+?)\s*\n([\s\S]*?)(?=\n- id:|\n*$)/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(packsYml)) !== null) {
+        const id = (m[2] ?? '').trim();
+        const block = m[3] ?? '';
+        const risk = _field(block, 'risk_class') ?? 'low';
+        if (risk !== 'high') continue;
+        const checks: Array<[string, string, string]> = [
+            ['default_install', 'false', `${id}: risk_class high requires default_install: false`],
+            ['requires_explicit_consent', 'true', `${id}: risk_class high requires requires_explicit_consent: true`],
+            ['surface_tier', 'lab', `${id}: risk_class high requires surface_tier: lab`],
+        ];
+        for (const [key, want, msg] of checks) {
+            if (_field(block, key) !== want) out.push({ pack: id, msg });
+        }
+    }
+    return out;
+}
+
+function _print(s: string): void {
+    if (!QUIET) process.stdout.write(`${s}\n`);
+}
+
+export function main(): number {
+    if (!fs.existsSync(PACKS_YML)) {
+        _print('⚠️  packs.yml not found — skipping risk_class lint');
+        return 0;
+    }
+    const violations = riskClassViolations(fs.readFileSync(PACKS_YML, 'utf-8'));
+    if (violations.length === 0) {
+        _print('✅  risk_class invariant OK — every high-risk pack is off-by-default + consent + lab');
+        return 0;
+    }
+    _print(`❌  risk_class invariant — ${violations.length} violation(s):`);
+    for (const v of violations) _print(`  - ${v.msg}`);
+    return 1;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}

package/src/scripts/schemas/agent-settings.schema.json

@@ -83,6 +83,18 @@
           "description": "How strictly the agent must follow a user-provided prototype / mockup / design system. Consumed by the design-fidelity rule. strict = build 1:1, every visible deviation needs confirmation; structural = structure locked, silent gaps fillable with a stated assumption; hard-floor = any deviation is never autonomous."
         }
       }
+    },
+    "tokens": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Token-spend governance for skills marked token_budget_class: rich. See token-budget-discipline rule.",
+      "properties": {
+        "rich_skills": {
+          "type": "string",
+          "enum": ["on", "ask", "off"],
+          "description": "Controls whether skills marked token_budget_class: rich may load in full (exempt from telegraph-speak and thin-projector trimming). on = allowed (default); off = fall back to standard condensed behavior; ask = surface an estimated token delta (tokens, not dollars) and ask the user once per session before loading."
+        }
+      }
     }
   }
 }

package/src/scripts/schemas/skill.schema.json

@@ -182,6 +182,11 @@
         "removable": {"type": "boolean", "default": false}
       },
       "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
+    },
+    "token_budget_class": {
+      "type": "string",
+      "enum": ["lean", "standard", "rich"],
+      "description": "Token-cost class for this skill. `lean` (default): subject to telegraph-speak condensation and thin-projector trimming; optimize for <500 tokens. `standard`: balanced guidance, normal condensation. `rich`: exempt from telegraph-speak and thin-projector trimming; detailed examples preserved; eager-load eligible; ≤15% of skills in a suite may be `rich` (CI-enforced). A `rich` skill MUST carry a '## Why this skill is rich' section explaining the irreducible complexity that makes condensation harmful. Governed by `token-budget-discipline` rule + `tokens.rich_skills` consumer setting. See docs/guidelines/token-budget-governance.md."
     }
   }
 }