@mindflight/mindbrain-personal-studio 0.6.1 → 0.6.2

package/scripts/build-serenity-v6-review-pack.mjs

@@ -1,479 +0,0 @@
-#!/usr/bin/env node
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-
-const TARGET_WORKSPACE = 'serenity-production-v6';
-const DEFAULT_DB = '/home/dlamotte/.ghostcrab/databases/ghostcrab-serenity-v4-demos.sqlite';
-const DEFAULT_IN_DIR = 'docs/demo/export-audit/2026-06-26/serenity-production-v6-migration';
-const DEFAULT_OUT_DIR = 'docs/demo/export-audit/2026-06-26/serenity-production-v6-review-pack';
-
-const dbPath = valueAfter('--db') ?? process.env.GHOSTCRAB_SQLITE_PATH ?? DEFAULT_DB;
-const inDir = valueAfter('--in-dir') ?? DEFAULT_IN_DIR;
-const outDir = valueAfter('--out-dir') ?? DEFAULT_OUT_DIR;
-
-function valueAfter(flag) {
-	const index = process.argv.indexOf(flag);
-	return index >= 0 ? process.argv[index + 1] : null;
-}
-
-function readJson(name) {
-	return JSON.parse(readFileSync(join(inDir, name), 'utf8'));
-}
-
-function writeJson(name, value) {
-	writeFileSync(join(outDir, name), `${JSON.stringify(value, null, 2)}\n`);
-}
-
-function quote(value) {
-	return `'${String(value).replaceAll("'", "''")}'`;
-}
-
-function runSqlJson(sql) {
-	const result = spawnSync('sqlite3', ['-readonly', '-json', dbPath, sql], {
-		encoding: 'utf8',
-		maxBuffer: 1024 * 1024 * 64
-	});
-	if (result.status !== 0) {
-		throw new Error(result.stderr || result.stdout || 'sqlite3 failed');
-	}
-	return JSON.parse(result.stdout || '[]');
-}
-
-function uniq(values) {
-	return [...new Set(values.filter((value) => value !== null && value !== undefined && value !== ''))].sort();
-}
-
-function splitSources(sourceString) {
-	return uniq(String(sourceString || '').split(','));
-}
-
-function normalizeName(value) {
-	return String(value || '')
-		.toLowerCase()
-		.normalize('NFD')
-		.replace(/[\u0300-\u036f]/g, '')
-		.replace(/d[eu]_/g, '')
-		.replace(/[^a-z0-9]+/g, '_')
-		.replace(/^_+|_+$/g, '');
-}
-
-function localSchemaId(schemaId) {
-	const value = String(schemaId || '');
-	if (value.startsWith(`${TARGET_WORKSPACE}:`)) return value.slice(TARGET_WORKSPACE.length + 1);
-	if (value.startsWith('serenity-v4:')) return value.slice('serenity-v4:'.length);
-	return value;
-}
-
-function domainOfSchema(schemaId) {
-	const local = localSchemaId(schemaId);
-	return local.split(':')[0] || 'unknown';
-}
-
-function familyFromScope(scope) {
-	const parts = String(scope || '').split(':');
-	return parts[1] || 'unknown';
-}
-
-function relationFamily(relationType) {
-	const relation = String(relationType);
-	if (['referencer', 'supported_by', 'supporter', 'maps_to', 'sourced_from'].includes(relation)) {
-		return 'evidence_or_provenance';
-	}
-	if (['contenir', 'rattacher', 'est_composee_d', 'assigner_gestion'].includes(relation)) {
-		return 'structural_or_ownership';
-	}
-	if (['est_calcule_a_partir_de', 'est_emise_par', 'resulte_de'].includes(relation)) {
-		return 'financial_or_accounting';
-	}
-	if (['donne_lieu_a', 'est_actee_par', 'fonde_une', 'peut_preceder', 'porte_sur'].includes(relation)) {
-		return 'procedure_flow';
-	}
-	if (['activer', 'composer', 'declencher', 'evalue', 'peut_generer', 'produit_des'].includes(relation)) {
-		return 'workflow_effect';
-	}
-	return 'unclassified';
-}
-
-function evidenceLevel(supportedScenarios, sources) {
-	if (supportedScenarios.some((scenario) => scenario.workflow)) return 'A_explicit_workflow';
-	if (supportedScenarios.length > 0) return 'B_scenario_required_edge';
-	if (sources.length > 0 && sources.every((source) => /fake|smoke|mini_seed/i.test(source))) return 'D_generated_only';
-	return 'C_implied_or_unmapped';
-}
-
-function proposedRelationDecision(relationType, evidence) {
-	if (['referencer', 'supported_by', 'supporter'].includes(relationType)) return 'split_or_rename_required';
-	if (evidence === 'A_explicit_workflow') return 'candidate_promote_renamed';
-	if (evidence === 'B_scenario_required_edge') return 'review_source_target_before_promote';
-	return 'keep_rejected';
-}
-
-function schemaDecision(schemaId, match) {
-	if (match?.exact) return 'map_to_existing';
-	if (match?.best) return 'review_possible_existing_mapping';
-	if (schemaId.startsWith('serenity-v4:')) return 'rename_and_add_if_sop_valid';
-	return 'add_or_rename_after_sop_review';
-}
-
-function loadV6Schemas() {
-	const rows = runSqlJson(
-		`SELECT COALESCE(NULLIF(json_extract(facets_json, '$.schema_id'), ''),
-		                NULLIF(json_extract(content, '$.schema_id'), ''),
-		                id) AS schema_id
-		   FROM agent_facts
-		  WHERE workspace_id = ${quote(TARGET_WORKSPACE)}
-		    AND schema_id = 'mindbrain:schema'
-		  ORDER BY schema_id`
-	);
-	const schemas = rows.map((row) => row.schema_id);
-	const normalized = new Map();
-	for (const schema of schemas) {
-		normalized.set(normalizeName(localSchemaId(schema)), schema);
-	}
-	return { schemas, normalized };
-}
-
-function findSchemaMatch(schemaId, v6Schemas) {
-	const local = localSchemaId(schemaId);
-	const exactTarget = `${TARGET_WORKSPACE}:${local}`;
-	if (v6Schemas.schemas.includes(exactTarget)) return { exact: exactTarget, best: exactTarget };
-	if (v6Schemas.schemas.includes(schemaId)) return { exact: schemaId, best: schemaId };
-	const normalized = normalizeName(local);
-	const best = v6Schemas.normalized.get(normalized);
-	if (best) return { exact: null, best };
-
-	const [, domain, name] = schemaId.match(/^(?:serenity-v4:)?([^:]+):(.+)$/) || [];
-	if (domain && name) {
-		const nameNorm = normalizeName(name);
-		const candidates = v6Schemas.schemas
-			.filter((schema) => localSchemaId(schema).startsWith(`${domain}:`))
-			.map((schema) => ({ schema, score: similarity(nameNorm, normalizeName(localSchemaId(schema).split(':').slice(1).join(':'))) }))
-			.filter((candidate) => candidate.score >= 0.72)
-			.sort((a, b) => b.score - a.score);
-		if (candidates[0]) return { exact: null, best: candidates[0].schema, score: candidates[0].score };
-	}
-	return { exact: null, best: null };
-}
-
-function similarity(a, b) {
-	const aParts = new Set(String(a).split('_').filter(Boolean));
-	const bParts = new Set(String(b).split('_').filter(Boolean));
-	if (aParts.size === 0 || bParts.size === 0) return 0;
-	const intersection = [...aParts].filter((part) => bParts.has(part)).length;
-	const union = new Set([...aParts, ...bParts]).size;
-	return intersection / union;
-}
-
-function buildScenarioMatrix(scenarios) {
-	return scenarios.map((scenario) => ({
-		artifact_id: scenario.artifact_id,
-		scope: scenario.scope,
-		public_label: scenario.public_label,
-		projection_id: scenario.projection_id,
-		sop_family: scenario.workflow ?? `legacy:${familyFromScope(scenario.scope)}`,
-		evidence_level: scenario.workflow ? 'A_explicit_workflow' : 'B_or_C_legacy_analysis_plan',
-		required_edges: scenario.required_edges,
-		required_schemas: scenario.required_schemas,
-		review_question: scenario.workflow
-			? `Does workflow ${scenario.workflow} need additional V6 source/target schemas or typed relations?`
-			: `Is ${scenario.scope} still a valid SOP/business scenario, or a stale V4 planning artifact?`,
-		decision: 'pending_review'
-	}));
-}
-
-function buildSchemaPack(missingSchemas, v6Schemas) {
-	return missingSchemas.map((schema) => {
-		const match = findSchemaMatch(schema.schema_id, v6Schemas);
-		const requiredScopes = uniq(schema.required_by.map((entry) => entry.scope));
-		const sopFamilies = uniq(schema.required_by.map((entry) => entry.workflow ?? `legacy:${familyFromScope(entry.scope)}`));
-		const decision = schemaDecision(schema.schema_id, match);
-		return {
-			schema_id: schema.schema_id,
-			mece_bucket: schema.schema_id.startsWith('serenity-v4:')
-				? 'legacy_v4_name_mapping'
-				: 'missing_or_ambiguous_v6_schema',
-			domain: domainOfSchema(schema.schema_id),
-			required_by_count: schema.required_by.length,
-			required_by_scopes: requiredScopes,
-			sop_families: sopFamilies,
-			current_v6_equivalent: match.best,
-			exact_v6_match: match.exact,
-			field_gap: 'unknown_until_schema_inspection',
-			relation_gap: 'unknown_until_relation_review',
-			decision,
-			canonical_v6_schema_id:
-				decision === 'map_to_existing' || decision === 'review_possible_existing_mapping'
-					? match.best
-					: `${TARGET_WORKSPACE}:${localSchemaId(schema.schema_id).replace(/^serenity-v4:/, '')}`,
-			review_questions: [
-				`Is ${schema.schema_id} a live SOP object or a stale V4 reference?`,
-				'Does the suggested V6 equivalent cover the same business meaning?',
-				'Which minimum fields are required by the SOP?',
-				'Which accepted relation should connect this schema to the existing V6 model?'
-			],
-			next_action:
-				decision === 'map_to_existing'
-					? 'update scenario/schema reference to existing V6 schema'
-					: 'inspect SOP and decide add_schema vs rename vs reject'
-		};
-	});
-}
-
-function buildRelationPack(reviewRelations) {
-	const grouped = new Map();
-	for (const row of reviewRelations) {
-		const current =
-			grouped.get(row.relation_type) ?? {
-				relation_type: row.relation_type,
-				v4_instances: 0,
-				workspaces: [],
-				sources: new Set(),
-				linkml_classes: new Set(),
-				supported_scenarios: new Map()
-			};
-		current.v4_instances += Number(row.instance_count || 0);
-		current.workspaces.push({ workspace_id: row.workspace_id, instance_count: row.instance_count });
-		for (const source of splitSources(row.sources)) current.sources.add(source);
-		for (const cls of splitSources(row.linkml_classes)) current.linkml_classes.add(cls);
-		for (const scenario of row.supported_scenarios || []) current.supported_scenarios.set(scenario.scope, scenario);
-		grouped.set(row.relation_type, current);
-	}
-
-	return [...grouped.values()]
-		.sort((a, b) => a.relation_type.localeCompare(b.relation_type))
-		.map((group) => {
-			const scenarios = [...group.supported_scenarios.values()].sort((a, b) => a.scope.localeCompare(b.scope));
-			const sources = [...group.sources].sort();
-			const evidence = evidenceLevel(scenarios, sources);
-			const family = relationFamily(group.relation_type);
-			const decision = proposedRelationDecision(group.relation_type, evidence);
-			return {
-				relation_type: group.relation_type,
-				mece_bucket: family,
-				evidence_level: evidence,
-				v4_instances: group.v4_instances,
-				workspaces: group.workspaces.sort((a, b) => a.workspace_id.localeCompare(b.workspace_id)),
-				sources,
-				source_quality: sources.some((source) => /fake|smoke|mini_seed/i.test(source))
-					? 'mixed_or_generated'
-					: 'structured_or_artifact',
-				supported_scenarios: scenarios.map((scenario) => ({
-					scope: scenario.scope,
-					workflow: scenario.workflow,
-					scenario_refs: scenario.scenario_refs
-				})),
-				linkml_class_sample: [...group.linkml_classes].sort().slice(0, 20),
-				source_schema: null,
-				target_schema: null,
-				direction: 'unknown_until_sop_review',
-				cardinality: 'unknown_until_sop_review',
-				existing_v6_relation: null,
-				canonical_v6_relation:
-					decision === 'split_or_rename_required' ? null : suggestCanonicalRelation(group.relation_type),
-				decision,
-				devils_advocate_result:
-					decision === 'split_or_rename_required'
-						? 'Fails as-is because the verb is too generic; split into SOP-specific relations.'
-						: 'Pending source/target/direction proof.',
-				review_questions: [
-					`In which SOP is ${group.relation_type} required?`,
-					'What are the exact source and target schema types?',
-					'Can this be derived instead of stored?',
-					'Does V6 already express the same meaning with a better relation?',
-					'Would an operator understand this verb?'
-				],
-				next_action:
-					decision === 'split_or_rename_required'
-						? 'split into precise SOP-specific relations or reject'
-						: 'write SOP sentence and source/target proposal'
-			};
-		});
-}
-
-function suggestCanonicalRelation(relationType) {
-	const suggestions = {
-		activer: 'activates',
-		assigner_gestion: 'assigned_to_management_team',
-		composer: 'composed_of',
-		contenir: 'contains',
-		declencher: 'triggers',
-		donne_lieu_a: 'gives_rise_to',
-		est_actee_par: 'recorded_by',
-		est_calcule_a_partir_de: 'calculated_from',
-		est_composee_d: 'composed_of',
-		est_emise_par: 'issued_by',
-		evalue: 'evaluates',
-		fonde_une: 'grounds',
-		peut_generer: 'may_generate',
-		peut_preceder: 'may_precede',
-		porte_sur: 'applies_to',
-		produit_des: 'produces',
-		rattacher: 'attached_to',
-		resulte_de: 'results_from'
-	};
-	return suggestions[relationType] ?? relationType;
-}
-
-function buildRejectedAudit(rejectedRelations) {
-	return rejectedRelations.map((row) => ({
-		relation_type: row.relation_type,
-		workspace_id: row.workspace_id,
-		v4_instances: row.instance_count,
-		rejection_reason: row.decision,
-		source_quality: /fake|smoke|mini_seed/i.test(row.sources || '') ? 'generated_or_weak' : 'unmapped',
-		sources: splitSources(row.sources),
-		possible_sop_link: null,
-		reopen_trigger:
-			row.decision === 'reject_no_sop_or_scenario'
-				? 'reopen only if a concrete SOP sentence requires it'
-				: row.decision === 'reject_generic_relation'
-					? 'reopen only as split/renamed specific relation'
-					: 'keep rejected unless non-generated source is found',
-		final_status: 'keep_rejected'
-	}));
-}
-
-function writeMarkdown(summary, schemaPack, relationPack, rejectedAudit) {
-	const byDecision = (items) =>
-		items.reduce((acc, item) => {
-			acc[item.decision] = (acc[item.decision] || 0) + 1;
-			return acc;
-		}, {});
-	const rejectedByReason = rejectedAudit.reduce((acc, item) => {
-		acc[item.rejection_reason] = (acc[item.rejection_reason] || 0) + 1;
-		return acc;
-	}, {});
-	const md = `# Serenity Production V6 Review Pack
-
-This pack turns the raw V4/V4-S2 candidate reports into reviewable decision records.
-
-## Summary
-
-| Area | Count |
-|---|---:|
-| Scenarios/SOP rows | ${summary.scenarios} |
-| Missing schema decisions | ${schemaPack.length} |
-| Relation decisions | ${relationPack.length} |
-| Rejected relation audit rows | ${rejectedAudit.length} |
-
-## Schema Decisions
-
-\`\`\`json
-${JSON.stringify(byDecision(schemaPack), null, 2)}
-\`\`\`
-
-## Relation Decisions
-
-\`\`\`json
-${JSON.stringify(byDecision(relationPack), null, 2)}
-\`\`\`
-
-## Rejected Relation Audit
-
-\`\`\`json
-${JSON.stringify(rejectedByReason, null, 2)}
-\`\`\`
-
-## Review Rule
-
-A candidate can advance only when this sentence can be completed:
-
-> In SOP <name>, <source schema> must <relation> <target schema> so the operator can <decision/action>.
-
-## Files
-
-- \`scenario_sop_review_matrix.json\`
-- \`schema_decision_pack.json\`
-- \`relation_decision_pack.json\`
-- \`rejected_relation_audit.json\`
-- \`review_questions.md\`
-`;
-	writeFileSync(join(outDir, 'README.md'), md);
-}
-
-function writeQuestions(schemaPack, relationPack) {
-	const topSchemas = schemaPack
-		.slice()
-		.sort((a, b) => b.required_by_count - a.required_by_count)
-		.slice(0, 12)
-		.map(
-			(row) =>
-				`- ${row.schema_id}: ${row.decision}; suggested=${row.current_v6_equivalent ?? row.canonical_v6_schema_id}; required_by=${row.required_by_count}`
-		)
-		.join('\n');
-	const topRelations = relationPack
-		.slice()
-		.sort((a, b) => b.v4_instances - a.v4_instances)
-		.slice(0, 12)
-		.map(
-			(row) =>
-				`- ${row.relation_type}: ${row.decision}; bucket=${row.mece_bucket}; instances=${row.v4_instances}; scenarios=${row.supported_scenarios.length}`
-		)
-		.join('\n');
-	const md = `# Review Questions
-
-## Start Here: Schema Gaps
-
-${topSchemas}
-
-For each: map to existing V6, add/rename, or reject as stale.
-
-## Then: Relation Candidates
-
-${topRelations}
-
-For each: write the SOP sentence, then decide promote renamed, derive only, split, or reject.
-
-## Default Choices
-
-- Generic relation names are not promoted as-is.
-- Legacy no-workflow scenarios need SOP-family confirmation.
-- Mini-seed/fake/smoke evidence is not enough by itself.
-`;
-	writeFileSync(join(outDir, 'review_questions.md'), md);
-}
-
-function main() {
-	mkdirSync(outDir, { recursive: true });
-	const scenarioSopMap = readJson('scenario_sop_map.json');
-	const missingSchemas = readJson('missing_schemas_required_by_sop.json');
-	const reviewRelations = readJson('review_required_relations.json');
-	const rejectedRelations = readJson('rejected_relations.json');
-	const v6Schemas = loadV6Schemas();
-
-	const scenarioMatrix = buildScenarioMatrix(scenarioSopMap);
-	const schemaPack = buildSchemaPack(missingSchemas, v6Schemas);
-	const relationPack = buildRelationPack(reviewRelations);
-	const rejectedAudit = buildRejectedAudit(rejectedRelations);
-	const summary = {
-		target_workspace: TARGET_WORKSPACE,
-		scenarios: scenarioMatrix.length,
-		missing_schema_cases: schemaPack.length,
-		relation_cases: relationPack.length,
-		rejected_relation_cases: rejectedAudit.length,
-		policy: {
-			auto_promote: false,
-			default_unit: 'SOP/scenario',
-			default_generic_relation_action: 'split_or_rename_required'
-		}
-	};
-
-	writeJson('scenario_sop_review_matrix.json', scenarioMatrix);
-	writeJson('schema_decision_pack.json', schemaPack);
-	writeJson('relation_decision_pack.json', relationPack);
-	writeJson('rejected_relation_audit.json', rejectedAudit);
-	writeJson('review_pack_summary.json', summary);
-	writeMarkdown(summary, schemaPack, relationPack, rejectedAudit);
-	writeQuestions(schemaPack, relationPack);
-
-	console.log(`wrote ${outDir}`);
-	console.log(JSON.stringify(summary, null, 2));
-}
-
-try {
-	main();
-} catch (error) {
-	console.error(error instanceof Error ? error.message : error);
-	process.exit(1);
-}