@bongos/core 1.19.460 → 1.19.462

package/scripts/gds/docs-entropy.js

@@ -259,8 +259,12 @@ function scanDuplicateProse(relFiles) {
     for (const { text, startLine } of paragraphs) {
       const trimmed = text.trim();
       if (trimmed.length < MIN_DUPE_CHARS) continue;
-      // Skip content that is intentionally generated/duplicated across files
+      // Skip content that is intentionally generated/duplicated across files:
+      // generated blocks, and the ui-design module's PLATFORM PREAMBLE, which
+      // its policy requires byte-identical in every skill it ships (ADR 0198 §4;
+      // tests/ui_design_skills.mjs pins the copies against PREAMBLE.md).
       if (trimmed.startsWith('<!-- BEGIN GENERATED')) continue;
+      if (trimmed.startsWith('<!-- BEGIN PLATFORM PREAMBLE')) continue;
       // Normalize internal whitespace for comparison
       const key = trimmed.replace(/\s+/g, ' ');
       if (!byText.has(key)) byText.set(key, []);

package/src/module-api.js

@@ -33,7 +33,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.460'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.462'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/docs_entropy.mjs

@@ -19,7 +19,7 @@ import path from 'node:path';
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SCANNER = path.join(ROOT, 'scripts', 'gds', 'docs-entropy.js');
-const { collectMarkdownFiles, parseFile } = require(SCANNER); // require.main-guarded → no scan on import
+const { collectMarkdownFiles, parseFile, scanDuplicateProse } = require(SCANNER); // require.main-guarded → no scan on import
 
 test('collectMarkdownFiles passes the glob as an argv array, never a shell string', () => {
   let seen = null;
@@ -138,3 +138,31 @@ test('the real scan on THIS checkout matches the CI baselines (the platform-pari
     + 'on a CRLF checkout this read 21, because every heading in every CRLF file went unparsed',
   );
 });
+
+// The duplicate-prose scan skips content that is DUPLICATED BY POLICY: generated blocks,
+// and the ui-design module's PLATFORM PREAMBLE, which ADR 0198 §4 requires byte-identical
+// in every skill the module ships (task 1003325 / ADR 0220 — four in-house copies would
+// have tripped the doc_duplicate_prose ratchet on the policy working as designed). The
+// skip is a marker prefix, so a plain paragraph beside it in the same two files is still
+// flagged: the calibration that proves the skip is narrow.
+test('scanDuplicateProse skips a paragraph opening with the PLATFORM PREAMBLE marker, and still flags a plain duplicate beside it', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'docs-entropy-preamble-'));
+  const plain = 'A plain paragraph long enough to clear the scanner minimum of one hundred and twenty characters, written into two files so the scan has a real duplicate to report.';
+  const preamble = [
+    '<!-- BEGIN PLATFORM PREAMBLE · a fixture block, long enough to clear the minimum on its own, duplicated on purpose -->',
+    '> **Platform preamble.** Read the world first; this block is byte-identical in every skill the module ships.',
+    '<!-- END PLATFORM PREAMBLE -->',
+  ].join('\n');
+  const generated = '<!-- BEGIN GENERATED fixture --> a generated block long enough to clear the minimum, also duplicated on purpose, also skipped <!-- END GENERATED -->';
+  for (const name of ['a.md', 'b.md']) {
+    fs.writeFileSync(path.join(tmp, name), `# ${name}\n\n${plain}\n\n${preamble}\n\n${generated}\n`);
+  }
+  // scanDuplicateProse resolves each rel against the repo root, so a temp file is
+  // addressed by its relative path from there (path.join normalises the `..` hops).
+  const rel = (f) => path.relative(ROOT, path.join(tmp, f)).split(path.sep).join('/');
+  const dupes = scanDuplicateProse([rel('a.md'), rel('b.md')]);
+  assert.equal(dupes.length, 1, `exactly the plain paragraph is flagged, got ${JSON.stringify(dupes.map((d) => d.snippet.slice(0, 40)))}`);
+  assert.ok(dupes[0].snippet.startsWith('A plain paragraph'), 'the flagged block is the plain paragraph');
+  assert.equal(dupes[0].locations.length, 2, 'seen in both files');
+  fs.rmSync(tmp, { recursive: true, force: true });
+});

package/tests/ui_design_skills.mjs

@@ -4,7 +4,11 @@
 // opens with the PLATFORM PREAMBLE byte-identical to PREAMBLE.md; every name the manifest
 // contributes resolves to a real skill dir; a module-owned skill reaches a builder's
 // materialised .claude/skills with its sidecar (and not when the module is off); /design
