@bongos/core 1.19.478 → 1.19.479

package/tests/credit_ledger_read.mjs

@@ -0,0 +1,347 @@
+// tests/credit_ledger_read.mjs
+//
+// task 1003484 (goal 1000067) — the credit ledger gets a read surface, resolving
+// blocker 1000127. Until this, `credit_log` had NO reader anywhere in the API:
+// every in-tree query was an internal aggregate or an existence probe, so the
+// three ideator streams (ADR 0172) could not be audited from outside at all.
+//
+// What this pins, in the order it matters:
+//
+//   1. THE ANTI-DRIFT GUARD. The stream reason keys EMBED the idea id
+//      (`idea.credit.full_pass:<ideaId>`), because that string is the
+//      idempotency predicate. So per-stream audit is a PREFIX question, and the
+//      prefixes this route publishes are asserted against the actual writers in
+//      credits.js — not against a transcription of them. If someone renames a
+//      reason key, this test fails rather than the audit filter silently
+//      returning nothing forever.
+//   2. The filter SQL: builder scoping, exact vs prefix reason, LIKE-wildcard
+//      escaping (a `%` in a query string must not widen the scan), and the
+//      unpaginated total.
+//   3. The leak rule: reward_basis is session top-up bookkeeping, not money a
+//      reader should see.
+//   4. The two gates: /me/credits takes its builder from the SESSION (there is
+//      no parameter to tamper with), and /builders/:id/credits refuses a caller
+//      without the roster-read atom.
+//
+// Pure — a recording fake pool over the real router, no Postgres, no network
+// beyond a loopback listener. Runs in the DB-free unit gate.
+//
+// Run:  node tests/credit_ledger_read.mjs
+
+import { strict as assert } from 'node:assert';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const CREDITS_SRC = readFileSync(join(ROOT, 'modules/economy/credits.js'), 'utf8');
+
+// ---- the recording fake pool ----------------------------------------------
+//
+// One shared pool object, so the domain's `pool` (destructured once at require
+// time, through the pinned module-api below) and each test's queue are the same
+// thing.
+let queued = [];
+let calls = [];
+const pool = {
+  query: async (text, params) => {
+    calls.push({ text: String(text), params: params || [] });
+    return queued.shift() || { rows: [], rowCount: 0 };
+  },
+};
+function expect(...responses) { queued = responses; calls = []; }
+const lastCall = () => calls[calls.length - 1];
+// Collapse whitespace so an assertion reads like the SQL, not like its indentation.
+const sqlOf = (c) => c.text.replace(/\s+/g, ' ').trim();
+
+// ---- the route over the real domain, with core pinned ----------------------
+
+const SESSION = { id: 77, github_login: 'octo', rank: 'xenos' };
+let permissionGranted = true;    // flipped by the refusal test
+let knownBuilder = true;         // flipped by the 404 test
+
+const helpers = require('../src/bongos/routes/_helpers.js');
+const moduleApiPath = require.resolve('../src/module-api.js');
+require.cache[moduleApiPath] = {
+  id: moduleApiPath, filename: moduleApiPath, loaded: true,
+  exports: {
+    pool,
+    parsePagination: helpers.parsePagination,
+    pageMeta: helpers.pageMeta,
+    parseId: helpers.parseId,
+    validateOrRespond: helpers.validateOrRespond,
+    LIMITS: helpers.LIMITS,
+    // The own-scope stub: a live session, exactly as requireBuilder leaves it.
+    requireBuilder: (req, _res, next) => { req.builder = { ...SESSION }; next(); },
+    // The atom gate, controllable — so the refusal is proven, not assumed.
+    requirePermission: () => (req, res, next) => (
+      permissionGranted ? next() : res.fail('permission_forbidden', 403)
+    ),
+    getBuilderById: async (id) => (knownBuilder ? { id, github_login: 'target' } : null),
+    // Loaded-but-unused by the credit domain at require time.
+    branding: () => ({}),
+    llmPricing: { priceModelUsage: () => ({ totalUsd: 0 }), PRICES: {} },
+  },
+};
+
+const credits = require('../modules/economy/credits.js');
+const buildCreditsRouter = require('../modules/economy/routes/credits.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/gds', buildCreditsRouter());
+const server = app.listen(0, '127.0.0.1');
+await new Promise((r) => server.once('listening', r));
+const port = server.address().port;
+after(() => server.close());
+
+function call(method, path) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, method, path }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null; try { json = JSON.parse(text); } catch { /* non-JSON body */ }
+        resolve({ status: res.statusCode, json, text });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// A ledger row as the SELECT hands it back (window count rides along).
+const row = (over = {}) => ({
+  id: '5', delta: 5, reason: 'idea.credit.full_pass:20', description: null,
+  task_id: null, session_id: null, recorded_at: '2026-09-01T00:00:00.000Z',
+  total_count: 1, ...over,
+});
+
+// ---- 1. the anti-drift guard ----------------------------------------------
+
+test('the published stream prefixes are the REAL writers in credits.js, not a transcription', () => {
+  const p = credits.IDEA_STREAM_REASON_PREFIXES;
+  // Each writer builds its reason as `<prefix>${...}` — assert that exact
+  // template literal is present in the source. A renamed key breaks this test
+  // instead of silently making the audit filter match nothing, forever.
+  for (const [stream, prefix] of Object.entries(p)) {
+    assert.ok(
+      CREDITS_SRC.includes('`' + prefix + '${'),
+      `stream '${stream}' publishes prefix '${prefix}', but no writer in credits.js builds a reason with it`
+    );
+  }
+});
+
+test('all three ideator streams are covered — one missing prefix is one unauditable lane', () => {
+  assert.deepEqual(
+    Object.keys(credits.IDEA_STREAM_REASON_PREFIXES).sort(),
+    ['full_pass', 'governance_pass', 'task_ship'],
+    'ADR 0172 defines exactly three streams; each needs a prefix or it cannot be filtered for'
+  );
+});
+
+test('the prefixes are prefixes, not whole keys — the reason embeds the idea id', () => {
+  for (const prefix of Object.values(credits.IDEA_STREAM_REASON_PREFIXES)) {
+    assert.ok(prefix.endsWith(':'), `'${prefix}' must end at the separator, or it matches nothing`);
+  }
+});
+
+// ---- 2. the filter SQL -----------------------------------------------------
+
+test('an unfiltered read is scoped to the builder, newest-first, and paged', async () => {
+  expect({ rows: [row()] });
+  const out = await credits.creditLedger(77, { limit: 10, offset: 0 });
+  const sql = sqlOf(lastCall());
+  assert.match(sql, /WHERE builder_id = \$1/, 'the ledger is never read unscoped');
+  assert.match(sql, /ORDER BY recorded_at DESC, id DESC/, 'newest first, with id as the stable tiebreak');
+  assert.match(sql, /LIMIT \$2 OFFSET \$3/);
+  assert.deepEqual(lastCall().params, [77, 10, 0]);
+  assert.equal(out.total, 1);
+});
+
+test('total is the UNPAGINATED count, so a caller can tell more rows exist', async () => {
+  expect({ rows: [row({ total_count: 412 }), row({ id: '6', total_count: 412 })] });
+  const out = await credits.creditLedger(77, { limit: 2, offset: 0 });
+  assert.match(sqlOf(lastCall()), /COUNT\(\*\) OVER \(\)::int AS total_count/);
+  assert.equal(out.total, 412, 'the window count, not the page length');
+  assert.equal(out.rows.length, 2);
+});
+
+test('an empty page reports total 0 rather than throwing on rows[0]', async () => {
+  expect({ rows: [] });
+  const out = await credits.creditLedger(77, { limit: 10, offset: 900 });
+  assert.deepEqual(out, { rows: [], total: 0 });
+});
+
+test('reason is an EXACT match — right for the unparameterized keys', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, { reason: 'task.shipped' });
+  assert.match(sqlOf(lastCall()), /reason = \$2/);
+  assert.equal(lastCall().params[1], 'task.shipped');
+});
+
+test('reasonPrefix is a LIKE with an explicit ESCAPE — the per-stream audit filter', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, { reasonPrefix: credits.IDEA_STREAM_REASON_PREFIXES.full_pass });
+  // ESCAPE '\' — one literal backslash, which is what the SQL carries.
+  assert.match(sqlOf(lastCall()), /reason LIKE \$2 ESCAPE '\\'/);
+  // The stream keys contain '_', which is itself a LIKE wildcard — so our OWN
+  // prefix has to be escaped too, or 'full_pass' would also match 'fullXpass'.
+  assert.equal(lastCall().params[1], 'idea.credit.full\\_pass:%', 'anchored at the start, open at the end');
+});
+
+test("a caller's LIKE wildcards are escaped — a '%' cannot widen the scan", async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, { reasonPrefix: '100%_off\\x' });
+  assert.equal(lastCall().params[1], '100\\%\\_off\\\\x%',
+    'every %, _ and backslash is escaped; only the trailing % is ours');
+});
+
+test('filters AND together and number their placeholders in order', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, {
+    reason: 'task.shipped', taskId: 1234, since: '2026-01-01T00:00:00Z', limit: 5, offset: 10,
+  });
+  const sql = sqlOf(lastCall());
+  assert.match(sql, /WHERE builder_id = \$1 AND reason = \$2 AND task_id = \$3 AND recorded_at >= \$4::timestamptz/);
+  assert.match(sql, /LIMIT \$5 OFFSET \$6/);
+  assert.deepEqual(lastCall().params, [77, 'task.shipped', 1234, '2026-01-01T00:00:00Z', 5, 10]);
+});
+
+test('a non-positive builder id reads nothing at all — it never reaches SQL', async () => {
+  expect({ rows: [row()] });
+  const out = await credits.creditLedger(0);
+  assert.deepEqual(out, { rows: [], total: 0 });
+  assert.equal(calls.length, 0, 'a bad id must not turn into an unscoped query');
+});
+
+// ---- 3. the leak rule ------------------------------------------------------
+
+test('reward_basis is never selected — it is bookkeeping, not money a reader should see', async () => {
+  expect({ rows: [] });
+  await credits.creditLedger(77, {});
+  assert.doesNotMatch(sqlOf(lastCall()), /reward_basis/);
+});
+
+test('total_count is stripped from the rows it rode in on', async () => {
+  expect({ rows: [row({ total_count: 9 })] });
+  const out = await credits.creditLedger(77, {});
+  assert.equal(out.total, 9);
+  assert.ok(!('total_count' in out.rows[0]), 'an internal window count is not a ledger field');
+  assert.deepEqual(Object.keys(out.rows[0]).sort(),
+    ['delta', 'description', 'id', 'reason', 'recorded_at', 'session_id', 'task_id']);
+});
+
+// ---- 4. the two gates ------------------------------------------------------
+
+test('GET /me/credits takes its builder from the SESSION — there is no parameter to tamper with', async () => {
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/me/credits?builder_id=999');
+  assert.equal(res.status, 200);
+  assert.equal(res.json.builder_id, 77, 'the session id, never the query string');
+  assert.equal(lastCall().params[0], 77);
+});
+
+test('GET /me/credits serves the stream prefixes beside the rows, so the filter is discoverable', async () => {
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/me/credits');
+  assert.deepEqual(res.json.streams, credits.IDEA_STREAM_REASON_PREFIXES);
+  assert.deepEqual(res.json.page, { limit: 50, offset: 0, total: 1 });
+});
+
+test('the page limit is clamped — the ledger grows forever, so an uncapped read cannot be asked for', async () => {
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/me/credits?limit=100000');
+  assert.equal(res.json.page.limit, 200);
+});
+
+test('a ledger read is never cached — a stale balance is a wrong one', async () => {
+  expect({ rows: [] });
+  const res = await new Promise((resolve, reject) => {
+    http.request({ host: '127.0.0.1', port, method: 'GET', path: '/api/gds/me/credits' }, (r) => {
+      r.resume(); r.on('end', () => resolve(r));
+    }).on('error', reject).end();
+  });
+  assert.equal(res.headers['cache-control'], 'no-store');
+});
+
+test('a caller WITHOUT the roster-read atom cannot read another builder ledger', async () => {
+  permissionGranted = false;
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/builders/999/credits');
+  permissionGranted = true;
+  assert.equal(res.status, 403);
+  assert.equal(calls.length, 0, 'refused before any query — the gate is not decorative');
+});
+
+test('a permitted caller reads the TARGET builder ledger, not their own', async () => {
+  expect({ rows: [row()] });
+  const res = await call('GET', '/api/gds/builders/999/credits');
+  assert.equal(res.status, 200);
+  assert.equal(res.json.builder_id, 999);
+  assert.equal(lastCall().params[0], 999);
+});
+
+test('an unknown builder is a 404, not an empty ledger that reads like "paid nothing"', async () => {
+  knownBuilder = false;
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/builders/999/credits');
+  knownBuilder = true;
+  assert.equal(res.status, 404);
+  assert.equal(res.json.error.code, 'builder_not_found');
+});
+
+test('a non-numeric builder id is refused — /builders/me/credits is not a route', async () => {
+  const res = await call('GET', '/api/gds/builders/me/credits');
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_builder_id');
+});
+
+// ---- 5. bad filters are 400s, not 500s -------------------------------------
+
+test('an unparseable since is a bad request, not a Postgres error surfacing as a 500', async () => {
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/me/credits?since=not-a-date');
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_since');
+  assert.equal(calls.length, 0);
+});
+
+test('a non-positive task_id filter is refused', async () => {
+  const res = await call('GET', '/api/gds/me/credits?task_id=0');
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_task_id');
+});
+
+test('an over-long reason filter is refused rather than passed to the scan', async () => {
+  const res = await call('GET', `/api/gds/me/credits?reason=${'x'.repeat(201)}`);
+  assert.equal(res.status, 400);
+  assert.equal(res.json.error.code, 'bad_reason_filter');
+});
+
+test('the reason_prefix query param reaches the domain as a prefix filter', async () => {
+  expect({ rows: [] });
+  const res = await call('GET', '/api/gds/me/credits?reason_prefix=idea.credit.governance_pass%3A');
+  assert.equal(res.status, 200);
+  assert.equal(lastCall().params[1], 'idea.credit.governance\\_pass:%',
+    "the writer's own '_' is escaped, so it matches literally");
+});
+
+// ---- 6. the port ------------------------------------------------------------
+
+test('the read rides the reward PORT, so a core hall view can resolve it without importing economy', async () => {
+  const reward = require('../modules/economy/reward.js');
+  assert.equal(typeof reward.creditLedger, 'function');
+  expect({ rows: [row()] });
+  const out = await reward.creditLedger(77, { limit: 1 });
+  assert.equal(out.total, 1, 'delegated, not spread — the port reaches the live function');
+});

