Add concept world catalog and review workflow

AI-assisted: prepared by Codex at Paul's request.
This commit is contained in:
Paul Bakaus
2026-07-18 14:12:05 -07:00
parent 77c7d8e0fc
commit 2b1f36c43e
576 changed files with 45547 additions and 30979 deletions
File diff suppressed because it is too large Load Diff
+571
View File
@@ -0,0 +1,571 @@
{
"schemaVersion": 1,
"comment": "Human review decisions keyed by stable concept ID. Missing entries are pending and ineligible for challenger sampling.",
"reviews": {
"broadcast-programming-cinema-s-projection-booth-reel-change-cue-sheets": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-cinema-ticket-stub": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-photographic-slide-carousel-and-its-typed-index-card": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-printed-tv-programme-guide": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-radio-station-s-program-log-and-request-line-cards": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-shortwave-listener-s-qsl-card-collection-and-frequen": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-teletext-service": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-video-rental-shop": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-vintage-radio-receiver-plate": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"broadcast-programming-vinyl-double-album-gatefold": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-ballot-paper": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-bank-passbook": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-bank-statement": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-botanist-s-herbarium-sheet": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-cadastral-survey-map": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-census-questionnaire": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-court-transcript": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-customs-declaration-form": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-double-entry-ledger": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-expedition-s-field-notebook": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-industrial-standards-sheet": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-laboratory-notebook": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-legal-case-file": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-library-card-catalog": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-passport-booklet": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-patent-folio": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-repair-manual-s-exploded-parts-diagrams": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-ship-s-log": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-shipping-manifest": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-telephone-directory": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-title-deed-and-property-survey": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"civic-legal-governance-utility-bill": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-atlas-plate": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-broadsheet-newspaper-s-sports-section": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-classified-ads-section": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-comic-book-page": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-dictionary-spread": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-encyclopedia-double-spread": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-farmer-s-almanac": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-fashion-lookbook": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-literary-journal-s-table-of-contents": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-mail-order-catalog": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-naturalist-s-field-guide": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-paperback-s-back-cover-and-front-matter": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-pharmacopoeia-monograph": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-storyboard-sheet": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-theater-playbill": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"editorial-news-serial-zine": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-bingo-hall-s-number-board-and-dabbed-cards": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-board-game-s-rulebook": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-chess-annotation-sheet": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-crossword-page": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-kanban-board": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-loteri-a-board": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-perpetual-calendar": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-scorekeeper-s-baseball-scorecard": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-tarot-spread": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"games-play-tournament-bracket": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-african-block-print-textile-grid": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-annotated-manuscript-folio": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-aztec-tribute-codex": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-brazilian-cordel-chapbook": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-chinese-accordion-fold-book": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-east-asian-handscroll": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-ethiopian-codex-spread": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-indian-palm-leaf-manuscript": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-islamic-geometric-tile-system": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-japanese-bento-box-partition": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-korean-folding-screen": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-persian-manuscript-page": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-sheet-music": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-stamp-collector-s-album": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"global-manuscripts-knowledge-vintage-postcard-back": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-aircraft-preflight-checklist": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-camera-viewfinder-overlay": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-darkroom-contact-sheet": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-hospital-patient-chart": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-medical-triage-chart": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-mission-control-status-wall": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-oscilloscope-faceplate": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-patch-bay-diagram": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-periodic-table": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-recording-studio-mixing-console": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-seismograph-station-s-drum-recorders-and-event-logs": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-ship-s-bridge-instrument-panel": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-sonar-sweep-display": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"industrial-control-weather-station-s-synoptic-chart": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-airport-departures-board": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-botanical-garden-trail-map": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-emergency-evacuation-plan": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-harbor-s-tide-table-board-and-small-craft-advisories": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-metro-system-s-map-and-station-signage": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-motorway-sign-gantry": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-museum-gallery-directory": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-national-park-trailhead-kiosk": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-parking-garage-level-guide": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-pilgrimage-route-map": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-race-circuit-s-pit-wall-timing-screens": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-rail-platform-sign-system": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-supermarket-planogram": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"mapping-navigation-theater-s-lobby-cards-and-marquee": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-auction-house-catalog": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-coupon-sheet": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-hardware-store-s-parts-drawers": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-mail-order-seed-catalog": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-market-price-board": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-matchbook-and-cigar-band-graphics": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-pharmacy-prescription-label-and-patient-information": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-produce-market-s-chalkboard-price-signs-and-crate-si": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-recipe-card": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-restaurant-order-rail": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-restaurant-order-ticket": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
},
"retail-packaging-service-seed-packet-s-front-and-back-panels": {
"status": "approved",
"reviewedBy": "pbakaus",
"reviewedAt": "2026-07-18T00:00:00.000Z"
}
}
}
+92 -58
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env node
/**
* External concept seed: the dice half of new-work's world and surface
* selection procedures.
* External concept seed: the dice half of new-work's coupled-direction and
* established-world surface procedures.
*
* The model derives a grounded shortlist of candidate FORMS from the
* audience's world and the subject's cultural home (see
@@ -23,94 +23,128 @@
* material and win over thin categories, which is the intended shape.
*
* Usage:
* node scripts/concept-seed.mjs --scope surface
* node scripts/concept-seed.mjs --scope world --from <key>
* node scripts/concept-seed.mjs --scope direction
* node scripts/concept-seed.mjs --scope surface --from <key>
*
* Env vars:
* IMPECCABLE_CONCEPT_SEED — same as --from; for reproducible eval runs.
*/
import crypto from 'node:crypto';
import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import {
approvedPoolRevision,
deterministicRank,
readConceptCatalog,
} from './lib/concept-catalog.mjs';
const here = dirname(fileURLToPath(import.meta.url));
const pool = JSON.parse(readFileSync(join(here, 'concept-ingredients.json'), 'utf8'));
const { concepts } = readConceptCatalog(
join(here, 'concept-ingredients.json'),
join(here, 'concept-reviews.json')
);
const args = process.argv.slice(2);
const fromIdx = args.indexOf('--from');
const scopeIdx = args.indexOf('--scope');
const scope = scopeIdx !== -1 ? args[scopeIdx + 1] : 'surface';
if (scope !== 'surface' && scope !== 'world') {
process.stderr.write('concept-seed: --scope must be world or surface\n');
process.exit(1);
}
// When no key is supplied, generate one and print it: a user reporting a
// bad outcome can hand us the key and we replay the exact roll.
const key = fromIdx !== -1
? args[fromIdx + 1]
: (process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex'));
function hashUnit(k, salt) {
const h = crypto.createHash('sha256').update(`${scope}:${salt}:${k}`).digest();
return h.readUInt32BE(0) / 0xffffffff;
}
const unit = (salt) => hashUnit(key, salt);
const buildIndex = 3 + Math.floor(unit('index') * 5); // 3..7
const entries = Object.entries(pool)
.filter(([k]) => !k.startsWith('_'))
.flatMap(([, list]) => list);
const picks = [];
const taken = new Set();
for (let i = 0; picks.length < 3 && i < 60; i++) {
const idx = Math.floor(unit(`challenger-${i}`) * entries.length) % entries.length;
if (!taken.has(idx)) {
taken.add(idx);
picks.push(entries[idx]);
export function selectApprovedChallengers({ scope, key, sourceConcepts = concepts }) {
const approved = sourceConcepts.filter(concept => concept.status === 'approved');
const approvedByFamily = new Map();
for (const concept of approved) {
const family = approvedByFamily.get(concept.familyId) || [];
family.push(concept);
approvedByFamily.set(concept.familyId, family);
}
if (approvedByFamily.size < 3) {
throw new Error('concept-seed: at least three families need approved concepts');
}
const familyIds = deterministicRank(
[...approvedByFamily.keys()].map(id => ({ id })),
`${scope}:${key}:families`
).slice(0, 3).map(item => item.id);
const picks = familyIds.map((familyId, index) => deterministicRank(
approvedByFamily.get(familyId),
`${scope}:${key}:challenger-${index}`
)[0]);
return {
approved,
picks,
poolRevision: approvedPoolRevision(sourceConcepts),
};
}
const promotedInstruction = scope === 'world'
? `After ordering the grounded visual-world candidates by product fit, promote
candidate ${buildIndex} into the serious shortlist. Present it beside the
strongest materially different candidates and let the user select or revise
the durable world. It must survive navigation, quiet and dense content,
interaction and state, and a surface unlike the current request.`
export function renderConceptSeed({
scope = 'surface',
key = process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex'),
} = {}) {
if (scope !== 'surface' && scope !== 'direction') {
throw new Error('concept-seed: --scope must be direction or surface');
}
const unit = (salt) => {
const h = crypto.createHash('sha256').update(`${scope}:${salt}:${key}`).digest();
return h.readUInt32BE(0) / 0xffffffff;
};
const buildIndex = 3 + Math.floor(unit('index') * 5); // 3..7
const { approved, picks, poolRevision } = selectApprovedChallengers({ scope, key });
const promotedInstruction = scope === 'direction'
? `After ordering the grounded coupled directions by product fit, promote
candidate ${buildIndex} into the serious shortlist. Each candidate must join
a durable visual system to a concrete expression for the requested first
surface; select or revise that pair as one decision. It must survive the
current task plus navigation, quiet and dense content, interaction and state,
and a substantially different future surface.`
: `After ordering the task's grounded structural candidates by resonance,
promote candidate ${buildIndex} into the serious shortlist. In an attended
run, present it beside the strongest materially different candidates and
let the user select or revise the surface concept. In a truly unattended
run, use it when it survives audience identification and product clarity.`;
const challengerInstruction = scope === 'world'
? `A challenger enters the world shortlist only when its structure can become
reusable identity grammar across the product, not a one-page costume. Weigh
product identification, product clarity, and cross-surface system breadth.`
const challengerInstruction = scope === 'direction'
? `Translate each challenger's organizing logic into reusable identity grammar
and a strong first-surface structure before judging it. Noticeable form is
allowed when the product stays clear. Compare only audience identification
and product clarity.`
: `A challenger wins only when it beats the grounded list on both audience
identification and product clarity. It may change task topology or
interaction, but never the committed visual identity.`;
const authorityInstruction = scope === 'world'
? `PRODUCT.md and explicit incumbent brand commitments constrain every world.
The seed never chooses exact colors, fonts, tokens, or a user preference.`
const authorityInstruction = scope === 'direction'
? `PRODUCT.md and explicit incumbent brand commitments constrain every coupled
direction. The seed never chooses exact colors, fonts, tokens, or a user
preference, and it never permits the world and first surface to be selected
independently.`
: `PRODUCT.md and DESIGN.md constrain every surface candidate's identity
vocabulary; they do not cancel task-level composition. The seed never
authorizes a new palette, type system, material world, or unfamiliar control
behavior.`;
process.stdout.write(`${scope.toUpperCase()} CONCEPT SEED (key: ${key}; rerun with --scope ${scope} --from ${key} to reproduce this roll)
return `${scope.toUpperCase()} CONCEPT SEED (key: ${key}; approved pool: ${poolRevision}; ${approved.length}/${concepts.length} human-approved; rerun with --scope ${scope} --from ${key} to reproduce this roll against this catalog revision)
PROMOTED INDEX: ${buildIndex}
${promotedInstruction}
The promotion exists to refuse the model's ranking rut, not to outrank the
user or the brief.
user or the brief. Never expose promotion metadata in choice labels or order.
CHALLENGERS:
1. ${picks[0]}
2. ${picks[1]}
3. ${picks[2]}
1. ${picks[0].form}
2. ${picks[1].form}
3. ${picks[2].form}
${challengerInstruction}
${authorityInstruction}
A user- or brief-pinned decision beats the roll, always.
`);
`;
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const args = process.argv.slice(2);
const fromIdx = args.indexOf('--from');
const scopeIdx = args.indexOf('--scope');
try {
process.stdout.write(renderConceptSeed({
scope: scopeIdx !== -1 ? args[scopeIdx + 1] : 'surface',
key: fromIdx !== -1
? args[fromIdx + 1]
: (process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex')),
}));
} catch (error) {
process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
process.exitCode = 1;
}
}
+70 -1
View File
@@ -25,7 +25,8 @@ import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { parseTargetOptions } from './lib/target-args.mjs';
import { IMPECCABLE_COMMAND } from './lib/provider.mjs';
import { IMPECCABLE_COMMAND, IMPECCABLE_PROVIDER_ID } from './lib/provider.mjs';
import { renderLlmOnlySlopReview } from './lib/slop-review.mjs';
import { resolveSurfaceBrief } from './lib/surface-briefs.mjs';
const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
@@ -1051,6 +1052,7 @@ async function cli() {
];
appendSurfaceBriefContext(parts, ctx);
parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
appendHookFallback(parts, ctx);
if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
parts.push(buildMissingTargetDirective());
}
@@ -1064,6 +1066,7 @@ async function cli() {
}
appendSurfaceBriefContext(parts, ctx);
parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
appendHookFallback(parts, ctx);
if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
parts.push(buildMissingTargetDirective());
}
@@ -1111,6 +1114,72 @@ function pathExistsForTarget(cwd, targetPath) {
return fs.existsSync(abs);
}
const HOOK_MANIFESTS_BY_PROVIDER = Object.freeze({
'claude-code': ['.claude/settings.local.json', '.claude/settings.json'],
codex: ['.codex/hooks.json'],
agents: ['.codex/hooks.json'],
cursor: ['.cursor/hooks.json'],
github: ['.github/hooks/impeccable.json'],
});
function truthyEnv(value) {
return typeof value === 'string' && /^(1|true|yes|on)$/i.test(value.trim());
}
function valueHasHookMarker(value) {
if (typeof value === 'string') {
return value.includes('skills/impeccable/scripts/hook.mjs')
|| value.includes('skills/impeccable/scripts/hook-before-edit.mjs');
}
if (Array.isArray(value)) return value.some(valueHasHookMarker);
if (value && typeof value === 'object') return Object.values(value).some(valueHasHookMarker);
return false;
}
function hookEnabledAt(root) {
if (truthyEnv(process.env.IMPECCABLE_HOOK_DISABLED)) return false;
let enabled = true;
for (const name of ['.impeccable/config.json', '.impeccable/config.local.json']) {
const raw = readJson(path.join(root, name));
if (raw?.hook && Object.prototype.hasOwnProperty.call(raw.hook, 'enabled')) {
enabled = raw.hook.enabled !== false;
}
}
return enabled;
}
const STOP_REVIEW_PROVIDERS = new Set(['claude-code', 'codex', 'agents']);
function automaticHookMode(ctx) {
if (ctx.platform === 'ios' || ctx.platform === 'android' || ctx.platform === 'adaptive') {
return 'none';
}
const activeRoot = path.resolve(ctx.projectRoot || process.cwd());
if (!hookEnabledAt(activeRoot)) return 'none';
const manifests = HOOK_MANIFESTS_BY_PROVIDER[IMPECCABLE_PROVIDER_ID] || [];
const roots = [...new Set([process.cwd(), ctx.projectRoot, ctx.repoRoot].filter(Boolean).map((root) => path.resolve(root)))];
for (const root of roots) {
for (const rel of manifests) {
const raw = readJson(path.join(root, rel));
if (raw?.hooks && valueHasHookMarker(raw.hooks)) {
return STOP_REVIEW_PROVIDERS.has(IMPECCABLE_PROVIDER_ID) ? 'stop' : 'per-edit';
}
}
}
return 'none';
}
function appendHookFallback(parts, ctx) {
const hookMode = automaticHookMode(ctx);
if (hookMode === 'stop') return;
const native = ctx.platform === 'ios' || ctx.platform === 'android' || ctx.platform === 'adaptive';
parts.push(renderLlmOnlySlopReview({
automaticDetector: hookMode === 'per-edit',
manualDetector: hookMode === 'none' && !native,
scriptsPath: path.dirname(fileURLToPath(import.meta.url)),
}));
}
function buildResolvedContextDirective(ctx, options, { targetExists = null } = {}) {
const targetPath = hasTargetOption(options) ? options.targetPath : null;
return `RESOLVED_CONTEXT:\n${JSON.stringify({
+26 -2
View File
@@ -46,6 +46,7 @@ import path from 'node:path';
import { pathToFileURL, fileURLToPath } from 'node:url';
import { extractPlatform, loadContext } from './context.mjs';
import { IMPECCABLE_COMMAND } from './lib/provider.mjs';
import { renderStopSlopReview } from './lib/slop-review.mjs';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
@@ -2008,9 +2009,22 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
return result({ skipped: 'native-platform', platform, durationMs: Date.now() - started });
}
const session = ensureSession(cache, sessionId);
const needsSlopReview = session.llmSlopReviewed !== true;
const det = detector || await loadDetector();
if (!det || typeof det.detectText !== 'function') {
return result({ skipped: 'detector-missing', durationMs: Date.now() - started });
if (!needsSlopReview) return result({ skipped: 'detector-missing', durationMs: Date.now() - started });
session.llmSlopReviewed = true;
session.updatedAt = Date.now();
persistCache(projectCwd, cache);
const text = renderStopSlopReview();
return {
exitCode: 0,
stdout: payload(text, 'Stop', harness),
emission: { kind: 'stop-llm-slop-review', llmSlopReview: true },
audit: { ...audit, emitted: true, detectorMissing: true, llmSlopReview: true, chars: text.length, durationMs: Date.now() - started },
};
}
const scanOptions = designSystemOptions(config, det, projectCwd);
@@ -2071,10 +2085,15 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
}
audit.scannedFiles = scanned;
if (freshGroups.length === 0 && contractEntries.length === 0) {
if (freshGroups.length === 0 && contractEntries.length === 0 && !needsSlopReview) {
return result({ emitted: false, skipped: 'stop-clean', durationMs: Date.now() - started });
}
if (needsSlopReview) {
session.llmSlopReviewed = true;
session.updatedAt = Date.now();
}
// Fresh findings and first-time contract audits earn the cache write;
// both mark this batch as surfaced so the next Stop fire is silent
// unless new issues appear.
@@ -2089,6 +2108,9 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
if (contractEntries.length > 0) {
parts.push(renderContractAudit(contractEntries, { cwd: projectCwd }));
}
if (needsSlopReview) {
parts.push(renderStopSlopReview());
}
const text = appendDesignSystemNote(parts.join('\n\n'), scanOptions);
return {
exitCode: 0,
@@ -2099,6 +2121,7 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
...(contractEntries.length > 0
? { contractFiles: contractEntries.map((entry) => entry.filePath) }
: {}),
...(needsSlopReview ? { llmSlopReview: true } : {}),
},
audit: {
...audit,
@@ -2106,6 +2129,7 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
freshFiles: freshGroups.length,
freshFindings: freshGroups.reduce((sum, group) => sum + group.findings.length, 0),
...(contractEntries.length > 0 ? { contractAudits: contractEntries.length } : {}),
...(needsSlopReview ? { llmSlopReview: true } : {}),
chars: text.length,
durationMs: Date.now() - started,
},
+159
View File
@@ -0,0 +1,159 @@
import crypto from 'node:crypto';
import { readFileSync } from 'node:fs';
export const CONCEPT_STATUSES = new Set(['approved', 'rejected']);
export function normalizeConceptForm(value) {
return String(value || '')
.normalize('NFKD')
.toLowerCase()
.replace(/[’‘]/g, "'")
.replace(/[^a-z0-9]+/g, ' ')
.trim();
}
export function readConceptCatalog(catalogPath, reviewsPath) {
const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
const reviewData = JSON.parse(readFileSync(reviewsPath, 'utf8'));
const reviews = reviewData.reviews || {};
const concepts = [];
for (const family of catalog.families || []) {
for (const concept of family.concepts || []) {
concepts.push({
...concept,
familyId: family.id,
familyLabel: family.label,
status: reviews[concept.id]?.status || 'pending',
review: reviews[concept.id] || null,
});
}
}
return { catalog, reviewData, reviews, concepts };
}
export function validateConceptCatalog(catalog, reviewData, { expectedTotal, minimumTotal } = {}) {
const errors = [];
const warnings = [];
const familyIds = new Set();
const conceptIds = new Set();
const normalizedForms = new Map();
const concepts = [];
if (!Number.isInteger(catalog?.schemaVersion) || catalog.schemaVersion < 1) {
errors.push('catalog.schemaVersion must be a positive integer');
}
if (typeof catalog?.catalogVersion !== 'string' || !catalog.catalogVersion.trim()) {
errors.push('catalog.catalogVersion must be a non-empty string');
}
if (!Array.isArray(catalog?.families) || catalog.families.length < 3) {
errors.push('catalog.families must contain at least three families');
}
for (const family of catalog?.families || []) {
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(family.id || '')) {
errors.push(`invalid family id: ${String(family.id)}`);
} else if (familyIds.has(family.id)) {
errors.push(`duplicate family id: ${family.id}`);
}
familyIds.add(family.id);
if (typeof family.label !== 'string' || !family.label.trim()) {
errors.push(`family ${family.id || '(unknown)'} needs a label`);
}
if (!Array.isArray(family.concepts) || family.concepts.length === 0) {
errors.push(`family ${family.id || '(unknown)'} has no concepts`);
continue;
}
for (const concept of family.concepts) {
concepts.push(concept);
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(concept.id || '')) {
errors.push(`invalid concept id: ${String(concept.id)}`);
} else if (conceptIds.has(concept.id)) {
errors.push(`duplicate concept id: ${concept.id}`);
}
conceptIds.add(concept.id);
const normalized = normalizeConceptForm(concept.form);
if (!normalized) {
errors.push(`concept ${concept.id || '(unknown)'} needs a form`);
} else if (normalizedForms.has(normalized)) {
errors.push(`duplicate concept form: ${concept.id} and ${normalizedForms.get(normalized)}`);
}
normalizedForms.set(normalized, concept.id);
if (typeof concept.form !== 'string' || !concept.form.includes(',')) {
errors.push(`concept ${concept.id || '(unknown)'} must name a form and inherited structure after a comma`);
}
if (typeof concept.lineage !== 'string' || !concept.lineage.trim()) {
errors.push(`concept ${concept.id || '(unknown)'} needs lineage metadata`);
}
if (!Array.isArray(concept.tags) || concept.tags.length !== 3 || concept.tags.some(tag => typeof tag !== 'string' || !tag.trim())) {
errors.push(`concept ${concept.id || '(unknown)'} must have exactly three structural tags`);
}
if (/\b(?:in the style of|styled like|copy of)\b/i.test(concept.form)) {
errors.push(`concept ${concept.id || '(unknown)'} contains imitation language`);
}
}
}
if (expectedTotal !== undefined && concepts.length !== expectedTotal) {
errors.push(`expected ${expectedTotal} concepts, found ${concepts.length}`);
}
if (minimumTotal !== undefined && concepts.length < minimumTotal) {
errors.push(`expected at least ${minimumTotal} concepts, found ${concepts.length}`);
}
if (!Number.isInteger(reviewData?.schemaVersion) || reviewData.schemaVersion < 1) {
errors.push('reviews.schemaVersion must be a positive integer');
}
for (const [id, review] of Object.entries(reviewData?.reviews || {})) {
if (!conceptIds.has(id)) errors.push(`review references missing concept: ${id}`);
if (!CONCEPT_STATUSES.has(review?.status)) errors.push(`invalid review status for ${id}: ${String(review?.status)}`);
if (typeof review?.reviewedBy !== 'string' || !review.reviewedBy.trim()) {
errors.push(`review ${id} needs reviewedBy`);
}
if (typeof review?.reviewedAt !== 'string' || Number.isNaN(Date.parse(review.reviewedAt))) {
errors.push(`review ${id} needs an ISO reviewedAt timestamp`);
}
}
const approved = concepts.filter(concept => reviewData?.reviews?.[concept.id]?.status === 'approved');
const approvedFamilies = new Set(
(catalog?.families || [])
.filter(family => family.concepts?.some(concept => reviewData?.reviews?.[concept.id]?.status === 'approved'))
.map(family => family.id)
);
if (approved.length < 3) errors.push('at least three concepts must be approved');
if (approvedFamilies.size < 3) errors.push('approved concepts must span at least three families');
return {
errors,
warnings,
stats: {
families: familyIds.size,
concepts: concepts.length,
approved: approved.length,
pending: concepts.length - Object.keys(reviewData?.reviews || {}).length,
rejected: Object.values(reviewData?.reviews || {}).filter(review => review?.status === 'rejected').length,
},
};
}
export function approvedPoolRevision(concepts) {
const payload = concepts
.filter(concept => concept.status === 'approved')
.map(concept => `${concept.familyId}:${concept.id}:${concept.form}`)
.sort()
.join('\n');
return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 12);
}
export function deterministicRank(items, input, idFor = item => item.id) {
return [...items].sort((a, b) => {
const scoreA = crypto.createHash('sha256').update(`${input}:${idFor(a)}`).digest('hex');
const scoreB = crypto.createHash('sha256').update(`${input}:${idFor(b)}`).digest('hex');
return scoreB.localeCompare(scoreA) || idFor(a).localeCompare(idFor(b));
});
}
+1
View File
@@ -1,4 +1,5 @@
// Source scripts default to slash commands. The provider build replaces only
// this exact declaration, avoiding heuristic rewrites across executable code.
export const IMPECCABLE_COMMAND_PREFIX = '/'; // @impeccable-provider-command-prefix
export const IMPECCABLE_PROVIDER_ID = 'source'; // @impeccable-provider-id
export const IMPECCABLE_COMMAND = `${IMPECCABLE_COMMAND_PREFIX}impeccable`;
+30
View File
@@ -0,0 +1,30 @@
export const LLM_ONLY_SLOP_ITEMS = Object.freeze([
'Monospace used merely to signal “technical” or “developer.”',
'Light or dark mode chosen by category habit rather than the actual use scene.',
'Everything wrapped in cards, or identical icon-heading-text cards repeated as the page structure.',
'Hero-metric scaffolds: one oversized number, a small label, supporting stats, and an accent treatment.',
'Decorative glassmorphism, meaningless sparklines, or generic rounded rectangles with drop shadows.',
'A modal chosen by reflex when the task does not require interruption or protected focus.',
]);
export function renderLlmOnlySlopReview({ manualDetector = false, automaticDetector = false, scriptsPath = null } = {}) {
const lines = [
automaticDetector
? 'AI_SLOP_REVIEW_REQUIRED: The automatic detector covers mechanical rules, but this harness has no reliable late review. Before finishing changed UI, inspect the authored result for detector-blind model reflexes:'
: 'AI_SLOP_REVIEW_REQUIRED: The automatic Impeccable design hook is not available for this session. Before finishing changed UI, inspect the authored result for detector-blind model reflexes:',
...LLM_ONLY_SLOP_ITEMS.map((item) => `- ${item}`),
'Fix reflexes, not intentional choices required by the brief or established visual authority.',
];
if (manualDetector && scriptsPath) {
lines.push(`Then run the mechanical detector once over the changed web UI: \`node ${scriptsPath}/detect.mjs --json <changed targets>\`. Do not run it earlier during concept selection.`);
}
return lines.join('\n');
}
export function renderStopSlopReview() {
return [
'[impeccable@1] Detector-blind AI-slop review. The mechanical pass is complete; now inspect the rendered result for model reflexes it cannot reliably detect:',
...LLM_ONLY_SLOP_ITEMS.map((item) => `- ${item}`),
'Fix reflexes, not intentional choices required by the brief or established visual authority. Do not rerun the detector; this is the authored judgment layer.',
].join('\n');
}
@@ -0,0 +1,22 @@
#!/usr/bin/env node
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { readConceptCatalog, validateConceptCatalog } from './lib/concept-catalog.mjs';
const here = dirname(fileURLToPath(import.meta.url));
const { catalog, reviewData } = readConceptCatalog(
join(here, 'concept-ingredients.json'),
join(here, 'concept-reviews.json')
);
const result = validateConceptCatalog(catalog, reviewData, { minimumTotal: 2304 });
if (result.errors.length > 0) {
for (const error of result.errors) process.stderr.write(`concept-catalog: ${error}\n`);
process.exitCode = 1;
} else {
process.stdout.write(
`concept-catalog: ${result.stats.concepts} concepts across ${result.stats.families} families; ` +
`${result.stats.approved} approved, ${result.stats.pending} pending, ${result.stats.rejected} rejected\n`
);
}