@geraldmaron/construct 1.0.18 → 1.0.19

package/README.md

@@ -177,16 +177,16 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | Command | What it does |
 |---|---|
 | `construct efficiency` | Show read efficiency, repeated files, and context-budget guidance |
-| `construct eval-datasets` | Sync scored Langfuse traces into eval datasets for prompt regression testing |
+| `construct eval-datasets` | Sync scored traces from the telemetry backend into eval datasets for prompt regression testing |
 | `construct evals` | Show evaluator catalog for prompt and agent experiments |
 | `construct feedback:history` | Show recorded outcome ratings |
 | `construct feedback:record` | Record an outcome rating for a recent specialist invocation |
 | `construct llm-judge` | Run LLM-as-a-judge evaluations on unscored traces for continuous quality feedback |
-| `construct optimize` | Prompt optimization using Langfuse trace quality scores |
-| `construct review` | Generate agent performance review from Langfuse trace backend |
+| `construct optimize` | Prompt optimization using telemetry trace quality scores |
+| `construct review` | Generate agent performance review from the configured telemetry trace backend |
 | `construct telemetry` | Query telemetry traces and latency data |
 | `construct telemetry-backfill` | Backfill sparse traces with observations (trace backend) |
-| `construct telemetry-setup` | Configure Langfuse credentials and trace export |
+| `construct telemetry-setup` | Configure telemetry backend credentials and trace export (OTLP or Langfuse-compatible) |
 
 ### Diagnostics
 