package/tests/hall_reading_world.mjs

@@ -428,3 +428,83 @@ test('with no repo bases the resolver degrades instead of crashing the page', ()
   assert.equal(resolve('../../CLAUDE.md'), '../../CLAUDE.md',
     'the bases are fetched at boot; before they land a relative href passes through and 404s harmlessly');
 });
+
+// A link target reaches an href only if the reader vouches for its scheme
+// (task 1003482). escapeHtml stops markup, not URI schemes: a `javascript:`
+// target would run on click. Every document the hall renders today is
+// repo-controlled, but the reference room widened what flows through the
+// shared reader, so the door closes before it meets a document someone else
+// wrote. The hostile list carries the shapes a browser's URL parser would
+// still read as a scheme: tab/newline inside, whitespace before, backslashes
+// for slashes.
+const HOSTILE_TARGETS = [
+  'javascript:alert(1)',
+  'JavaScript:alert(1)',
+  'java\tscript:alert(1)',
+  ' javascript:alert(1)',
+  'data:text/html;base64,PHNjcmlwdD5hbGVydCgxKTwvc2NyaXB0Pg==',
+  'vbscript:MsgBox(1)',
+  'file:///etc/passwd',
+  'ftp://example.org/x',
+  '//evil.example/x',
+  '\\\\evil.example/x',
+  '/\\evil.example/x',
+];
+const REPO_BASES = {
+  baseDir: 'docs/onboarding/',
+  getBlobBase: () => 'https://github.com/o/r/blob/main',
+  getTreeBase: () => 'https://github.com/o/r/tree/main',
+};
+const VOUCHED_TARGETS = [
+  ['https://example.org/x', 'https://example.org/x'],
+  ['http://example.org/x', 'http://example.org/x'],
+  ['mailto:hello@example.org', 'mailto:hello@example.org'],
+  ['tel:+15555550100', 'tel:+15555550100'],
+  ['#a-section', '#a-section'],
+  ['../../CLAUDE.md', 'https://github.com/o/r/blob/main/CLAUDE.md'],
+];
+
+test('the allowlist is the reader\'s own, and it is short', () => {
+  const MD = loadReader();
+  for (const [target] of VOUCHED_TARGETS) assert.ok(MD.isAllowedLinkHref(target), `${target} is vouched for`);
+  assert.ok(MD.isAllowedLinkHref('docs/recipes/'), 'a bare relative path is a repo path');
+  assert.ok(MD.isAllowedLinkHref('/docs/recipes/'), 'one leading slash is a repo path, not a host');
+  for (const target of HOSTILE_TARGETS) assert.ok(!MD.isAllowedLinkHref(target), `${JSON.stringify(target)} is refused`);
+});
+
+test('a hostile link target renders as its text, with no <a> at all', () => {
+  const MD = loadReader();
+  const resolvers = {
+    'no bases': MD.makeResolveLinkHref({ baseDir: 'docs/onboarding/' }),
+    'bases up': MD.makeResolveLinkHref(REPO_BASES),
+    identity: (h) => h,
+  };
+  for (const target of HOSTILE_TARGETS) {
+    for (const [name, resolve] of Object.entries(resolvers)) {
+      const { html } = MD.parseMarkdown(`see [the door](${target}) here\n`, resolve);
+      assert.doesNotMatch(html, /<a[\s>]|href=/, `${JSON.stringify(target)} under the ${name} resolver writes no anchor`);
+      // (a `)` inside a target ends the link — the parser's own limit, so
+      // `alert(1)` leaves one behind as text; what matters is no anchor)
+      assert.match(html, /<p>see the door\)? here<\/p>/, `… and the label survives as text`);
+    }
+  }
+});
+
+test('the resolver refuses a hostile target before the repo bases can dress it as a GitHub path', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref(REPO_BASES);
+  for (const target of HOSTILE_TARGETS) {
+    assert.equal(resolve(target), null, `${JSON.stringify(target)} is refused, not rewritten to ${resolve(target)}`);
+  }
+});
+
+test('the vouched shapes still become links, exactly as before', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref(REPO_BASES);
+  for (const [target, href] of VOUCHED_TARGETS) {
+    const { html } = MD.parseMarkdown(`[t](${target})\n`, resolve);
+    assert.ok(html.includes(`<a href="${href}"`), `${target} → ${href}, got ${html}`);
+  }
+  const degraded = MD.parseMarkdown('[t](../../CLAUDE.md)\n', MD.makeResolveLinkHref({ baseDir: 'docs/onboarding/' })).html;
+  assert.ok(degraded.includes('<a href="../../CLAUDE.md"'), 'and with no bases a repo path still degrades to a link, as §10 pins above');
+});

