@geraldmaron/construct 1.0.23 → 1.1.0

package/lib/specialists/prompt-schema.mjs

@@ -0,0 +1,162 @@
+/**
+ * lib/specialists/prompt-schema.mjs — validation for hybrid specialist prompt files.
+ *
+ * Specialist prompts are migrating from opaque free-form markdown to a hybrid
+ * shape: YAML frontmatter (structured metadata) + markdown body (the authored
+ * prose), mirroring skills/roles/*.md. This validates the frontmatter and the
+ * canonical-section contract, and gates the highest-value invariant — the
+ * frontmatter `perspective{}` must equal the registry's, since the two
+ * currently duplicate each other and drift silently (ADR-0037).
+ *
+ * A file with no frontmatter is treated as not-yet-converted: reported, never an
+ * error, so the linter can run across a half-migrated corpus. Frontmatter is the
+ * source of truth; section checks are warnings until the body-normalization
+ * phase, so adding frontmatter alone never fails the gate.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+export const REQUIRED_FRONTMATTER = ['name', 'role', 'version', 'perspective'];
+export const PERSPECTIVE_FIELDS = ['bias', 'tension', 'openingQuestion', 'failureMode'];
+export const OPTIONAL_FRONTMATTER = ['roleGuidance', 'roleOverlays', 'templates', 'preloadRoleGuidance'];
+export const REQUIRED_SECTIONS = ['Anti-fabrication contract', 'Output format'];
+export const CANONICAL_SECTIONS = [
+  'Orientation', 'Anti-fabrication contract', 'Productive tension',
+  'Opening question', 'Failure mode', 'Domain overlays', 'Output format',
+];
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+/**
+ * Split a prompt file into { frontmatter, body }. frontmatter is null when the
+ * file has none (unconverted), or undefined when the YAML failed to parse.
+ */
+export function splitFrontmatter(text) {
+  const raw = String(text ?? '');
+  const m = raw.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: null, body: raw };
+  try {
+    const fm = yaml.load(m[1]);
+    return { frontmatter: (fm && typeof fm === 'object') ? fm : {}, body: raw.slice(m[0].length) };
+  } catch (err) {
+    return { frontmatter: undefined, body: raw.slice(m[0].length), error: err.message };
+  }
+}
+
+function hasHeading(body, title) {
+  const target = String(title).trim().toLowerCase();
+  const re = /^#{1,6}\s+(.+)$/gm;
+  let m;
+  while ((m = re.exec(body))) {
+    if (m[1].trim().toLowerCase() === target) return true;
+  }
+  return false;
+}
+
+function samePerspective(a, b) {
+  if (!a || !b) return false;
+  return PERSPECTIVE_FIELDS.every((f) => String(a[f] ?? '').trim() === String(b[f] ?? '').trim());
+}
+
+/**
+ * Validate one prompt file's content against the hybrid format.
+ *
+ * @param {object} opts
+ * @param {string} opts.content - raw file content
+ * @param {string} [opts.id] - display id (cx-<role>) for messages
+ * @param {object} [opts.registryEntry] - the matching registry specialist (for drift checks)
+ * @returns {{ converted: boolean, errors: string[], warnings: string[] }}
+ */
+export function validatePromptContent({ content, id = '(prompt)', registryEntry } = {}) {
+  const errors = [];
+  const warnings = [];
+  const { frontmatter, body, error } = splitFrontmatter(content);
+
+  if (frontmatter === null) {
+    return { converted: false, errors, warnings: [`${id}: no frontmatter — not yet converted to the hybrid format`] };
+  }
+  if (frontmatter === undefined) {
+    errors.push(`${id}: frontmatter is not valid YAML — ${error}`);
+    return { converted: true, errors, warnings };
+  }
+
+  for (const field of REQUIRED_FRONTMATTER) {
+    if (frontmatter[field] == null || frontmatter[field] === '') {
+      errors.push(`${id}: missing required frontmatter field "${field}"`);
+    }
+  }
+
+  if (frontmatter.name && registryEntry?.name) {
+    const expected = `cx-${registryEntry.name}`;
+    if (frontmatter.name !== expected) {
+      errors.push(`${id}: frontmatter name "${frontmatter.name}" must equal "${expected}" (registry name)`);
+    }
+  }
+  if (frontmatter.version != null && !Number.isInteger(frontmatter.version)) {
+    errors.push(`${id}: frontmatter version must be an integer (got ${JSON.stringify(frontmatter.version)})`);
+  }
+
+  const persp = frontmatter.perspective;
+  if (persp && typeof persp === 'object') {
+    for (const f of PERSPECTIVE_FIELDS) {
+      if (!persp[f] || !String(persp[f]).trim()) errors.push(`${id}: perspective.${f} is required and must be non-empty`);
+    }
+    if (registryEntry?.perspective && !samePerspective(persp, registryEntry.perspective)) {
+      errors.push(`${id}: perspective{} drifts from registry.json — they must match while both exist (frontmatter is the source of truth; update the registry)`);
+    }
+  } else if (frontmatter.perspective != null) {
+    errors.push(`${id}: perspective must be an object with ${PERSPECTIVE_FIELDS.join(', ')}`);
+  }
+
+  const known = new Set([...REQUIRED_FRONTMATTER, ...OPTIONAL_FRONTMATTER]);
+  for (const key of Object.keys(frontmatter)) {
+    if (!known.has(key)) warnings.push(`${id}: unknown frontmatter key "${key}"`);
+  }
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!hasHeading(body, section)) warnings.push(`${id}: missing canonical section "## ${section}" (warn-only until body normalization)`);
+  }
+
+  return { converted: true, errors, warnings };
+}
+
+/**
+ * Validate every specialist prompt file referenced by the registry.
+ * @returns {{ errors: string[], warnings: string[], total: number, converted: number }}
+ */
+export function validatePromptFiles({ rootDir = process.cwd(), registry } = {}) {
+  const errors = [];
+  const warnings = [];
+  let total = 0;
+  let converted = 0;
+
+  const reg = registry ?? loadRegistry(rootDir);
+  const specialists = Array.isArray(reg?.specialists) ? reg.specialists : [];
+  const byName = new Map(specialists.map((s) => [s.name, s]));
+
+  const seen = new Set();
+  for (const entry of specialists) {
+    if (!entry?.promptFile || !entry.promptFile.startsWith('specialists/prompts/')) continue;
+    if (seen.has(entry.promptFile)) continue;
+    seen.add(entry.promptFile);
+    const filePath = path.join(rootDir, entry.promptFile);
+    if (!fs.existsSync(filePath)) { errors.push(`${entry.name}: promptFile ${entry.promptFile} does not exist`); continue; }
+    total += 1;
+    const content = fs.readFileSync(filePath, 'utf8');
+    const result = validatePromptContent({ content, id: `cx-${entry.name}`, registryEntry: byName.get(entry.name) });
+    if (result.converted) converted += 1;
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+  return { errors, warnings, total, converted };
+}
+
+function loadRegistry(rootDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(rootDir, 'specialists', 'registry.json'), 'utf8'));
+  } catch {
+    return { specialists: [] };
+  }
+}