@@ -212,6 +212,8 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct ci` | Local CI mirror: run CI jobs locally or view recent run status |
 | `construct completions` | Shell completion scripts |
 | `construct config` | Deployment mode configuration |
+| `construct decisions` | Index load-bearing decisions and their enforcement bindings |
+| `construct deployment` | Deployment posture tools (capability parity contract) |
 | `construct diff` | Show agent changes since HEAD |
 | `construct embed` | Embed mode management |
 | `construct gates:audit` | Audit policy gates |

package/bin/construct

@@ -1441,9 +1441,19 @@ async function cmdSearch(args) {
 async function cmdStorage(args) {
   const [action, ...rest] = args;
   if (!action) {
-    errorln('Usage: construct storage <sync|status|reset|delete-ingested|repair-migrations|migrations>');
+    errorln('Usage: construct storage <sync|status|reset|reconcile|delete-ingested|repair-migrations|migrations>');
     process.exit(1);
   }
+  if (action === 'reconcile') {
+    const { reconcileObservationEmbeddings } = await import('../lib/embed/reconcile.mjs');
+    const result = await reconcileObservationEmbeddings(process.cwd());
+    if (result.skipped) {
+      println(`Reconcile skipped: ${result.skipped} (no Postgres backend — local index is authoritative).`);
+      return;
+    }
+    println(`Reconciled observations: re-embedded ${result.reembedded} of ${result.checked} (model ${result.model}).`);
+    return;
+  }
   if (action === 'migrations') {
     const { describeMigrations } = await import('../lib/storage/migrations.mjs');
     const sqlClient = createSqlClient(process.env);
@@ -4097,7 +4107,7 @@ async function cmdCiPreview(args) {
   const jobsSection = jobsStart >= 0 ? yml.slice(jobsStart + 1) : '';
 
   // Find all top-level job keys (2-space indent) and slice blocks between them.
-  const jobKeyPattern = /^  (\w[\w-]*):\s*$/gm;
+  const jobKeyPattern = /^ {2}(\w[\w-]*):\s*$/gm;
   const jobPositions = [];
   let km;
   while ((km = jobKeyPattern.exec(jobsSection)) !== null) {
@@ -4111,7 +4121,7 @@ async function cmdCiPreview(args) {
     const end = jobPositions[i + 1]?.start ?? jobsSection.length;
     const block = jobsSection.slice(start, end);
 
-    const nameMatch = block.match(/^    name:\s*(.+)\s*$/m);
+    const nameMatch = block.match(/^ {4}name:\s*(.+)\s*$/m);
     const displayName = nameMatch
       ? nameMatch[1].replace(/\$\{\{[^}]+\}\}/g, '<matrix>').trim()
       : id;
@@ -5173,6 +5183,19 @@ const handlers = new Map([
   ['lint:research', cmdLintResearch],
   ['lint:agents', cmdLintAgents],
   ['lint:contracts', cmdLintContracts],
+  ['decisions', async (args) => {
+    const { runDecisionsCli } = await import('../lib/decisions/registry.mjs');
+    return runDecisionsCli(args);
+  }],
+  ['deployment', async (args) => {
+    const sub = args[0];
+    if (sub === 'parity') {
+      const { runDeploymentParityCli } = await import('../lib/deployment/parity-contract.mjs');
+      return runDeploymentParityCli(args.slice(1));
+    }
+    errorln(`Unknown deployment subcommand: ${sub || '(none)'}. Available: parity`);
+    process.exit(1);
+  }],
   ['audit', async (args) => {
     const sub = args[0];
     if (sub === 'skills') return runAuditSkillsCli(args.slice(1));

package/db/schema/003_observation_reconciliation.sql

@@ -0,0 +1,14 @@
+-- db/schema/003_observation_reconciliation.sql
+-- Stamp each observation with the content hash and embedding model that
+-- produced its vector. An idempotent reconciliation pass uses (content_hash,
+-- model) to find rows whose embedding is missing or stale — content edited, or
+-- the embedding model changed — and re-embed only those, rather than relying on
+-- the inline write at creation time always succeeding. Mirrors the
+-- (content_hash, model) tracking construct_embeddings already carries for
+-- documents. Fully idempotent: safe to re-apply.
+
+ALTER TABLE construct_observations ADD COLUMN IF NOT EXISTS content_hash text;
+ALTER TABLE construct_observations ADD COLUMN IF NOT EXISTS model text;
+
+CREATE INDEX IF NOT EXISTS idx_observations_content_hash ON construct_observations (content_hash);
+CREATE INDEX IF NOT EXISTS idx_observations_model ON construct_observations (model);

package/lib/bootstrap/resources.mjs

@@ -17,7 +17,6 @@
  * The registry is consulted by:
  *   - `construct init`         walks every resource, asks consent, installs
  *   - `construct doctor --bootstrap`  re-probes every resource verbosely
- *   - lazy-install paths in hooks (consult the cached consent silently)
  *
  * Resources are "additive" — anyone can register a new resource via
  * `registerResource()` so plugins (or future built-ins) can extend the set

package/lib/cli-commands.mjs

@@ -373,7 +373,7 @@ export const CLI_COMMANDS = [
     emoji: '📈',
     category: 'Observability',
     core: false,
-    description: 'Generate agent performance review from Langfuse trace backend',
+    description: 'Generate agent performance review from the configured telemetry trace backend',
     usage: 'construct review [--agent=<id>] [--days=N]',
   },
   {
@@ -381,7 +381,7 @@ export const CLI_COMMANDS = [
     emoji: '⚙️',
     category: 'Observability',
     core: false,
-    description: 'Prompt optimization using Langfuse trace quality scores',
+    description: 'Prompt optimization using telemetry trace quality scores',
     usage: 'construct optimize <agent>',
   },
   {
@@ -397,7 +397,7 @@ export const CLI_COMMANDS = [
     emoji: '📊',
     category: 'Observability',
     core: false,
-    description: 'Sync scored Langfuse traces into eval datasets for prompt regression testing',
+    description: 'Sync scored traces from the telemetry backend into eval datasets for prompt regression testing',
     usage: 'construct eval-datasets',
   },
   {
@@ -580,7 +580,7 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Role framework management',
-    usage: 'construct role <list|set|latest>',
+    usage: 'construct role <list|latest|show|status|resolve|prune|reset>',
   },
   {
     name: 'embed',
@@ -646,6 +646,34 @@ export const CLI_COMMANDS = [
     description: 'Audit policy gates',
     usage: 'construct gates:audit',
   },
+  {
+    name: 'decisions',
+    emoji: '🧭',
+    category: 'Advanced',
+    core: false,
+    description: 'Index load-bearing decisions and their enforcement bindings',
+    usage: 'construct decisions [list|validate|json|check|baseline|golden]',
+    options: [
+      { flag: 'list', desc: 'Show decisions with status and enforcement (default)' },
+      { flag: 'validate', desc: 'Validate registry structure; exit 1 on error' },
+      { flag: 'check', desc: 'Fail on dangling markers, enforcement/supersede/linkage/precedence drift' },
+      { flag: 'baseline', desc: 'Print the enforced baseline; --write to regenerate it' },
+      { flag: 'golden', desc: 'Check the CLI/agent/hook surface snapshot; --write to regenerate it' },
+      { flag: 'json', desc: 'Emit the full registry as JSON' },
+    ],
+  },
+  {
+    name: 'deployment',
+    emoji: '🛰️',
+    category: 'Advanced',
+    core: false,
+    description: 'Deployment posture tools (capability parity contract)',
+    usage: 'construct deployment parity',
+    options: [
+      { flag: 'parity', desc: 'Show and validate capability parity across solo/team/enterprise' },
+      { flag: '--json', desc: 'Emit the parity contract as JSON' },
+    ],
+  },
   {
     name: 'policy',
     emoji: '🔒',
@@ -838,7 +866,7 @@ export const CLI_COMMANDS = [
     emoji: '🩹',
     category: 'Observability',
     core: false,
-    description: 'Configure Langfuse credentials and trace export',
+    description: 'Configure telemetry backend credentials and trace export (OTLP or Langfuse-compatible)',
     usage: 'construct telemetry-setup',
   },
   // ── Internal — callable but not advertised in help or completions ────

package/lib/comment-lint.mjs

@@ -223,6 +223,49 @@ function hasCitationNearby(lines, idx) {
   return false;
 }
 
+// A citation marker proves nothing if it resolves to nothing. Two marker kinds
+// are mechanically verifiable offline: a `[^n]` footnote must have a matching
+// `[^n]:` definition, and a `[source: <repo-path>]` must point at a file that
+// exists. URLs and free-text sources are left alone — unverifiable here, and
+// flagging them would punish honest prose. Skip code fences and tables so regex
+// examples and tabular data never read as dangling citations.
+
+function looksLikeRepoPath(value) {
+  return /^[\w./@-]+$/.test(value) && value.includes('/') && !/^https?:/i.test(value);
+}
+
+export function findDanglingCitations(content, { rootDir = process.cwd() } = {}) {
+  const lines = content.split('\n');
+  const skip = buildSkipMap(lines);
+  const defs = new Set();
+  lines.forEach((line, i) => {
+    if (skip[i]) return;
+    const d = line.match(/^\s*\[\^([^\]]+)\]:/);
+    if (d) defs.add(d[1]);
+  });
+
+  const violations = [];
+  lines.forEach((line, i) => {
+    if (skip[i] || line.includes('construct-lint-ignore')) return;
+    const scan = line.replace(/`[^`]*`/g, '');
+    let m;
+    const refRe = /\[\^([^\]]+)\](?!:)/g;
+    while ((m = refRe.exec(scan)) !== null) {
+      if (!defs.has(m[1])) {
+        violations.push({ line: i + 1, label: `dangling footnote citation [^${m[1]}] has no definition`, kind: 'artifact' });
+      }
+    }
+    const srcRe = /\[source:\s*([^\]]+)\]/gi;
+    while ((m = srcRe.exec(scan)) !== null) {
+      const value = m[1].trim();
+      if (looksLikeRepoPath(value) && !fs.existsSync(path.resolve(rootDir, value))) {
+        violations.push({ line: i + 1, label: `citation source path not found: ${value}`, kind: 'artifact' });
+      }
+    }
+  });
+  return violations;
+}
+
 function checkArtifactBanned(content, rel) {
   if (!isArtifactPath(rel)) return [];
   const lines = content.split('\n');
@@ -316,6 +359,7 @@ export function lintFile(filePath, { rootDir = process.cwd(), fix = false } = {}
   // kind:'artifact' so the hook can let the edit through while still surfacing
   // the finding.
   const artifactHits = checkArtifactBanned(content, rel);
+  if (isArtifactPath(rel)) artifactHits.push(...findDanglingCitations(content, { rootDir }));
   if (artifactHits.length > 0) {
     const mode = process.env.CONSTRUCT_ARTIFACT_LINT_MODE || 'warn';
     const bucket = mode === 'block' ? errors : warnings;

package/lib/contracts/validate.mjs

@@ -300,6 +300,77 @@ function hasSection(body, sectionTitle) {
   return false;
 }
 
+// A fenced ```mermaid block, optionally of a required diagram kind (the kind is
+// matched against the first keyword inside the fence, e.g. flowchart, sequenceDiagram).
+
+function hasMermaid(body, kind) {
+  const re = /```mermaid\s*\n([\s\S]*?)```/g;
+  let m;
+  while ((m = re.exec(body))) {
+    if (!kind) return true;
+    if (new RegExp(`\\b${kind}\\b`, 'i').test(m[1])) return true;
+  }
+  return false;
+}
+
+function hasTable(body) {
+  const lines = body.split('\n');
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (/\|/.test(lines[i]) && /^\s*\|?[\s:-]*-[\s:|-]*\|?\s*$/.test(lines[i + 1]) && lines[i + 1].includes('-')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Header rows of every GFM table in the body, each as a lowercased cell list.
+// A table is a `| ... |` line immediately followed by a `|---|` separator row.
+
+function tableHeaderRows(body) {
+  const lines = body.split('\n');
+  const headers = [];
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (/\|/.test(lines[i]) && /^\s*\|?[\s:-]*-[\s:|-]*\|?\s*$/.test(lines[i + 1]) && lines[i + 1].includes('-')) {
+      const cells = lines[i].split('|').map((c) => c.trim().toLowerCase()).filter(Boolean);
+      headers.push({ line: i + 1, cells, rowsBelow: countRows(lines, i + 2) });
+    }
+  }
+  return headers;
+}
+
+function countRows(lines, start) {
+  let n = 0;
+  for (let i = start; i < lines.length; i++) {
+    if (/^\s*\|/.test(lines[i]) || (/\|/.test(lines[i]) && lines[i].trim())) n += 1;
+    else break;
+  }
+  return n;
+}
+
+function tableWithColumns(body, columns) {
+  const want = columns.map((c) => c.trim().toLowerCase());
+  for (const header of tableHeaderRows(body)) {
+    if (want.every((w) => header.cells.includes(w))) return header;
+  }
+  return null;
+}
+
+function sectionIsNonEmpty(body, sectionTitle) {
+  const target = sectionTitle.trim().toLowerCase();
+  const lines = body.split('\n');
+  let inSection = false;
+  for (const line of lines) {
+    const heading = line.match(/^#{1,6}\s+(.+)$/);
+    if (heading) {
+      if (inSection) return false;
+      inSection = heading[1].trim().toLowerCase() === target;
+      continue;
+    }
+    if (inSection && line.trim() && !line.trim().startsWith('<!--')) return true;
+  }
+  return false;
+}
+
 function claimsHaveCitations(body) {
   const lines = body.split('\n');
   const offenders = [];
@@ -367,6 +438,41 @@ export function validateArtifactPostconditions({ contract, artifactPath }) {
         }
         break;
       }
+      case 'artifact-has-mermaid': {
+        if (!hasMermaid(body, pc.diagram)) {
+          errors.push(`[${tag}] artifact missing required mermaid diagram${pc.diagram ? ` (${pc.diagram})` : ''}`);
+        }
+        break;
+      }
+      case 'artifact-has-table': {
+        if (!hasTable(body)) {
+          errors.push(`[${tag}] artifact missing a required table`);
+        }
+        break;
+      }
+      case 'artifact-table-has-columns': {
+        if (!Array.isArray(pc.columns) || pc.columns.length === 0) {
+          errors.push(`[${tag}] postcondition missing 'columns' for artifact-table-has-columns`);
+          break;
+        }
+        const match = tableWithColumns(body, pc.columns);
+        if (!match) {
+          errors.push(`[${tag}] no table has the required columns: ${pc.columns.join(', ')}`);
+        } else if (match.rowsBelow === 0) {
+          errors.push(`[${tag}] required table (${pc.columns.join(', ')}) has no data rows`);
+        }
+        break;
+      }
+      case 'artifact-section-nonempty': {
+        if (!pc.section) {
+          errors.push(`[${tag}] postcondition missing 'section' for artifact-section-nonempty`);
+          break;
+        }
+        if (!sectionIsNonEmpty(body, pc.section)) {
+          errors.push(`[${tag}] required section is empty or missing: "${pc.section}"`);
+        }
+        break;
+      }
       default:
         errors.push(`[${tag}] unknown postcondition check: ${pc.check}`);
     }

package/lib/decisions/enforced-baseline.json

@@ -0,0 +1,23 @@
+{
+  "enforced": [
+    "ADR-0015",
+    "ADR-0016",
+    "ADR-0017",
+    "ADR-0018",
+    "any-to-business-strategist",
+    "any-to-explorer",
+    "architect-to-data-engineer",
+    "architect-to-evaluator",
+    "architect-to-legal-compliance",
+    "construct-to-rd-lead",
+    "product-manager-to-architect",
+    "product-manager-to-data-analyst",
+    "product-manager-to-ux-researcher",
+    "qa-to-test-automation",
+    "researcher-to-product-manager",
+    "rule:common/comments",
+    "rule:common/no-fabrication",
+    "rule:common/precedence",
+    "rule:common/research-sources"
+  ]
+}

package/lib/decisions/golden.mjs

@@ -0,0 +1,87 @@
+/**
+ * lib/decisions/golden.mjs — behavioral golden snapshot of core surfaces.
+ *
+ * Pins the surfaces whose silent change is a drift hazard: the CLI command set,
+ * the specialist roster, and hook execution order. buildSurfaceSnapshot computes
+ * the live surface from source; a committed snapshot (tests/fixtures/golden/
+ * surface.json) is the expectation. A mismatch fails the suite until the snapshot
+ * is regenerated on purpose (`construct decisions golden --write`) — the same
+ * conscious-update discipline as the enforced baseline (bead wvbf.5).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const HOOK_EVENTS = ['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop'];
+
+function hookName(command) {
+  const m = command.match(/hooks\/([\w-]+)\.mjs/);
+  if (m) return m[1];
+  if (/node\s+-e/.test(command)) return 'inline';
+  return 'cmd';
+}
+
+export function buildSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+  const snapshot = { commands: [], agents: [], hooks: {} };
+
+  const cli = readFileSync(join(repoRoot, 'lib', 'cli-commands.mjs'), 'utf8');
+  const nameRe = /name:\s*'([^']+)'[\s\S]*?core:\s*(true|false)/g;
+  let m;
+  const seen = new Set();
+  while ((m = nameRe.exec(cli)) !== null) {
+    if (seen.has(m[1])) continue;
+    seen.add(m[1]);
+    snapshot.commands.push({ name: m[1], core: m[2] === 'true' });
+  }
+  snapshot.commands.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  const registry = JSON.parse(readFileSync(join(repoRoot, 'specialists', 'registry.json'), 'utf8'));
+  snapshot.agents = (registry.specialists || []).map((s) => s.name).sort();
+
+  const settings = JSON.parse(readFileSync(join(repoRoot, 'platforms', 'claude', 'settings.template.json'), 'utf8'));
+  for (const event of HOOK_EVENTS) {
+    const entries = settings.hooks?.[event] || [];
+    const ordered = [];
+    for (const entry of entries) {
+      for (const h of entry.hooks || []) ordered.push(hookName(h.command));
+    }
+    snapshot.hooks[event] = ordered;
+  }
+
+  return snapshot;
+}
+
+function snapshotPath(repoRoot) {
+  return join(repoRoot, 'tests', 'fixtures', 'golden', 'surface.json');
+}
+
+export function compareSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+  const file = snapshotPath(repoRoot);
+  if (!existsSync(file)) return { ok: false, diffs: ['no committed snapshot — run: construct decisions golden --write'] };
+  const expected = JSON.stringify(JSON.parse(readFileSync(file, 'utf8')));
+  const actual = JSON.stringify(buildSurfaceSnapshot({ repoRoot }));
+  if (expected === actual) return { ok: true, diffs: [] };
+  return { ok: false, diffs: ['surface snapshot drift — review the change, then regenerate with: construct decisions golden --write'] };
+}
+
+export function writeSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+  writeFileSync(snapshotPath(repoRoot), JSON.stringify(buildSurfaceSnapshot({ repoRoot }), null, 2) + '\n');
+}
+
+export async function runGoldenCli(args = []) {
+  if (args.includes('--write')) {
+    writeSurfaceSnapshot();
+    process.stdout.write('✓ wrote surface golden snapshot\n');
+    return;
+  }
+  const { ok, diffs } = compareSurfaceSnapshot();
+  if (ok) {
+    process.stdout.write('✓ surface matches the golden snapshot\n');
+    return;
+  }
+  for (const d of diffs) process.stderr.write(`✗ ${d}\n`);
+  process.exit(1);
+}

package/lib/decisions/precedence.mjs

@@ -0,0 +1,46 @@
+/**
+ * lib/decisions/precedence.mjs — explicit precedence for conflicting guidance.
+ *
+ * When two rules give contradictory direction, the conflict must resolve the same
+ * way every time, not by whichever the model read last. PRECEDENCE_TIERS is the
+ * canonical order (index 0 wins); a rule declares its tier in frontmatter
+ * (`precedence_tier`), and resolvePrecedence answers which of two tiers governs.
+ *
+ * Scope is deliberate: this provides deterministic TIER-based precedence, not
+ * natural-language contradiction detection. It makes the resolution order
+ * explicit and validates that declared tiers are real; judging whether two rules
+ * actually contradict remains human work. See rules/common/precedence.md.
+ */
+
+export const PRECEDENCE_TIERS = ['safety', 'security', 'correctness', 'durability', 'performance', 'style'];
+
+export function tierRank(tier) {
+  const i = PRECEDENCE_TIERS.indexOf(tier);
+  return i === -1 ? Number.POSITIVE_INFINITY : i;
+}
+
+/**
+ * Resolve which tier governs. Returns -1 if a wins, 1 if b wins, 0 if equal rank.
+ * A lower index is higher priority (safety beats style).
+ */
+export function resolvePrecedence(a, b) {
+  const ra = tierRank(a);
+  const rb = tierRank(b);
+  if (ra < rb) return -1;
+  if (ra > rb) return 1;
+  return 0;
+}
+
+/**
+ * Validate declared precedence tiers over a decisions array (bead wvbf.8): any
+ * rule that declares a `precedence_tier` must use one from PRECEDENCE_TIERS.
+ */
+export function validatePrecedenceTiersOn(decisions) {
+  const violations = [];
+  for (const d of decisions) {
+    if (d.precedenceTier && !PRECEDENCE_TIERS.includes(d.precedenceTier)) {
+      violations.push(`${d.id}: unknown precedence_tier "${d.precedenceTier}" (expected one of ${PRECEDENCE_TIERS.join(', ')})`);
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}