-// lists every vendored skill by name; the policy ADR is indexed. DB-free.
+// lists every vendored skill by name; the policy ADR is indexed. Since task 1003325 (ADR
+// 0220) the same file pins the IN-HOUSE rebuilds under skills/<name>/: the same preamble
+// first and once, a `## Rebuilt from` section instead of a sidecar (the spec task, ADR
+// 0198, "no upstream bytes"), the style library named as the palette source, no image
+// mandate, and the preamble copies proven not to be doc-entropy debt. DB-free.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
@@ -93,6 +97,126 @@ test('every vendored SKILL.md opens with the PLATFORM PREAMBLE, byte-identical t
   }
 });
 
+// ── every in-house rebuild: the preamble, the Rebuilt-from section, no sidecar (ADR 0220) ──
+const TASTE_CORE = ['design-taste-frontend', 'design-taste-frontend-v1', 'high-end-visual-design', 'redesign-existing-projects'];
+
+test('the taste core of task 1003325 exists as four in-house skills and every one is declared', () => {
+  for (const name of TASTE_CORE) {
+    assert.ok(ownDirs.includes(name), `${name}: skills/${name}/SKILL.md exists`);
+    assert.ok(manifest.contributes.skills.includes(name), `${name}: declared in contributes.skills`);
+  }
+});
+
+// ── the impeccable method (task 1003326, ADR 0221): one skill, one playbook per sub-command ──
+const IMPECCABLE = path.join(SKILLS, 'impeccable');
+const IMPECCABLE_SUBCOMMANDS = ['shape', 'audit', 'critique', 'polish', 'harden', 'animate', 'typeset', 'colorize', 'layout', 'adapt', 'distill', 'clarify', 'onboard', 'optimize', 'document', 'extract'];
+
+test('impeccable is one in-house skill whose sixteen sub-commands each own exactly one playbook under reference/', () => {
+  assert.ok(ownDirs.includes('impeccable'), 'skills/impeccable/SKILL.md exists');
+  assert.ok(manifest.contributes.skills.includes('impeccable'), 'declared in contributes.skills');
+  const skill = read(path.join(IMPECCABLE, 'SKILL.md'));
+  const refDir = path.join(IMPECCABLE, 'reference');
+  const onDisk = fs.readdirSync(refDir).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')).sort();
+  for (const sub of IMPECCABLE_SUBCOMMANDS) {
+    assert.ok(onDisk.includes(sub), `reference/${sub}.md exists (the task body names it)`);
+    assert.ok(skill.includes(`reference/${sub}.md`), `SKILL.md routes \`${sub}\` to its playbook`);
+  }
+  for (const ref of onDisk) assert.ok(skill.includes(`reference/${ref}.md`), `reference/${ref}.md is routed from SKILL.md (no orphan playbook)`);
+  for (const ref of onDisk) {
+    const text = read(path.join(refDir, `${ref}.md`));
+    assert.ok(!text.includes(policy.preamble.begin), `reference/${ref}.md carries no preamble copy (the block is pinned once, in SKILL.md, and governs every playbook)`);
+    assert.ok(text.trim().length > 400, `reference/${ref}.md is a playbook, not a stub`);
+  }
+});
+
+test('impeccable carries none of the behaviour that made its origin dangerous: no hooks, no bypass agent, no telemetry, no remote bundle, no live-server token', () => {
+  const files = [path.join(IMPECCABLE, 'SKILL.md'), ...fs.readdirSync(path.join(IMPECCABLE, 'reference')).map((f) => path.join(IMPECCABLE, 'reference', f))];
+  for (const f of files) {
+    const text = read(f);
+    const rel = path.relative(ROOT, f).split(path.sep).join('/');
+    assert.doesNotMatch(text, /bypassPermissions|--dangerously-skip-permissions/, `${rel}: no permission bypass`);
+    assert.doesNotMatch(text, /\b(write|add|install|register)\b[^.\n]{0,60}\b(PostToolUse|PreToolUse|Stop)\b[^.\n]{0,40}\bhooks?\b/i, `${rel}: no step writes a hook into a harness config`);
+    assert.doesNotMatch(text, /\b(write|edit|patch)\b[^.\n]{0,40}\bsettings(\.local)?\.json\b/i, `${rel}: no step edits settings.json`);
+    assert.doesNotMatch(text, /\b(enable|send|collect|report|emit)s?\b[^.\n]{0,40}\btelemetry\b|\btelemetry\b[^.\n]{0,40}\b(is|are|stays|defaults?)\s+(on|enabled|sent)\b/i, `${rel}: no step turns on or sends telemetry (naming the ban is fine; directing it is not)`);
+    assert.doesNotMatch(text, /\b(curl|wget|fetch|download)\b[^.\n]{0,60}\bhttps?:\/\//i, `${rel}: no remote bundle download`);
+    assert.doesNotMatch(text, /\b(auth|access|bearer|helper)\s+token\b/i, `${rel}: no live-server token`);
+    assert.doesNotMatch(text, /(disregard|ignore)\b[^.\n]{0,40}\b(system prompt|harness)/i, `${rel}: no instruction-override directive`);
+  }
+  const skill = read(path.join(IMPECCABLE, 'SKILL.md'));
+  assert.match(skill, /playwright/i, 'the live loop is the playwright plugin, named as a prerequisite');
+  assert.match(skill, /kit\/render\.js/, 'the headless loop is the kit');
+  assert.match(skill, /1003329/, 'the detector is named as its own task, not shipped here');
+});
+
+test('every in-house SKILL.md opens with the PLATFORM PREAMBLE, byte-identical to PREAMBLE.md, exactly once, right after its frontmatter', () => {
+  const pre = read(path.join(SKILLS, 'PREAMBLE.md')).trimEnd();
+  for (const name of ownDirs) {
+    const text = read(path.join(SKILLS, name, 'SKILL.md'));
+    const fm = text.match(/^---\n[\s\S]*?\n---\n/);
+    assert.ok(fm, `${name}: SKILL.md keeps its frontmatter first`);
+    const body = text.slice(fm[0].length).replace(/^\n+/, '');
+    assert.ok(body.startsWith(pre), `${name}: the preamble block is the first thing after the frontmatter and matches PREAMBLE.md byte for byte`);
+    assert.equal(text.split(policy.preamble.begin).length, 2, `${name}: the preamble appears exactly once`);
+  }
+});
+
+test('every in-house skill names its dir, carries a description, and says what it was rebuilt from instead of carrying a sidecar', () => {
+  const pre = read(path.join(SKILLS, 'PREAMBLE.md')).trimEnd();
+  for (const name of ownDirs) {
+    const dir = path.join(SKILLS, name);
+    const text = read(path.join(dir, 'SKILL.md'));
+    const fm = frontmatter(text);
+    assert.equal(fm.name, name, `${name}: frontmatter names its own dir`);
+    assert.ok(fm.description && fm.description.length > 80, `${name}: a description the harness can route on`);
+    assert.ok(!fs.existsSync(path.join(dir, policy.sidecar)), `${name}: an in-house skill claims no upstream, so no ${policy.sidecar}`);
+    assert.ok(!fs.existsSync(path.join(dir, 'LICENSE')), `${name}: no upstream licence text travels with a rebuild`);
+    const afterPreamble = text.slice(text.indexOf(pre) + pre.length);
+    const section = afterPreamble.match(/^## Rebuilt from\n([\s\S]*?)(?=\n## )/m);
+    assert.ok(section, `${name}: a "## Rebuilt from" section is the first thing after the preamble`);
+    assert.match(afterPreamble.trimStart(), /^## Rebuilt from\n/, `${name}: nothing sits between the preamble and the Rebuilt-from section`);
+    assert.match(section[1], /builders#\/task\/\d+/, `${name}: the section links the spec task`);
+    assert.match(section[1], /ADR 0198/, `${name}: the section names the vendoring policy that made it a rebuild`);
+    assert.match(section[1], /REBUILD-SPEC/, `${name}: the section names the spec`);
+    assert.match(section[1], /no upstream bytes/i, `${name}: the section states no upstream bytes were consulted or copied`);
+    assert.match(section[1], /what changed in translation/i, `${name}: the section says where the rebuild departs from the documented behaviour`);
+  }
+});
+
+test('every in-house skill works inside the world: the style library is the palette source, images are hero plates only, and no step mandates generating one', () => {
+  const pre = read(path.join(SKILLS, 'PREAMBLE.md')).trimEnd();
+  for (const name of ownDirs) {
+    const text = read(path.join(SKILLS, name, 'SKILL.md'));
+    const own = text.slice(text.indexOf(pre) + pre.length); // the skill's own rules, not the shared block
+    assert.ok(own.includes('modules/ui-design/styles/'), `${name}: names the style library as where a variant comes from`);
+    assert.match(own, /hero plates/i, `${name}: restates the owner's imagery rule in its own rules`);
+    assert.doesNotMatch(own, /\b(must|always|first|then)\s+generate\s+(an?\s+|the\s+)?(image|asset|photo|render)/i, `${name}: no step mandates image generation (ADR 0198's panel finding; the owner's rule)`);
+    assert.doesNotMatch(own, /\b(use|add|insert|prefer|fall back to|source)\s+(seeded\s+)?placeholder (photo|imag)/i, `${name}: no step reaches for seeded placeholder photography (naming the ban is fine; directing it is not)`);
+    assert.match(own, /Kill Switch|prefers-reduced-motion/, `${name}: its motion rules name the switch they live inside`);
+    assert.match(own, /kit\/render\.js/, `${name}: the kit's render is its pre-flight`);
+  }
+});
+
+test('the preamble copies are policy, not doc-entropy debt: the scanner skips the block and still flags a plain duplicate', () => {
+  const de = require(path.join(ROOT, 'scripts', 'gds', 'docs-entropy.js'));
+  const carriers = ['modules/ui-design/skills/PREAMBLE.md', ...ownDirs.map((n) => `modules/ui-design/skills/${n}/SKILL.md`)];
+  assert.ok(carriers.length >= 2, 'at least one own skill carries the block beside PREAMBLE.md');
+  for (const rel of carriers) assert.ok(read(path.join(ROOT, rel)).includes(policy.preamble.begin), `${rel} carries the block`);
+  const dupes = de.scanDuplicateProse(carriers);
+  assert.ok(!dupes.some((d) => d.snippet.startsWith(policy.preamble.begin)), 'the byte-identical preamble is not reported as duplicate prose');
+  // calibration: the same scanner over the same files still sees a plain paragraph twice
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ui-skills-dupe-'));
+  const para = 'A plain paragraph long enough to clear the scanner\'s 120-character floor, written twice so the duplicate-prose scan has something real to report.';
+  const a = path.join(tmp, 'a.md');
+  const b = path.join(tmp, 'b.md');
+  fs.writeFileSync(a, `# a\n\n${para}\n\n${read(path.join(SKILLS, 'PREAMBLE.md'))}`);
+  fs.writeFileSync(b, `# b\n\n${para}\n\n${read(path.join(SKILLS, 'PREAMBLE.md'))}`);
+  const rel = (p) => path.relative(ROOT, p).split(path.sep).join('/');
+  const control = de.scanDuplicateProse([rel(a), rel(b)]);
+  assert.equal(control.length, 1, 'the plain paragraph is flagged once');
+  assert.ok(control[0].snippet.startsWith('A plain paragraph'), 'and it is the plain paragraph, not the preamble');
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
 // ── the manifest declares what is on disk, and nothing else ─────────────────
 test('every skill the manifest contributes resolves to a skill dir (core .claude/skills or the module), and every module skill dir is declared', () => {
   const declared = manifest.contributes.skills;
@@ -145,24 +269,31 @@ test('a module-owned skill lands in a materialised .claude/skills with its sidec
 });
 
 // ── the doors: /design lists them, the README rosters them, the ADR is indexed ──
-test('/design lists every vendored skill by name, one line each, and names the playwright plugin as a prerequisite', () => {
+test('/design lists every module skill (vendored or in-house) by name, one line each, and names the playwright plugin as a prerequisite', () => {
   const design = read(path.join(ROOT, '.claude', 'skills', 'design', 'SKILL.md'));
-  for (const name of vendoredDirs) {
+  for (const name of [...vendoredDirs, ...ownDirs]) {
     const line = design.split('\n').find((l) => l.includes(`\`/${name}\``) || l.includes(`**${name}**`));
     assert.ok(line, `/design names ${name} on a line of its own`);
   }
   assert.match(design, /playwright/i, '/design names the playwright plugin');
 });
 
-test('the skills README rosters every vendored skill and every rebuild spec by name', () => {
+test('the skills README and the module CLAUDE.md roster every module skill by name', () => {
   const readme = read(path.join(SKILLS, 'README.md'));
-  for (const name of vendoredDirs) assert.ok(readme.includes(`\`${name}\``), `README rosters ${name}`);
+  const claude = read(path.join(MODULE, 'CLAUDE.md'));
+  for (const name of [...vendoredDirs, ...ownDirs]) {
+    assert.ok(readme.includes(`\`${name}\``), `README rosters ${name}`);
+    assert.ok(claude.includes(`\`${name}\``), `modules/ui-design/CLAUDE.md names ${name}`);
+  }
   assert.ok(readme.includes('policy.json') && readme.includes('PREAMBLE.md') && readme.includes('PROVENANCE.md'));
+  assert.ok(readme.includes('Rebuilt from'), 'the README says what a rebuild carries instead of a sidecar');
 });
 
-test('the vendoring policy ADR exists and is indexed', () => {
-  const adr = fs.readdirSync(path.join(ROOT, 'docs', 'adr')).find((f) => /^0198-/.test(f));
-  assert.ok(adr, 'docs/adr/0198-*.md exists');
+test('the vendoring-policy ADR and the in-house-rebuild ADR exist and are indexed', () => {
   const index = read(path.join(ROOT, 'docs', 'adr', 'README.md'));
-  assert.ok(index.includes(`](${adr})`), 'docs/adr/README.md links the ADR');
+  for (const n of ['0198', '0220']) {
+    const adr = fs.readdirSync(path.join(ROOT, 'docs', 'adr')).find((f) => f.startsWith(`${n}-`));
+    assert.ok(adr, `docs/adr/${n}-*.md exists`);
+    assert.ok(index.includes(`](${adr})`), `docs/adr/README.md links ADR ${n}`);
+  }
 });