package/lib/specialists/scaffold.mjs

@@ -0,0 +1,109 @@
+/**
+ * lib/specialists/scaffold.mjs — scaffold and field-edit hybrid specialist prompts.
+ *
+ * The CLI harness side of ADR-0037: `construct specialist create` emits a
+ * canonical skeleton (frontmatter + required sections) a human then fills in,
+ * and `construct specialist edit` mutates frontmatter fields only (never the
+ * prose body). Both validate against lib/specialists/prompt-schema.mjs before
+ * declaring success, so a scaffolded file passes `lint:prompts` immediately.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { splitFrontmatter, validatePromptContent, PERSPECTIVE_FIELDS } from './prompt-schema.mjs';
+
+function promptRelPath(role) {
+  return path.join('specialists', 'prompts', `cx-${role}.md`);
+}
+
+/**
+ * Render a canonical skeleton for a new specialist. Body sections are stubbed
+ * with a one-line placeholder so the file is valid-shaped from creation.
+ */
+export function renderSkeleton({ role, perspective = {}, roleGuidance } = {}) {
+  const fm = {
+    name: `cx-${role}`,
+    role,
+    version: 1,
+    perspective: {
+      bias: perspective.bias || 'TODO: what this role is instinctively suspicious of',
+      tension: perspective.tension || 'cx-TODO',
+      openingQuestion: perspective.openingQuestion || 'TODO: the first diagnostic question',
+      failureMode: perspective.failureMode || 'TODO: how this role fails when absent',
+    },
+    ...(roleGuidance ? { roleGuidance } : {}),
+  };
+  const body = [
+    '## Orientation',
+    '',
+    'TODO: the role voice — the hard-won instinct that makes this specialist worth consulting.',
+    '',
+    '## Anti-fabrication contract',
+    '',
+    'Every load-bearing claim cites a source the reader can re-verify. When a fact is not in the source, write `unknown` or `[unverified]`. See `rules/common/no-fabrication.md`.',
+    '',
+    '## Output format',
+    '',
+    'TODO: the artifact this role produces, or the `get_template(...)` it delegates to.',
+    '',
+  ].join('\n');
+  return `---\n${yaml.dump(fm).trimEnd()}\n---\n\n${body}`;
+}
+
+/**
+ * Create a specialist prompt draft on disk. Refuses to overwrite. Validates
+ * the rendered skeleton before writing.
+ * @returns {{ path: string, relPath: string }}
+ */
+export function createSpecialistDraft({ rootDir = process.cwd(), role, perspective, roleGuidance } = {}) {
+  if (!role || !/^[a-z][a-z0-9-]*$/.test(role)) {
+    throw new Error(`invalid role id "${role}" — use lowercase kebab-case (e.g. performance-auditor)`);
+  }
+  const relPath = promptRelPath(role);
+  const filePath = path.join(rootDir, relPath);
+  if (fs.existsSync(filePath)) throw new Error(`${relPath} already exists — refusing to overwrite`);
+
+  const content = renderSkeleton({ role, perspective, roleGuidance });
+  const { errors } = validatePromptContent({ content, id: `cx-${role}` });
+  if (errors.length) throw new Error(`scaffold failed validation:\n  ${errors.join('\n  ')}`);
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content.endsWith('\n') ? content : `${content}\n`);
+  return { path: filePath, relPath };
+}
+
+/**
+ * Edit a specialist's frontmatter only (never the prose body). Supported edits:
+ * set a perspective field, add a role overlay, or bump the version.
+ * @returns {{ path: string, frontmatter: object }}
+ */
+export function editSpecialistFrontmatter({ rootDir = process.cwd(), role, setPerspective = {}, addOverlay, bumpVersion = false } = {}) {
+  const relPath = promptRelPath(role);
+  const filePath = path.join(rootDir, relPath);
+  if (!fs.existsSync(filePath)) throw new Error(`${relPath} does not exist`);
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = splitFrontmatter(raw);
+  if (!frontmatter) throw new Error(`${relPath} has no frontmatter — convert it to the hybrid format first`);
+
+  for (const [field, value] of Object.entries(setPerspective)) {
+    if (!PERSPECTIVE_FIELDS.includes(field)) throw new Error(`unknown perspective field "${field}"`);
+    frontmatter.perspective = { ...(frontmatter.perspective || {}), [field]: value };
+  }
+  if (addOverlay) {
+    const overlays = new Set(Array.isArray(frontmatter.roleOverlays) ? frontmatter.roleOverlays : []);
+    overlays.add(addOverlay);
+    frontmatter.roleOverlays = [...overlays];
+  }
+  if (bumpVersion) {
+    frontmatter.version = (Number.isInteger(frontmatter.version) ? frontmatter.version : 0) + 1;
+  }
+
+  const next = `---\n${yaml.dump(frontmatter).trimEnd()}\n---\n${body.startsWith('\n') ? '' : '\n'}${body}`;
+  const { errors } = validatePromptContent({ content: next, id: `cx-${role}` });
+  if (errors.length) throw new Error(`edit would break validation:\n  ${errors.join('\n  ')}`);
+
+  fs.writeFileSync(filePath, next.endsWith('\n') ? next : `${next}\n`);
+  return { path: filePath, frontmatter };
+}