package/tests/own_scope_guard.mjs

@@ -89,6 +89,20 @@ const OWN_SCOPED_SURFACES = [
     why: 'the per-builder preference domain (wandering, skill, sound, render, model-allocation, display name) carved out of /me — read and write, all keyed on req.builder.id.',
     crossOwner: [],
   },
+  {
+    file: 'modules/economy/routes/credits.js',
+    why: 'the credit-ledger read (task 1003484, blocker 1000127). GET /me/credits takes its builder from req.builder.id and never reads an id off the request, so there is no parameter to tamper with. The one cross-owner route names its target in the path and is gate-verified below.',
+    // Two routes, one of them cross-owner — so one own-scoped route is the whole
+    // truth here, not a parser that stopped matching.
+    minOwnScoped: 1,
+    crossOwner: [
+      {
+        path: '/builders/:builderId/credits',
+        gate: /requirePermission\(\s*['"]builder\.roster\.read['"]\s*\)/,
+        why: "itemised read of ANOTHER builder's credit ledger — permission-gated on the builder.roster.read atom, the same gate /builders/:id/active-claims carries for the same act (reading another builder's record off the roster).",
+      },
+    ],
+  },
   {
     file: 'modules/platform-identity/routes/profile.js',
     why: "the builder's OWN cross-project profile controls (hide flag, handle, bio/links) — all keyed on req.builder.github_id.",
@@ -139,6 +153,12 @@ const OWN_SCOPED_SURFACES = [
 
 // Floors that keep this guard from going quietly vacuous (a regex that stops
 // matching would otherwise "pass" by checking nothing).
+//
+// The per-file floor is a DEFAULT, not a law: a surface may declare its own
+// `minOwnScoped` when it genuinely mounts fewer (modules/economy/routes/credits.js
+// is one own-scoped read plus one gated cross-owner read). The floor's job is to
+// notice a file whose routes STOPPED parsing — so what matters is that every
+// surface has a non-zero floor it must clear, not that they all share one number.
 const MIN_OWN_SCOPED_ROUTES_TOTAL = 28;
 const MIN_OWN_SCOPED_ROUTES_PER_FILE = 3;
 
@@ -416,9 +436,11 @@ for (const surface of OWN_SCOPED_SURFACES) {
   }
 
   t(`${surface.file} — contributes a real number of own-scoped routes (not vacuous)`, () => {
+    const floor = surface.minOwnScoped ?? MIN_OWN_SCOPED_ROUTES_PER_FILE;
+    assert.ok(floor > 0, 'a declared floor of 0 would exempt the file from this check entirely');
     assert.ok(
-      ownScopedHere >= MIN_OWN_SCOPED_ROUTES_PER_FILE,
-      `only ${ownScopedHere} own-scoped routes found (floor ${MIN_OWN_SCOPED_ROUTES_PER_FILE}) — either routes moved out or the parser stopped seeing them`
+      ownScopedHere >= floor,
+      `only ${ownScopedHere} own-scoped routes found (floor ${floor}) — either routes moved out or the parser stopped seeing them`
     );
   });
 

package/tests/ui_design_skills.mjs

@@ -8,7 +8,11 @@
 // 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.
+// mandate, and the preamble copies proven not to be doc-entropy debt. Since task 1003327
+// (ADR 0230) it also pins the four LOOKS: each names the style-library entry it was tuned
+// against, declares no colour of its own outside the legal black/white carve-out, adds no
+// face, and keeps the translations that ADR fixed (the archetype that still ships both modes,
+// the deterministic selection, the transcribed colour contract). DB-free.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
@@ -200,6 +204,57 @@ test('the worked example of the image family is the grove specimen: the pair wit
   assert.match(design, /grove-pod\.jpg/, 'the look\'s DESIGN.md names its specimen\'s plate instead of claiming it brings none');
 });
 
+// ── the four looks (task 1003327, ADR 0230): a composition grammar, never a palette ──
+const LOOKS = ['minimalist-ui', 'industrial-brutalist-ui', 'gpt-taste', 'stitch-design-taste'];
+const LIBRARY = ['chrome-world', 'expedition', 'grove'];
+const ownRules = (name) => {
+  const pre = read(path.join(SKILLS, 'PREAMBLE.md')).trimEnd();
+  const text = read(path.join(SKILLS, name, 'SKILL.md'));
+  return text.slice(text.indexOf(pre) + pre.length);
+};
+
+test('the four looks of task 1003327 exist as in-house skills, are declared, and each names the library entry it was tuned against', () => {
+  for (const name of LOOKS) {
+    assert.ok(ownDirs.includes(name), `${name}: skills/${name}/SKILL.md exists`);
+    assert.ok(manifest.contributes.skills.includes(name), `${name}: declared in contributes.skills`);
+    const own = ownRules(name);
+    assert.ok(LIBRARY.some((look) => own.includes(`\`${look}\``)), `${name}: names a style-library entry by directory, so a builder can render the grammar under a real look`);
+    assert.match(own, /1003327/, `${name}: names the port task`);
+    assert.match(own, /ADR 0230/, `${name}: names the look-skill ADR`);
+  }
+});
+
+test('a look skill ships a grammar and no world of its own: no palette of its own, no face, the pack is the source', () => {
+  for (const name of LOOKS) {
+    const own = ownRules(name);
+    // the preamble's only legal literal is pure black or white; every other colour is a var() or a color-mix()
+    const illegal = (own.match(/#[0-9a-fA-F]{3,8}\b/g) || []).filter((h) => !/^#(0{3,8}|f{3,8})$/i.test(h));
+    assert.deepEqual(illegal, [], `${name}: a look skill declares no colour of its own (found ${illegal.join(', ')})`);
+    assert.doesNotMatch(own, /\b(add|load|install|import|declare|register)\s+(an?\s+|the\s+|a new\s+)?(@?font-face|webfont|typeface|font family|google font)/i, `${name}: a look skill adds no face; the pack's two stacks are the type system`);
+    assert.doesNotMatch(own, /https?:\/\/fonts\./i, `${name}: no font host of its own`);
+    assert.match(own, /the pack|instance's pack/i, `${name}: says the palette is the instance's pack`);
+  }
+});
+
+test('each look keeps the translation ADR 0230 fixed: the substrate is an archetype, the selection is deterministic, the document transcribes, the placeholder photography is gone', () => {
+  const brutalist = ownRules('industrial-brutalist-ui');
+  assert.match(brutalist, /the other mode/i, 'brutalist: the substrate became an archetype and the other mode still ships');
+  assert.match(brutalist, /never mixed/i, 'brutalist: the two archetypes are never mixed in one interface');
+  const gpt = ownRules('gpt-taste');
+  assert.match(gpt, /deterministic, not random/i, 'gpt-taste: the selection is deterministic, not a roll');
+  assert.match(gpt, /sibling/i, 'gpt-taste: the selection is checked against sibling surfaces');
+  const stitch = ownRules('stitch-design-taste');
+  assert.match(stitch, /transcrib/i, 'stitch: the colour contract is transcribed from the pack');
+  assert.match(stitch, /diff/i, 'stitch: the thirteen are diffed against the pack, not retyped');
+  for (const name of ['minimalist-ui', 'gpt-taste']) {
+    assert.match(ownRules(name), /seeded placeholder photograph/i, `${name}: names the upstream's seeded placeholder photography, which this port drops`);
+  }
+  const index = read(path.join(ROOT, 'docs', 'adr', 'README.md'));
+  const adr = fs.readdirSync(path.join(ROOT, 'docs', 'adr')).find((f) => f.startsWith('0230-'));
+  assert.ok(adr, 'docs/adr/0230-*.md exists');
+  assert.ok(index.includes(`](${adr})`), 'docs/adr/README.md links ADR 0230');
+});
+
 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) {