@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/improvement/store.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/improvement/store.mjs — durable proposal records for the governed
+ * improvement loop (construct-6zga.1.11).
+ *
+ * Each submission is a versioned JSON file under `.cx/improvement/proposals/`
+ * holding the proposal, held-out dataset item, evaluation report, optional
+ * specialist trace, governance verdict, and rollout plan. The store is the
+ * operator surface's source of truth; the controller never mutates artifacts in
+ * place without persisting the new state here.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const IMPROVEMENT_STORE_SCHEMA_VERSION = 1;
+
+export function improvementDir(projectDir) {
+  return path.join(projectDir, '.cx', 'improvement');
+}
+
+export function proposalsDir(projectDir) {
+  return path.join(improvementDir(projectDir), 'proposals');
+}
+
+export function proposalRecordPath(projectDir, id) {
+  return path.join(proposalsDir(projectDir), `${id}.json`);
+}
+
+export function approversPath(projectDir) {
+  return path.join(improvementDir(projectDir), 'approvers.json');
+}
+
+function ensureProposalsDir(projectDir) {
+  const dir = proposalsDir(projectDir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function loadApprovers(projectDir) {
+  const file = approversPath(projectDir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(parsed?.identities) ? parsed.identities : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveRecord(projectDir, record) {
+  ensureProposalsDir(projectDir);
+  const id = record?.id || record?.proposal?.id;
+  if (!id) throw new Error('record id required');
+  const now = new Date().toISOString();
+  const { projectDir: _omit, ...rest } = record;
+  const payload = {
+    schemaVersion: IMPROVEMENT_STORE_SCHEMA_VERSION,
+    ...rest,
+    id,
+    updatedAt: now,
+    submittedAt: record.submittedAt || now,
+  };
+  fs.writeFileSync(proposalRecordPath(projectDir, id), JSON.stringify(payload, null, 2), 'utf8');
+  return payload;
+}
+
+export function loadRecord(projectDir, id) {
+  const file = proposalRecordPath(projectDir, id);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function listRecords(projectDir, { state = null } = {}) {
+  const dir = proposalsDir(projectDir);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const record = loadRecord(projectDir, name.replace(/\.json$/, ''));
+    if (!record) continue;
+    if (state && record.proposal?.state !== state) continue;
+    out.push(record);
+  }
+  out.sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
+  return out;
+}

package/lib/improvement/surface.mjs

@@ -0,0 +1,219 @@
+/**
+ * lib/improvement/surface.mjs — operator flow for the governed improvement loop
+ * (construct-6zga.1.11).
+ *
+ * Wires the specialist loop, eval gates, and approval-gated controller into a
+ * review → approve → apply path shared by the CLI and dashboard. Submissions
+ * persist under `.cx/improvement/`; the controller plans rollouts and records
+ * human-performed apply/rollback but never mutates live artifacts itself.
+ */
+import os from 'node:os';
+
+import {
+  governProposal,
+  requireApproval,
+  planRollout,
+  recordApplication,
+  recordRollback,
+} from './controller.mjs';
+import { transitionProposal } from './proposal.mjs';
+import { runSpecialistImprovement } from './specialist-loop.mjs';
+import {
+  loadApprovers,
+  loadRecord,
+  listRecords,
+  saveRecord,
+} from './store.mjs';
+
+export function resolveKnownApprovers(projectDir, env = process.env) {
+  const configured = loadApprovers(projectDir);
+  if (configured?.length) return [...new Set(configured)];
+  const fromEnv = [env.CONSTRUCT_IMPROVEMENT_APPROVER, env.USER, env.LOGNAME].filter(Boolean);
+  try {
+    fromEnv.push(os.userInfo().username);
+  } catch { /* ignore */ }
+  return [...new Set(fromEnv.filter((id) => typeof id === 'string' && id))];
+}
+
+function mergeGovernance(projectDir, record, governance) {
+  const next = { ...record, governance, updatedAt: new Date().toISOString() };
+  if (governance?.admissible && record.proposal?.state === 'proposal_ready') {
+    const moved = transitionProposal(record.proposal, 'awaiting_approval');
+    if (moved.ok) next.proposal = moved.proposal;
+  }
+  return saveRecord(projectDir, next);
+}
+
+export function submitBundle({
+  projectDir,
+  bundle = {},
+  knownApprovers = null,
+  resolvedDependencies = [],
+} = {}) {
+  const approvers = knownApprovers || resolveKnownApprovers(projectDir);
+  const {
+    trace = null,
+    trigger = null,
+    dataset = null,
+    evaluationReport = null,
+    proposal: directProposal = null,
+    approver = null,
+    target = 'prompt',
+    baselineVersion = null,
+    candidateVersion = null,
+    heldOutProfiles = [],
+  } = bundle;
+
+  let proposal = directProposal;
+  let loopResult = null;
+
+  if (!proposal && trace) {
+    loopResult = runSpecialistImprovement({
+      trace,
+      trigger,
+      target,
+      heldOutProfiles,
+      baselineVersion,
+      candidateVersion,
+      approver,
+      dataset,
+      evaluationReport,
+      knownApprovers: approvers,
+      resolvedDependencies,
+    });
+    if (!loopResult.proposed) {
+      return { ok: false, stage: 'specialist-loop', loopResult };
+    }
+    proposal = loopResult.proposal;
+  }
+
+  if (!proposal) return { ok: false, error: 'bundle must include trace or proposal' };
+
+  const governance = governProposal({
+    proposal,
+    dataset,
+    evaluationReport,
+    knownApprovers: approvers,
+    resolvedDependencies,
+  });
+
+  const record = saveRecord(projectDir, {
+    projectDir,
+    id: proposal.id,
+    proposal,
+    dataset,
+    evaluationReport,
+    trace,
+    trigger,
+    loopResult,
+    governance,
+  });
+
+  if (governance.admissible) {
+    const advanced = mergeGovernance(projectDir, record, governance);
+    return { ok: true, record: advanced, governance, loopResult };
+  }
+
+  const failed = transitionProposal(proposal, 'evaluation_failed', {
+    terminalReason: governance.refusals?.join(', ') || 'governance-refused',
+  });
+  const refused = saveRecord(projectDir, {
+    ...record,
+    proposal: failed.ok ? failed.proposal : proposal,
+    governance,
+  });
+  return { ok: false, stage: governance.stage || 'governance', record: refused, governance, loopResult };
+}
+
+export function reviewRecord(projectDir, id, { knownApprovers = null, resolvedDependencies = [] } = {}) {
+  const record = loadRecord(projectDir, id);
+  if (!record) return { ok: false, error: 'not-found' };
+
+  const approvers = knownApprovers || resolveKnownApprovers(projectDir);
+  const governance = governProposal({
+    proposal: record.proposal,
+    dataset: record.dataset,
+    evaluationReport: record.evaluationReport,
+    knownApprovers: approvers,
+    resolvedDependencies,
+  });
+
+  const next = mergeGovernance(projectDir, record, governance);
+  return { ok: true, record: next, governance };
+}
+
+export function listPending(projectDir) {
+  return listRecords(projectDir, { state: 'awaiting_approval' });
+}
+
+export function approveRecord(projectDir, id, { identity = null, knownApprovers = null, nowIso = null } = {}) {
+  const record = loadRecord(projectDir, id);
+  if (!record) return { ok: false, error: 'not-found' };
+
+  const approvers = knownApprovers || resolveKnownApprovers(projectDir);
+  const who = identity || record.proposal?.approver?.identity || approvers[0] || null;
+  const approved = requireApproval({
+    proposal: record.proposal,
+    approval: { identity: who, approvedAt: nowIso || new Date().toISOString() },
+    knownApprovers: approvers,
+    nowIso,
+  });
+  if (!approved.ok) return approved;
+
+  const rollout = planRollout({ proposal: approved.proposal });
+  const saved = saveRecord(projectDir, {
+    ...record,
+    projectDir,
+    proposal: approved.proposal,
+    rolloutPlan: rollout.ok ? rollout.plan : null,
+  });
+  return { ok: true, record: saved, rollout };
+}
+
+export function applyRecord(projectDir, id, { monitor = null, nowIso = null } = {}) {
+  const record = loadRecord(projectDir, id);
+  if (!record) return { ok: false, error: 'not-found' };
+
+  const applied = recordApplication({
+    proposal: record.proposal,
+    monitor: monitor || `monitor-${id}`,
+    nowIso: nowIso || new Date().toISOString(),
+  });
+  if (!applied.ok) return applied;
+
+  const saved = saveRecord(projectDir, { ...record, projectDir, proposal: applied.proposal });
+  return { ok: true, record: saved };
+}
+
+export function rollbackRecord(projectDir, id, { reason = 'operator-rollback', nowIso = null } = {}) {
+  const record = loadRecord(projectDir, id);
+  if (!record) return { ok: false, error: 'not-found' };
+
+  const rolled = recordRollback({
+    proposal: record.proposal,
+    reason,
+    nowIso: nowIso || new Date().toISOString(),
+  });
+  if (!rolled.ok) return rolled;
+
+  const saved = saveRecord(projectDir, { ...record, projectDir, proposal: rolled.proposal });
+  return { ok: true, record: saved };
+}
+
+export function formatReviewSummary(record, governance = record?.governance) {
+  const p = record?.proposal || {};
+  const lines = [
+    `Proposal ${p.id} · ${p.type} · ${p.state}`,
+    `Profiles: ${(p.affectedProfiles || []).join(', ') || '—'}`,
+    `Blast radius: ${p.blastRadius}`,
+    `Baseline → candidate: ${p.lineage?.baselineVersion} → ${p.lineage?.candidateVersion}`,
+  ];
+  if (governance) {
+    lines.push(`Governance: ${governance.admissible ? 'admissible' : 'refused'} (${governance.stage || '—'})`);
+    if (governance.refusals?.length) lines.push(`Refusals: ${governance.refusals.join(', ')}`);
+  }
+  if (record?.rolloutPlan) {
+    lines.push(`Rollout: ${record.rolloutPlan.mode} · ${record.rolloutPlan.steps?.join(' → ')}`);
+  }
+  return lines.join('\n');
+}

package/lib/ingest-tooling.mjs

@@ -0,0 +1,97 @@
+/**
+ * lib/ingest-tooling.mjs — detect optional binaries for document ingestion.
+ *
+ * Probes docling venv, whisper-cli, unpdf/mammoth optional deps, and
+ * docling-remote URL config for construct tools detect and doctor.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { resolveDoclingServeUrl } from './ingest/docling-remote.mjs';
+
+function whichBin(name) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(cmd, [name], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return (result.stdout || '').trim().split('\n')[0] || null;
+}
+
+export function doclingVenvPath(cwd = process.cwd()) {
+  return path.join(cwd, '.cx', 'runtime', 'docling', '.venv');
+}
+
+export function detectDoclingSidecar({ cwd = process.cwd() } = {}) {
+  const venv = doclingVenvPath(cwd);
+  const python = process.platform === 'win32'
+    ? path.join(venv, 'Scripts', 'python.exe')
+    : path.join(venv, 'bin', 'python');
+  const present = fs.existsSync(python);
+  return {
+    ok: true,
+    present,
+    venvDir: venv,
+    pythonBin: present ? python : null,
+    message: present
+      ? `Docling venv ready at ${venv}`
+      : 'Docling not provisioned — runs on first high-fidelity ingest or construct install --with-docling',
+  };
+}
+
+export function detectNodeNativeDeps({ repoRoot = process.cwd() } = {}) {
+  const unpdf = fs.existsSync(path.join(repoRoot, 'node_modules', 'unpdf'));
+  const mammoth = fs.existsSync(path.join(repoRoot, 'node_modules', 'mammoth'));
+  const present = unpdf && mammoth;
+  return {
+    ok: true,
+    present,
+    unpdf,
+    mammoth,
+    message: present
+      ? 'Node-native extraction ready (unpdf + mammoth)'
+      : `Missing optional deps: ${[!unpdf && 'unpdf', !mammoth && 'mammoth'].filter(Boolean).join(', ') || 'none'}`,
+  };
+}
+
+export function detectWhisper(env = process.env) {
+  const cli = whichBin('whisper-cli') || whichBin('whisper');
+  return {
+    ok: true,
+    present: Boolean(cli),
+    path: cli,
+    message: cli
+      ? `ASR ready (${cli})`
+      : 'Install whisper-cpp for audio/video ingest (brew install whisper-cpp on macOS)',
+  };
+}
+
+export function detectDoclingRemote(env = process.env) {
+  const url = resolveDoclingServeUrl(env);
+  return {
+    ok: true,
+    present: Boolean(url),
+    url: url || null,
+    message: url
+      ? `docling-remote configured (${url})`
+      : 'Set DOCLING_SERVE_URL for docling-remote ingest strategy',
+  };
+}
+
+export function detectIngestPipeline({ cwd = process.cwd(), env = process.env, repoRoot = cwd } = {}) {
+  const steps = {
+    docling: detectDoclingSidecar({ cwd }),
+    nodeNative: detectNodeNativeDeps({ repoRoot }),
+    whisper: detectWhisper(env),
+    doclingRemote: detectDoclingRemote(env),
+  };
+  return {
+    ok: true,
+    present: steps.docling.present || steps.nodeNative.present,
+    steps,
+    message: steps.docling.present
+      ? 'Ingest: high-fidelity docling ready'
+      : steps.nodeNative.present
+        ? 'Ingest: fast tier ready (unpdf/mammoth); high-fidelity provisions on first use'
+        : 'Ingest degraded — install optional deps or run construct install --with-docling',
+  };
+}

package/lib/init/doc-lanes.mjs

@@ -0,0 +1,165 @@
+/**
+ * lib/init/doc-lanes.mjs — shared documentation lane definitions for init flows.
+ *
+ * Single source for DOC_LANES, presets, lane order, and alias normalization used
+ * by both `construct init` (init-unified) and the legacy init-docs entrypoint.
+ */
+
+export const DOC_LANES = {
+  adrs: {
+    title: 'ADRs',
+    dir: 'adr',
+    description: 'Architecture decision records for decisions that have already been made.',
+    templates: ['adr.md'],
+  },
+  briefs: {
+    title: 'Briefs',
+    dir: 'briefs',
+    description: 'Research, evidence, signal, and one-pager style documents.',
+    templates: [
+      'research-brief.md',
+      'evidence-brief.md',
+      'signal-brief.md',
+      'one-pager.md',
+      'customer-profile.md',
+      'product-intelligence-report.md',
+      'backlog-proposal.md',
+    ],
+  },
+  changelogs: {
+    title: 'Changelogs',
+    dir: 'changelogs',
+    description: 'User-facing release notes and version history entries.',
+    templates: ['changelog-entry.md'],
+  },
+  intake: {
+    title: 'Intake',
+    dir: 'intake',
+    description: 'Intake batch records that explain what arrived, why it matters, and how it should be ingested.',
+    templates: ['__intake-template__'],
+  },
+  memos: {
+    title: 'Memos',
+    dir: 'memos',
+    description: 'Decision memos and internal arguments for alignment and approval.',
+    templates: ['memo.md'],
+  },
+  meetings: {
+    title: 'Meetings',
+    dir: 'meetings',
+    description: 'Meeting notes, minutes, retros, standups, planning sessions, and agendas.',
+    templates: ['__meeting-notes-template__'],
+  },
+  notes: {
+    title: 'Notes',
+    dir: 'notes',
+    description: 'Working notes and lightweight durable context outside formal docs or meetings.',
+    templates: ['__notes-template__'],
+  },
+  onboarding: {
+    title: 'Onboarding',
+    dir: 'onboarding',
+    description: 'Runnable setup guides and first-day workflows for engineers, product, or ops.',
+    templates: ['onboarding.md'],
+  },
+  postmortems: {
+    title: 'Postmortems',
+    dir: 'postmortems',
+    description: 'Blameless incident reports: timeline, root cause, contributing factors, and corrective actions.',
+    templates: ['incident-report.md'],
+  },
+  prds: {
+    title: 'PRDs',
+    dir: 'prds',
+    description: 'Product and capability requirement documents.',
+    templates: ['prd.md', 'meta-prd.md', 'prd-business.md', 'prd-platform.md', 'prfaq.md'],
+  },
+  rfcs: {
+    title: 'RFCs',
+    dir: 'rfcs',
+    description: 'Architecture and implementation proposals that need review before a decision.',
+    templates: ['rfc.md', 'rfc-platform.md'],
+  },
+  runbooks: {
+    title: 'Runbooks',
+    dir: 'runbooks',
+    description: 'Operational procedures, diagnostics, remediation, and escalation paths.',
+    templates: ['runbook.md'],
+  },
+};
+
+export const LANE_ORDER = ['adrs', 'briefs', 'changelogs', 'intake', 'memos', 'meetings', 'notes', 'onboarding', 'postmortems', 'prds', 'rfcs', 'runbooks'];
+
+export const DOC_PRESETS = {
+  lean: ['adrs', 'intake', 'memos', 'meetings', 'notes', 'prds'],
+  product: ['adrs', 'intake', 'memos', 'meetings', 'notes', 'prds', 'rfcs'],
+  full: LANE_ORDER,
+};
+
+export const DEFAULT_LANES = DOC_PRESETS.lean;
+
+export const LANE_ALIASES = {
+  adr: 'adrs',
+  adrs: 'adrs',
+  brief: 'briefs',
+  briefs: 'briefs',
+  changelog: 'changelogs',
+  changelogs: 'changelogs',
+  releases: 'changelogs',
+  release: 'changelogs',
+  intake: 'intake',
+  memo: 'memos',
+  memos: 'memos',
+  meeting: 'meetings',
+  meetings: 'meetings',
+  minutes: 'meetings',
+  retro: 'meetings',
+  note: 'notes',
+  notes: 'notes',
+  onboard: 'onboarding',
+  onboarding: 'onboarding',
+  postmortem: 'postmortems',
+  postmortems: 'postmortems',
+  incident: 'postmortems',
+  incidents: 'postmortems',
+  prd: 'prds',
+  prds: 'prds',
+  rfc: 'rfcs',
+  rfcs: 'rfcs',
+  runbook: 'runbooks',
+  runbooks: 'runbooks',
+};
+
+export function normalizeLaneKey(name) {
+  return LANE_ALIASES[name.trim().toLowerCase()] ?? name.trim().toLowerCase();
+}
+
+export function normalizeCustomLaneName(name) {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export function parseCsvList(value) {
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function parseSelectableLanes(value) {
+  return value
+    .split(/[,\n]/)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      if (/^\d+$/.test(entry)) {
+        const lane = LANE_ORDER[Number(entry) - 1];
+        return lane ?? '';
+      }
+      return normalizeLaneKey(entry);
+    })
+    .filter((lane) => lane in DOC_LANES);
+}