package/lib/status.mjs

@@ -20,9 +20,6 @@ import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory }
 import { loadPluginRegistry } from './plugin-registry.mjs';
 import { readCostLog, summarizeCostData, normalizeCostEntry } from './cost.mjs';
 import { readEfficiencyLog, summarizeEfficiencyData } from './efficiency.mjs';
-import { describeSqlStore, sqlStoreHealth } from './storage/sql-store.mjs';
-import { describeVectorStore } from './storage/vector-store.mjs';
-import { describeSqlStoreHealth } from './storage/sql-store.mjs';
 import { triggerAutoBackfillIfSparse } from './telemetry/backfill.mjs';
 import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
 const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
@@ -709,9 +706,9 @@ export async function buildStatus({
   triggerAutoBackfillIfSparse(telemetryRichness, { ...mergedEnv });
   const efficiencyDigest = summarizeEfficiencyData(readEfficiencyLog(homeDir));
   const activeOverlays = getActiveOverlays(cwd);
-  const sqlStore = describeSqlStore(mergedEnv);
-  const vectorStore = describeVectorStore(mergedEnv);
-  const sqlHealth = sqlStore.mode === 'postgres' ? await describeSqlStoreHealth(mergedEnv) : sqlStoreHealth(mergedEnv);
+  const sqlStore = { mode: 'lancedb', label: 'LanceDB + Git-Backed', dbUrl: null, vectorEnabled: true };
+  const vectorStore = { enabled: true, backend: 'lancedb', label: 'Embedded LanceDB' };
+  const sqlHealth = { status: 'healthy', message: 'Local embedded' };
   const promotionRequests = getPromotionRequests(cwd);
   const executionContractModel = resolveExecutionContractModelMetadata({
     envValues: mergedEnv,