@event4u/agent-config 7.4.0 → 8.0.0

package/src/scripts/degrade_to_pointer.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env tsx
+/**
+ * Pointer degradation — road-to-knowledge-system Phase 4 (self-learning
+ * wiring). After `learning-to-rule-or-skill` promotes a knowledge-page
+ * entry into a real skill/rule/guideline, the SOURCE entry is rewritten to
+ * a pointer stub instead of staying as full duplicated prose. This is the
+ * staging → promotion → pointer lifecycle: it prevents double-maintenance
+ * between the knowledge page and the new artifact, and keeps
+ * `agents/knowledge/INDEX.md` honest about what still needs attention.
+ *
+ * Two source shapes:
+ *   - Whole page: `--source agents/knowledge/concepts/x.md` — the page
+ *     BODY (below frontmatter) is replaced with a pointer line;
+ *     frontmatter (and its provenance) is preserved untouched.
+ *   - Named section: `--source agents/knowledge/procedures/skill-candidates.md#<topic>`
+ *     — only the matching `## <topic>` section's body is replaced; the
+ *     heading and every other section stay untouched.
+ *
+ * Usage:
+ *   degrade_to_pointer.ts --source <path[#anchor]> --artifact <path> --date <YYYY-MM-DD>
+ *
+ * Exit codes: 0 = degraded, 1 = usage error / source not found, 3 = internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { main as generateIndexMain } from './generate_knowledge_index.js';
+
+const PROG = 'degrade_to_pointer.ts';
+const FRONTMATTER_RE = /^(---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n)/;
+
+export function pointerLine(artifact: string, date: string): string {
+    return `> Promoted to \`${artifact}\` on ${date}; see that artifact for current guidance.`;
+}
+
+/** Replace a whole page's body (below frontmatter, if any) with a pointer line. Preserves frontmatter and the first H1 heading, if present, so the page stays a resolvable link target. */
+export function degradeWholeFile(content: string, artifact: string, date: string): string {
+    const fmMatch = FRONTMATTER_RE.exec(content);
+    const frontmatter = fmMatch?.[1] ?? '';
+    const rest = fmMatch ? content.slice(frontmatter.length) : content;
+
+    const headingMatch = /^(#\s+.+)$/m.exec(rest);
+    const heading = headingMatch?.[1] !== undefined ? `${headingMatch[1]}\n\n` : '';
+
+    return `${frontmatter}${heading}${pointerLine(artifact, date)}\n`;
+}
+
+/** Replace one `## <anchor>` section's body (up to the next `## ` heading or EOF) with a pointer line, byte-for-byte outside that span. Throws if the anchor is not found. */
+export function degradeSection(content: string, anchor: string, artifact: string, date: string): string {
+    const headingLine = `## ${anchor}`;
+    const lines = content.split('\n');
+    const startIdx = lines.findIndex((l) => l.trim() === headingLine);
+    if (startIdx === -1) {
+        throw new Error(`section "${anchor}" not found`);
+    }
+    let endIdx = lines.length;
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i] ?? '')) {
+            endIdx = i;
+            break;
+        }
+    }
+    const before = lines.slice(0, startIdx + 1);
+    const after = lines.slice(endIdx);
+    const body = ['', pointerLine(artifact, date), ''];
+    return [...before, ...body, ...after].join('\n');
+}
+
+function printUsage(): void {
+    process.stdout.write(`usage: ${PROG} --source PATH[#ANCHOR] --artifact PATH --date YYYY-MM-DD\n`);
+}
+
+export function main(argv: string[]): number {
+    let source: string | null = null;
+    let artifact: string | null = null;
+    let date: string | null = null;
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            printUsage();
+            return 0;
+        } else if (arg === '--source') {
+            source = argv[++i] ?? null;
+        } else if (arg === '--artifact') {
+            artifact = argv[++i] ?? null;
+        } else if (arg === '--date') {
+            date = argv[++i] ?? null;
+        } else {
+            process.stderr.write(`${PROG}: error: unrecognized argument: ${arg}\n`);
+            printUsage();
+            return 1;
+        }
+    }
+
+    if (!source || !artifact || !date) {
+        process.stderr.write(`${PROG}: error: --source, --artifact, and --date are required\n`);
+        printUsage();
+        return 1;
+    }
+
+    const [filePath = '', anchor] = source.split('#');
+
+    let content: string;
+    try {
+        content = fs.readFileSync(filePath, 'utf8');
+    } catch {
+        process.stderr.write(`${PROG}: error: source file not found: ${filePath}\n`);
+        return 1;
+    }
+
+    let updated: string;
+    try {
+        updated = anchor ? degradeSection(content, anchor, artifact, date) : degradeWholeFile(content, artifact, date);
+    } catch (err) {
+        process.stderr.write(`${PROG}: error: ${(err as Error).message}\n`);
+        return 1;
+    }
+
+    fs.writeFileSync(filePath, updated, 'utf8');
+    process.stdout.write(`${PROG}: degraded ${source} → pointer to ${artifact}.\n`);
+
+    // Regenerate the index so the pointer's new one-line summary is
+    // reflected immediately, not left stale until the next unrelated write.
+    // Assumes the standard invocation cwd (repo root), matching every other
+    // script in this package (generate_knowledge_index.ts defaults the same way).
+    generateIndexMain(['--dir', process.cwd(), '--quiet']);
+
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/design_slop_rules.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+import { SLOP_RULES, type DesignContext } from "./design_slop_rules.js";
+import { scanFile } from "./lint_design_slop.js";
+
+// Context with no DESIGN.md → all gates OFF, every rule active.
+const NO_CTX: DesignContext = { raw: "", has: () => false };
+const ctxWith = (raw: string): DesignContext => ({
+  raw: raw.toLowerCase(),
+  has: (...ks: string[]) => ks.some((k) => raw.toLowerCase().includes(k.toLowerCase())),
+});
+
+/**
+ * Calibration corpus (Phase 4). One positive (must fire) + one negative (must be
+ * clean) per rule. `ext` drives the engine class. No untested tell — the guard
+ * below asserts every registry rule appears here.
+ */
+const FIXTURES: Record<string, { ext: string; positive: string; negative: string }> = {
+  "slop-v1-side-stripe": {
+    ext: "css",
+    positive: ".card { border-left: 4px solid #6c5ce7; padding: 16px; }",
+    negative: ".card { border-left: 1px solid #eee; padding: 16px; }",
+  },
+  "slop-v3-ghost-card": {
+    ext: "css",
+    positive: ".card { border: 1px solid #ddd; box-shadow: 0 8px 24px rgba(0,0,0,.1); }",
+    negative: ".card { box-shadow: 0 2px 4px rgba(0,0,0,.1); }",
+  },
+  "slop-v6-diagonal-stripes": {
+    ext: "css",
+    positive: ".bg { background: repeating-linear-gradient(45deg,#000,#000 10px,#111 10px,#111 20px); }",
+    negative: ".bg { background: linear-gradient(#fff,#eee); }",
+  },
+  "slop-c2-gradient-text": {
+    ext: "css",
+    positive: ".h { background: linear-gradient(90deg,#f00,#00f); -webkit-background-clip: text; color: transparent; }",
+    negative: ".h { color: #111; }",
+  },
+  "slop-c5-cream-palette": {
+    ext: "css",
+    positive: "body { background: #f5f1ea; } .a { color: #b08947; }",
+    negative: "body { background: #ffffff; } .a { color: #111111; }",
+  },
+  "slop-t4-eyebrow-overuse": {
+    ext: "html",
+    positive:
+      '<section><span class="uppercase">Features</span></section><section><span class="uppercase">Pricing</span></section><section><h2>Contact</h2></section>',
+    negative:
+      '<section><span class="uppercase">Features</span></section><section><h2>Pricing</h2></section><section><h2>Contact</h2></section>',
+  },
+  "slop-t6-crushed-tracking": {
+    ext: "css",
+    positive: ".display { letter-spacing: -0.05em; }",
+    negative: ".display { letter-spacing: -0.02em; }",
+  },
+  "slop-t7-default-fonts": {
+    ext: "css",
+    positive: "body { font-family: 'Inter', sans-serif; }",
+    negative: "body { font-family: 'Söhne', sans-serif; }",
+  },
+  "slop-l4-numbered-markers": {
+    ext: "html",
+    positive: "<div>01</div><div>02</div><div>03</div>",
+    negative: "<div>Discover</div><div>Build</div><div>Ship</div>",
+  },
+  "slop-l8-zindex-magic": {
+    ext: "css",
+    positive: ".modal { z-index: 9999; }",
+    negative: ".modal { z-index: 400; }",
+  },
+  "slop-m4-transition-all": {
+    ext: "css",
+    positive: ".x { transition: all 200ms ease-out; }",
+    negative: ".x { transition: transform 200ms ease-out; }",
+  },
+  "slop-m2-animate-layout": {
+    ext: "css",
+    positive: ".x { transition: width 200ms ease; }",
+    negative: ".x { transition: transform 200ms, opacity 200ms; }",
+  },
+  "slop-cp1-em-dash": {
+    ext: "md",
+    // ≥80 words is the rule floor; positive carries 4 em-dashes (well over the
+    // ~2-per-500 density), negative carries one across the same length.
+    positive:
+      "We build tools — fast, focused tools — that teams genuinely love using every single day of the working week. " +
+      "The product is calm and clear and useful, and people return to it daily because it respects their time — and their attention — and never wastes a single click of effort or a moment of their busy day, and that quiet reliability is the whole point of the thing we set out to make together, and the team keeps shipping the small improvements that matter most to the people who rely on it.",
+    negative:
+      "We build tools, fast and focused tools, that teams genuinely love using every single day of the working week. " +
+      "The product is calm and clear and useful, and people return to it daily because it respects their time and their attention and never wastes a single click of effort or a moment of their busy day — and that quiet reliability is the whole point of the thing we set out to make together, and the team keeps shipping the small improvements that matter most to the people who rely on it.",
+  },
+  "slop-cp2-buzzword": {
+    ext: "md",
+    positive: "We streamline and empower your robust, world-class workflow.",
+    negative: "We cut page load by 40% and remove three steps from checkout.",
+  },
+  "slop-cp5-emoji-ui": {
+    ext: "html",
+    positive: '<h1>🚀 Get Started</h1><button>✅ Track progress</button>',
+    // Functional placements stay clean: mid-sentence emoji, status-cell emoji.
+    negative:
+      '<h1>Get Started</h1><p>Deploys are marked ✅ when healthy.</p><td>✅</td><button>Track progress</button>',
+  },
+  "slop-lock-shape": {
+    ext: "css",
+    positive: ".a{border-radius:4px}.b{border-radius:8px}.c{border-radius:12px}.d{border-radius:20px}",
+    negative: ".a{border-radius:8px}.b{border-radius:12px}",
+  },
+  "slop-lock-colour": {
+    ext: "css",
+    positive: ".a{color:#e11d48}.b{background:#2563eb}.c{border-color:#16a34a}",
+    negative: ".a{color:#111827}.b{background:#6b7280}.c{border-color:#2563eb}",
+  },
+  "slop-l9-section-monotony": {
+    ext: "html",
+    // 8 identical media+text sections → 1 distinct layout family (< 4)
+    positive: '<section><div class="grid"><img src="x"><h2>A</h2><p>t</p></div></section>'.repeat(8),
+    // 8 sections, 4 distinct signatures → not monotonous
+    negative: (
+      '<section><div class="grid"><img src="x"><h2>A</h2></div></section>' +
+      "<section><h2>B</h2><p>t</p></section>" +
+      '<section><div class="flex"><p>c</p></div></section>' +
+      '<section><img src="y"></section>'
+    ).repeat(2),
+  },
+  "slop-l10-zigzag": {
+    ext: "html",
+    // 3 consecutive media+text two-column sections → run > 2
+    positive: '<section><div class="grid"><img src="x"><h2>A</h2><p>t</p></div></section>'.repeat(3),
+    // only 2 consecutive → within cap
+    negative: '<section><div class="grid"><img src="x"><h2>A</h2><p>t</p></div></section>'.repeat(2),
+  },
+};
+
+function findingsFor(ruleId: string, content: string, ext: string, ctx = NO_CTX) {
+  return scanFile(content, `fixture.${ext}`, ctx).filter((f) => f.rule === ruleId);
+}
+
+describe("design-slop rule registry", () => {
+  it("every rule has a unique id + a catalog id", () => {
+    const ids = SLOP_RULES.map((r) => r.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    for (const r of SLOP_RULES) {
+      expect(r.id).toMatch(/^slop-/);
+      expect(r.catalogId).toMatch(/^[A-Z]+\d+$/);
+      expect(r.engines.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("no untested tell — every registry rule has a +/- fixture", () => {
+    for (const r of SLOP_RULES) {
+      expect(FIXTURES[r.id], `missing fixture for ${r.id}`).toBeDefined();
+    }
+    // and no orphan fixtures
+    const ids = new Set(SLOP_RULES.map((r) => r.id));
+    for (const k of Object.keys(FIXTURES)) {
+      expect(ids.has(k), `orphan fixture ${k}`).toBe(true);
+    }
+  });
+
+  describe("positive fixtures fire, negative fixtures are clean", () => {
+    for (const r of SLOP_RULES) {
+      const fx = FIXTURES[r.id];
+      if (!fx) continue;
+      it(`${r.id} (${r.catalogId})`, () => {
+        expect(findingsFor(r.id, fx.positive, fx.ext).length, "positive must fire").toBeGreaterThan(0);
+        expect(findingsFor(r.id, fx.negative, fx.ext).length, "negative must be clean").toBe(0);
+      });
+    }
+  });
+});
+
+describe("context gates suppress when DESIGN.md declares intent", () => {
+  it("t7 default-font is suppressed when DESIGN.md adopts Inter", () => {
+    const fx = FIXTURES["slop-t7-default-fonts"]!;
+    expect(findingsFor("slop-t7-default-fonts", fx.positive, "css", NO_CTX).length).toBeGreaterThan(0);
+    expect(
+      findingsFor("slop-t7-default-fonts", fx.positive, "css", ctxWith("Body font: Inter (chosen for variable metrics in a data-dense dashboard)")).length,
+    ).toBe(0);
+  });
+
+  it("cp5 emoji-ui is suppressed when DESIGN.md declares an emoji strategy", () => {
+    const fx = FIXTURES["slop-cp5-emoji-ui"]!;
+    expect(findingsFor("slop-cp5-emoji-ui", fx.positive, "html", NO_CTX).length).toBeGreaterThan(0);
+    expect(
+      findingsFor("slop-cp5-emoji-ui", fx.positive, "html", ctxWith("Voice: playful; emoji are part of the brand voice in headings and CTAs")).length,
+    ).toBe(0);
+  });
+
+  it("c5 cream-palette is suppressed under a declared warm-neutral language", () => {
+    const fx = FIXTURES["slop-c5-cream-palette"]!;
+    expect(findingsFor("slop-c5-cream-palette", fx.positive, "css", NO_CTX).length).toBeGreaterThan(0);
+    expect(
+      findingsFor("slop-c5-cream-palette", fx.positive, "css", ctxWith("Palette: warm-neutral, first-party")).length,
+    ).toBe(0);
+  });
+});
+
+describe("inline-ignore", () => {
+  it("design-slop-disable-next-line suppresses the next line", () => {
+    const css = "/* design-slop-disable-next-line slop-m4-transition-all */\n.x { transition: all 200ms; }";
+    expect(findingsFor("slop-m4-transition-all", css, "css").length).toBe(0);
+  });
+
+  it("file-scope design-slop-disable suppresses the whole file", () => {
+    const css = "/* design-slop-disable slop-l8-zindex-magic */\n.a{z-index:9999}\n.b{z-index:999}";
+    expect(findingsFor("slop-l8-zindex-magic", css, "css").length).toBe(0);
+  });
+});