@geraldmaron/construct 1.3.1 → 1.4.0

package/lib/providers/secret-resolver.mjs

@@ -2,13 +2,22 @@
  * lib/providers/secret-resolver.mjs — single credential resolver for the LLM path.
  *
  * Resolves a canonical environment variable (for example ANTHROPIC_API_KEY) by
- * walking the same sources the rest of Construct trusts, in priority order:
- * process env, the XDG config dir config.env, ~/.env, the project .env, then shell rc
- * files (.zshrc/.bashrc/.bash_profile/.profile). When the value carries a
+ * walking Construct's credential sources in priority order: a direct value on the
+ * passed env, then the project .env, the XDG config dir config.env, ~/.env, the
+ * alternate provider stores (Construct creds store, OpenCode provider config), the
+ * CONSTRUCT_OP_ENV_FILE catalog, and finally shell rc files
+ * (.zshrc/.bashrc/.bash_profile/.profile). The file tier matches loadConstructEnv:
+ * the project .env wins over the machine-wide config.env. When the value carries a
  * 1Password reference — a bare `op://vault/item/field` or the shell form
  * `$(op read 'op://...')` — it is resolved through the `op` CLI and cached for
  * the process lifetime so a single launch prompts at most once per reference.
  *
+ * One divergence from loadConstructEnv is intentional and tracked separately: that
+ * merge ranks the config files above process.env to defeat stale shell exports,
+ * while this resolver honors a directly-passed env value first so a hermetic caller
+ * can inject its own credentials. Unifying the process.env tier touches the live
+ * LLM path and is deferred to a follow-up.
+ *
  * resolveSecret performs the `op read` (and may surface a structured
  * SecretResolutionError); hasSecret only checks presence and never invokes the
  * CLI, so detection stays fast and free of biometric prompts. The plaintext
@@ -33,6 +42,30 @@ const OP_READ_TIMEOUT_MS = 20000;
 
 const opCache = new Map();
 
+let auditSink = null;
+
+// A structured, value-free record of resolution events: which variable, which
+// source tier, whether it carried an op:// reference, cache-hit, and the outcome —
+// never the materialized secret. The sink defaults to none (hermetic); a caller
+// wires it to the observation store. Sink failures never disrupt resolution.
+
+export function setSecretAuditSink(sink) {
+  auditSink = typeof sink === 'function' ? sink : null;
+}
+
+export function __resetSecretAuditSink() {
+  auditSink = null;
+}
+
+function emitAudit(event) {
+  if (!auditSink) return;
+  try {
+    auditSink(event);
+  } catch {
+    /* audit is best-effort */
+  }
+}
+
 export class SecretResolutionError extends Error {
   constructor(message, code) {
     super(message);
@@ -74,10 +107,19 @@ function defaultOpRead(opRef) {
 }
 
 export function resolveOpRef(opRef, { opRead = defaultOpRead } = {}) {
-  if (opCache.has(opRef)) return opCache.get(opRef);
-  const secret = opRead(opRef);
-  opCache.set(opRef, secret);
-  return secret;
+  if (opCache.has(opRef)) {
+    emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: true, ok: true });
+    return opCache.get(opRef);
+  }
+  try {
+    const secret = opRead(opRef);
+    opCache.set(opRef, secret);
+    emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: false, ok: true });
+    return secret;
+  } catch (err) {
+    emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: false, ok: false, code: err?.code });
+    throw err;
+  }
 }
 
 function materialize(rawValue, opts) {
@@ -140,26 +182,54 @@ function readFromOpEnvCatalog(varName, { env, home }) {
 
 function rawCandidate(varName, { env, cwd, home }) {
   const direct = env?.[varName];
-  if (typeof direct === 'string' && direct.length > 0) return direct;
-  const files = [path.join(configDir(home), 'config.env'), path.join(home, '.env'), path.join(cwd, '.env')];
-  for (const file of files) {
+  if (typeof direct === 'string' && direct.length > 0) return { raw: direct, source: 'env' };
+
+  // File tier matches loadConstructEnv: the project .env (closest to the work)
+  // wins over the machine-wide XDG config.env, which wins over a generic ~/.env.
+  const files = [
+    { file: path.join(cwd, '.env'), source: 'project-env' },
+    { file: path.join(configDir(home), 'config.env'), source: 'config-env' },
+    { file: path.join(home, '.env'), source: 'home-env' },
+  ];
+  for (const { file, source } of files) {
     const value = readDotenvVar(file, varName);
-    if (value) return value;
+    if (value) return { raw: value, source };
   }
   const alt = discoverAlternateRawForVar(varName, { home });
-  if (alt) return alt;
+  if (alt) return { raw: alt, source: 'alt-store' };
   const fromOpCatalog = readFromOpEnvCatalog(varName, { env, home });
-  if (fromOpCatalog) return fromOpCatalog;
-  return readShellRcVar(varName, home);
+  if (fromOpCatalog) return { raw: fromOpCatalog, source: 'op-catalog' };
+  const fromRc = readShellRcVar(varName, home);
+  if (fromRc) return { raw: fromRc, source: 'shell-rc' };
+  return null;
+}
+
+function resolveAndAudit(varName, raw, source, opts) {
+  const isOpRef = Boolean(extractOpRef(raw));
+  try {
+    const value = materialize(raw, opts);
+    emitAudit({ event: 'secret.resolve', varName, source, isOpRef, ok: true });
+    return value;
+  } catch (err) {
+    emitAudit({ event: 'secret.resolve', varName, source, isOpRef, ok: false, code: err?.code });
+    throw err;
+  }
 }
 
 export function resolveSecret(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true, opRead } = {}) {
   const direct = env?.[varName];
-  if (typeof direct === 'string' && direct.length > 0) return materialize(direct, { opRead });
-  if (!allowAmbient) return null;
+  if (typeof direct === 'string' && direct.length > 0) return resolveAndAudit(varName, direct, 'env', { opRead });
+  if (!allowAmbient) {
+    emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
+    return null;
+  }
   const home = os.homedir();
-  const raw = rawCandidate(varName, { env, cwd, home });
-  return raw ? materialize(raw, { opRead }) : null;
+  const found = rawCandidate(varName, { env, cwd, home });
+  if (!found) {
+    emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
+    return null;
+  }
+  return resolveAndAudit(varName, found.raw, found.source, { opRead });
 }
 
 export function resolveFirstSecret(varNames, opts = {}) {
@@ -178,8 +248,8 @@ export function hasSecret(varName, { env = process.env, cwd = process.cwd(), all
   if (typeof direct === 'string' && direct.length > 0) return true;
   if (!allowAmbient) return false;
   const home = os.homedir();
-  const raw = rawCandidate(varName, { env, cwd, home });
-  return typeof raw === 'string' && raw.length > 0;
+  const found = rawCandidate(varName, { env, cwd, home });
+  return Boolean(found && typeof found.raw === 'string' && found.raw.length > 0);
 }
 
 export function hasAnySecret(varNames, opts = {}) {

package/lib/publish.mjs

@@ -15,6 +15,9 @@ import { loadDemoRecording } from './demo-recording.mjs';
 import { recordPlaywrightDemo } from './playwright-demo.mjs';
 import { validateArtifactRelease } from './artifact-release-gate.mjs';
 import { inferArtifactTypeFromPath } from './artifact-type-from-path.mjs';
+import { runOutputQuality } from './output-quality.mjs';
+import { resolveArtifactWorkflowContract } from './artifact-manifest.mjs';
+import { resolveGateLevel } from './artifact-gate-levels.mjs';
 
 export { parsePublishFrontmatter };
 
@@ -50,6 +53,7 @@ export function runPublish({
   strict = true,
   sourceOnly = false,
   gate = true,
+  preview = false,
   artifactType = null,
   cwd = process.cwd(),
   repoRoot,
@@ -79,7 +83,7 @@ export function runPublish({
     env,
   });
 
-  const ledger = { export: null, demos: [], recordings: [], detection, gate: null };
+  const ledger = { export: null, demos: [], recordings: [], detection, gate: null, validation: null };
   const resolvedType = artifactType || inferArtifactTypeFromPath(resolvedIn, { rootDir: cwd });
 
   if (gate && !sourceOnly && resolvedType) {
@@ -123,6 +127,36 @@ export function runPublish({
     if (!ledger.export.ok && strict && !sourceOnly) {
       return { ok: false, strict: true, ledger, message: ledger.export.message };
     }
+
+    // Post-export output validation: validate the produced file, its content roundtrip, and
+    // its references; render-smoke and higher levels also capture screenshot evidence. The
+    // gate level comes from the artifact's quality contract (defaults to standard).
+
+    if (ledger.export.ok) {
+      let gateLevel = 'standard';
+      try {
+        const contract = resolveArtifactWorkflowContract(resolvedType, { rootDir: repoRoot || cwd, cwd });
+        gateLevel = resolveGateLevel(contract?.qualityContract);
+      } catch { /* default level */ }
+
+      // --preview forces a render so the user can inspect output before claiming done, even when
+      // the artifact's own gate level would not otherwise capture screenshots.
+      if (preview && gateLevel !== 'full-certification' && gateLevel !== 'human-reviewed') {
+        gateLevel = 'render-smoke';
+      }
+      const sourceMarkdown = fs.readFileSync(resolvedIn, 'utf8');
+      const diagramStrict = /^---\n[\s\S]*?\bcx_diagram_quality:\s*strict\b[\s\S]*?\n---/.test(sourceMarkdown);
+      ledger.validation = runOutputQuality({
+        exportPath: ledger.export.outputPath,
+        format,
+        sourceMarkdown,
+        baseDir: path.dirname(resolvedIn),
+        gateLevel,
+        diagramStrict,
+        rootDir: cwd,
+        env,
+      });
+    }
   } else {
     ledger.export = { ok: true, skipped: 'source-only' };
   }
@@ -183,6 +217,7 @@ Options:
   --demo=<name>           Terminal VHS tape name (repeatable)
   --recording=<name>      Playwright recording manifest (repeatable)
   --no-figures            Skip pandoc-ext/diagram filter
+  --preview               Render the export to images and report what was verified
   --no-gate               Skip artifact release gate (maintainer escape hatch)
   --source-only           Write sources only; skip rendering
   --no-strict             Do not exit 2 when toolchain or gate fails
@@ -211,6 +246,7 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     gate: true,
     sourceOnly: false,
     detect: false,
+    preview: false,
     help: false,
     input: null,
   };
@@ -223,6 +259,7 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     if (arg === '--source-only') { options.sourceOnly = true; continue; }
     if (arg === '--no-figures') { options.figures = false; continue; }
     if (arg === '--no-gate') { options.gate = false; continue; }
+    if (arg === '--preview') { options.preview = true; continue; }
     if (arg === '--detect') { options.detect = true; continue; }
     if (arg === '--to') { options.format = argv[++i]; continue; }
     if (arg.startsWith('--to=')) { options.format = arg.slice(5); continue; }
@@ -267,12 +304,38 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     gate: options.gate,
     artifactType: options.type,
     sourceOnly: options.sourceOnly,
+    preview: options.preview,
     cwd,
     repoRoot,
   });
 
   if (result.ok) {
     console.log(result.message);
+    const validation = result.ledger?.validation;
+    if (validation) {
+      const pdf = validation.checks?.pdf;
+      if (pdf?.pageCount) console.log(`  validity: ${pdf.pageCount} page(s)`);
+      const roundtrip = validation.checks?.roundtrip;
+      if (roundtrip && !roundtrip.degradation) console.log(`  content: ${roundtrip.message}`);
+      if (validation.render?.evidence && !validation.render.result?.degradation) {
+        console.log(`  render: ${validation.render.result.images.length} screenshot(s) captured`);
+        if (options.preview) for (const img of validation.render.result.images) console.log(`    ${path.relative(cwd, img)}`);
+      } else if (options.preview && validation.render?.result?.degradation) {
+        console.log(`  render: skipped (${validation.render.result.degradation})`);
+      }
+      for (const w of validation.diagrams?.warnings || []) {
+        console.log(`  diagram ${w.diagram} (${w.kind}): ${w.code} — ${w.detail}`);
+      }
+      const a11y = validation.a11y;
+      if (a11y && !a11y.unsupported) {
+        const checked = a11y.coverage.checked.map((c) => `${c.id}:${c.status}`).join(' ');
+        console.log(`  a11y [${a11y.format}]: ${checked}`);
+        if (a11y.coverage.uncheckable.length) {
+          console.log(`  a11y uncheckable: ${a11y.coverage.uncheckable.map((u) => u.id).join(', ')}`);
+        }
+      }
+      for (const f of validation.failures || []) console.log(`  ⚠ ${f}`);
+    }
     if (result.ledger?.demos?.length) {
       for (const d of result.ledger.demos) {
         if (d.tapePath) console.log(`  tape: ${d.tapePath}`);

package/lib/render-evidence.mjs

@@ -0,0 +1,55 @@
+/**
+ * lib/render-evidence.mjs — Bridge from the render pipeline to the completion ledger.
+ *
+ * captureRenderEvidence renders an artifact to images under a stable .cx/render path and returns a
+ * screenshot-captured evidence object. A successful render carries the image paths and a content
+ * digest as proof and advances the ladder; a degraded render carries the typed degradation reason
+ * so it is recorded for the trail but never lifts the state (highestState skips degraded entries).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderToImages } from './render-pipeline.mjs';
+import { makeEvidence } from './artifact-completion.mjs';
+
+export function renderEvidenceDir(rootDir, artifactName) {
+  return path.join(rootDir ?? process.cwd(), '.cx', 'render', artifactName);
+}
+
+// A digest over the rendered bytes lets a reader confirm the stored images are the ones the
+// evidence claims; null when nothing was produced.
+
+function digestImages(images) {
+  if (!images.length) return null;
+  const hash = crypto.createHash('sha256');
+  for (const image of images) hash.update(fs.readFileSync(image));
+  return `sha256:${hash.digest('hex')}`;
+}
+
+export function captureRenderEvidence({ format, inputPath, outDir, rootDir, actor = 'construct-render', env } = {}) {
+  const artifactName = path.basename(inputPath ?? `artifact.${format}`);
+  const dir = outDir ?? renderEvidenceDir(rootDir, artifactName);
+  const result = renderToImages({ format, inputPath, outDir: dir, env });
+
+  if (!result.ok) {
+    return {
+      result,
+      evidence: makeEvidence('screenshot-captured', {
+        actor,
+        artifact: inputPath ?? null,
+        degradation: result.degradation,
+        proof: { format, message: result.message },
+      }),
+    };
+  }
+
+  return {
+    result,
+    evidence: makeEvidence('screenshot-captured', {
+      actor,
+      artifact: inputPath,
+      digest: digestImages(result.images),
+      proof: { format, images: result.images, count: result.images.length, dir },
+    }),
+  };
+}

package/lib/render-pipeline.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/render-pipeline.mjs — Render exported artifacts to inspectable images.
+ *
+ * A declarative per-format renderer registry (PDF/HTML/PPTX → page or slide PNGs, Mermaid/D2 →
+ * SVG/PNG) plus availability detection that reuses the document-export binary probe. When a
+ * renderer is absent the result carries a typed degradation reason from the shared enum instead of
+ * a silent skip, so a caller can downgrade the completion state honestly. The actual render runs
+ * only when its tools resolve on PATH; detection and degradation need no tools and are
+ * deterministic.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { whichBin } from './document-export.mjs';
+
+const CHROME_CANDIDATES = ['chromium', 'chromium-browser', 'google-chrome', 'google-chrome-stable'];
+const SOFFICE_CANDIDATES = ['soffice', 'libreoffice'];
+
+// Each format declares the binaries its render needs (all must resolve), the image kind it emits,
+// and candidate names for tools that ship under different names per platform.
+
+export const RENDERERS = Object.freeze({
+  pdf: { tools: ['pdftoppm'], kind: 'png' },
+  html: { tools: ['chromium'], candidates: { chromium: CHROME_CANDIDATES }, kind: 'png' },
+  pptx: { tools: ['soffice', 'pdftoppm'], candidates: { soffice: SOFFICE_CANDIDATES }, kind: 'png' },
+  mermaid: { tools: ['mmdc'], kind: 'png' },
+  d2: { tools: ['d2'], kind: 'svg' },
+});
+
+export const RENDERABLE_FORMATS = Object.freeze(Object.keys(RENDERERS));
+
+function resolveTool(name, candidates, env) {
+  const names = candidates?.[name] ?? [name];
+  for (const candidate of names) {
+    const found = whichBin(candidate, env);
+    if (found) return { name, resolved: candidate, path: found };
+  }
+  return { name, resolved: null, path: null };
+}
+
+export function detectRenderer(format, env = process.env) {
+  const spec = RENDERERS[format];
+  if (!spec) {
+    return { format, available: false, unsupported: true, tools: [], missing: [], message: `No renderer for format: ${format}` };
+  }
+  const tools = spec.tools.map((tool) => resolveTool(tool, spec.candidates, env));
+  const missing = tools.filter((tool) => !tool.path).map((tool) => tool.name);
+  return {
+    format,
+    available: missing.length === 0,
+    unsupported: false,
+    tools,
+    missing,
+    message: missing.length === 0
+      ? `Ready: render ${format} to ${spec.kind}`
+      : `Missing renderer tool(s): ${missing.join(', ')}`,
+  };
+}
+
+function toolPath(detection, name) {
+  return detection.tools.find((tool) => tool.name === name)?.path ?? name;
+}
+
+function producedFiles(outDir, prefix, ext) {
+  return fs.readdirSync(outDir)
+    .filter((file) => file.startsWith(prefix) && file.endsWith(ext))
+    .sort()
+    .map((file) => path.join(outDir, file));
+}
+
+// Each render function runs its real command and returns the produced image paths, or throws so
+// the caller can record a typed degradation. Commands are gated behind detection, so they only run
+// when their tools resolved.
+
+const RENDER_FNS = {
+  pdf(inputPath, outDir, detection) {
+    const result = spawnSync(toolPath(detection, 'pdftoppm'), ['-png', inputPath, path.join(outDir, 'page')], { encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(result.stderr || 'pdftoppm failed');
+    return producedFiles(outDir, 'page', '.png');
+  },
+  html(inputPath, outDir, detection) {
+    const out = path.join(outDir, 'page.png');
+    const result = spawnSync(toolPath(detection, 'chromium'), [
+      '--headless', '--no-sandbox', '--hide-scrollbars',
+      `--screenshot=${out}`, '--window-size=1280,1696',
+      pathToFileURL(path.resolve(inputPath)).href,
+    ], { encoding: 'utf8' });
+    if (result.status !== 0 || !fs.existsSync(out)) throw new Error(result.stderr || 'chromium screenshot failed');
+    return [out];
+  },
+  mermaid(inputPath, outDir, detection) {
+    const out = path.join(outDir, 'diagram.png');
+    const result = spawnSync(toolPath(detection, 'mmdc'), ['-i', inputPath, '-o', out], { encoding: 'utf8' });
+    if (result.status !== 0 || !fs.existsSync(out)) throw new Error(result.stderr || 'mmdc failed');
+    return [out];
+  },
+  d2(inputPath, outDir, detection) {
+    const out = path.join(outDir, 'diagram.svg');
+    const result = spawnSync(toolPath(detection, 'd2'), [inputPath, out], { encoding: 'utf8' });
+    if (result.status !== 0 || !fs.existsSync(out)) throw new Error(result.stderr || 'd2 failed');
+    return [out];
+  },
+  pptx(inputPath, outDir, detection) {
+    const conv = spawnSync(toolPath(detection, 'soffice'), ['--headless', '--convert-to', 'pdf', '--outdir', outDir, inputPath], { encoding: 'utf8' });
+    if (conv.status !== 0) throw new Error(conv.stderr || 'soffice convert failed');
+    const pdf = path.join(outDir, path.basename(inputPath).replace(/\.pptx$/i, '.pdf'));
+    if (!fs.existsSync(pdf)) throw new Error('soffice produced no pdf');
+    const result = spawnSync(toolPath(detection, 'pdftoppm'), ['-png', pdf, path.join(outDir, 'slide')], { encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(result.stderr || 'pdftoppm failed');
+    return producedFiles(outDir, 'slide', '.png');
+  },
+};
+
+function degraded(format, degradation, message, detection) {
+  return { ok: false, format, images: [], degradation, message, detection };
+}
+
+export function renderToImages({ format, inputPath, outDir, env = process.env } = {}) {
+  const detection = detectRenderer(format, env);
+  if (detection.unsupported) return degraded(format, 'unsupported-format', detection.message, detection);
+  if (!detection.available) return degraded(format, 'missing-dependency', detection.message, detection);
+  if (!inputPath || !fs.existsSync(inputPath)) {
+    return degraded(format, 'skipped-by-policy', `input not found: ${inputPath}`, detection);
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  try {
+    const images = RENDER_FNS[format](inputPath, outDir, detection);
+    if (!images.length) return degraded(format, 'unavailable-renderer', `renderer produced no images for ${format}`, detection);
+    return { ok: true, format, images, degradation: null, message: `Rendered ${images.length} image(s) for ${format}`, detection };
+  } catch (err) {
+    const reason = format === 'html' ? 'headless-limitation' : 'unavailable-renderer';
+    return degraded(format, reason, err.message, detection);
+  }
+}

package/lib/service-manager.mjs

@@ -163,6 +163,20 @@ async function isCopilotBridgeRunning(port) {
   return probeRuntimePort(port);
 }
 
+// Opt-in 1Password resolution (ADR-0049 Design A): each long-lived service launches
+// under `op run --env-file -- <cmd>` so op:// references resolve once at this stable
+// parent and every child inherits resolved provider keys. wrapWithOpRun returns the
+// command unchanged when CONSTRUCT_OP_ENV_FILE is unset, the file is missing, or `op`
+// is absent, so the un-opted path is byte-for-byte the prior behavior. The env that
+// carries CONSTRUCT_OP_ENV_FILE is options.env when a site sets one (doctor, oracle)
+// and process.env otherwise (cm, opencode, copilot bridge).
+
+function wrapServiceSpawn(command, args, homeDir, options = {}) {
+  const env = options.env || process.env;
+  const wrapped = wrapWithOpRun(command, args, { env, homeDir });
+  return { command: wrapped.command, args: wrapped.args };
+}
+
 function spawnDetached(command, args, homeDir, logFile, options = {}) {
   const logPath = path.join(runtimeStateDir(homeDir), logFile);
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
@@ -211,7 +225,9 @@ export function startDoctor({ rootDir, homeDir = os.homedir() } = {}) {
   if (existing) return { started: false, reused: true, pid: existing.pid };
   const indexPath = path.join(INSTALL_ROOT, 'lib', 'doctor', 'index.mjs');
   if (!fs.existsSync(indexPath)) return { started: false, reason: 'missing-binary' };
-  const { logPath } = spawnDetached('node', [indexPath], homeDir, 'doctor.log', { cwd: rootDir, env: { ...process.env } });
+  const doctorEnv = { ...process.env };
+  const launch = wrapServiceSpawn('node', [indexPath], homeDir, { env: doctorEnv });
+  const { logPath } = spawnDetached(launch.command, launch.args, homeDir, 'doctor.log', { cwd: rootDir, env: doctorEnv });
   return { started: true, logPath };
 }
 
@@ -223,13 +239,15 @@ export function startOracle({ rootDir, homeDir = os.homedir(), projectDir = root
   if (!fs.existsSync(entry)) return { started: false, reason: 'missing-binary' };
   const live = readHeartbeat(heartbeatPath(homeDir));
   if (live) return { started: false, reused: true, pid: live.pid };
-  const { logPath } = spawnDetached('node', [entry], homeDir, 'oracle-daemon.log', {
+  const oracleEnv = {
+    ...process.env,
+    CONSTRUCT_ORACLE_ROOT: rootDir,
+    CONSTRUCT_ORACLE_PROJECT: projectDir,
+  };
+  const launch = wrapServiceSpawn('node', [entry], homeDir, { env: oracleEnv });
+  const { logPath } = spawnDetached(launch.command, launch.args, homeDir, 'oracle-daemon.log', {
     cwd: projectDir,
-    env: {
-      ...process.env,
-      CONSTRUCT_ORACLE_ROOT: rootDir,
-      CONSTRUCT_ORACLE_PROJECT: projectDir,
-    },
+    env: oracleEnv,
   });
   return { started: true, logPath };
 }
@@ -372,7 +390,8 @@ export async function startServices({
     if (await memoryProbeFn(ports.memory)) {
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'reused' });
     } else {
-      spawnDetachedFn('cm', ['serve', '--port', String(ports.memory)], homeDir, 'cm.log');
+      const cm = wrapServiceSpawn('cm', ['serve', '--port', String(ports.memory)], homeDir, { env: liveEnv });
+      spawnDetachedFn(cm.command, cm.args, homeDir, 'cm.log');
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'started' });
     }
   } else if (wants('memory')) {
@@ -384,7 +403,8 @@ export async function startServices({
     if (await openCodeProbeFn(ports.bridge)) {
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'reused' });
     } else {
-      spawnDetachedFn('opencode', ['serve', '--port', String(ports.bridge)], homeDir, 'opencode.log');
+      const opencode = wrapServiceSpawn('opencode', ['serve', '--port', String(ports.bridge)], homeDir, { env: liveEnv });
+      spawnDetachedFn(opencode.command, opencode.args, homeDir, 'opencode.log');
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'started' });
     }
   }
@@ -399,7 +419,8 @@ export async function startServices({
       } else {
         const proxyPath = path.join(INSTALL_ROOT, 'lib', 'bridges', 'copilot-proxy.mjs');
         if (fs.existsSync(proxyPath)) {
-          spawnDetachedFn('node', [proxyPath, '--port', String(ports.copilotBridge)], homeDir, 'copilot-bridge.log');
+          const copilot = wrapServiceSpawn('node', [proxyPath, '--port', String(ports.copilotBridge)], homeDir, { env: liveEnv });
+          spawnDetachedFn(copilot.command, copilot.args, homeDir, 'copilot-bridge.log');
           results.push({ name: 'Copilot Bridge', url: `http://127.0.0.1:${ports.copilotBridge}`, status: 'started' });
         } else {
           results.push({ name: 'Copilot Bridge', status: 'unavailable', note: 'copilot-proxy binary missing in lib/bridges/' });

package/lib/templates/doc-presentation.mjs

@@ -53,6 +53,30 @@ export function lintDocPresentation(body, { type } = {}) {
     warnings.push('prd-family: consider FR-* or ## Requirements section');
   }
 
+  const placeholder = body.match(/\{\{[^}]+\}\}|\[object Object\]|\b(?:TODO|TBD|FIXME|XXX)\b/);
+  if (placeholder) {
+    errors.push(`unresolved placeholder: ${placeholder[0]}`);
+  }
+
+  const headings = [];
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^(#{1,6})\s+(.*)/);
+    if (match) headings.push({ index: i, level: match[1].length, text: match[2].trim() });
+  }
+  for (let h = 0; h < headings.length; h++) {
+    const current = headings[h];
+    const next = headings[h + 1];
+    const end = next ? next.index : lines.length;
+    let hasContent = false;
+    for (let i = current.index + 1; i < end; i++) {
+      if (lines[i].trim() !== '') { hasContent = true; break; }
+    }
+    if (!hasContent && (!next || next.level <= current.level)) {
+      errors.push(`empty section: ${current.text}`);
+      break;
+    }
+  }
+
   return { errors, warnings };
 }
 

package/lib/tracking-surfaces.mjs

@@ -99,6 +99,42 @@ export async function refreshContextMd({ rootDir, now = new Date() } = {}) {
   };
 }
 
+const CONTEXT_SCAFFOLD = `# context
+
+${SECTION_HEADERS.activeWork}
+
+_None in progress._
+
+${SECTION_HEADERS.recentDecisions}
+
+_No recent decisions captured._
+
+${SECTION_HEADERS.architectureNotes}
+
+_No new architecture notes._
+
+${SECTION_HEADERS.openQuestions}
+
+_None._
+`;
+
+/**
+ * Re-converge `.cx/context.md` to the canonical scaffold, then refresh the managed sections.
+ * Discards user-authored drift, so the operation is gated on explicit consent (decision
+ * construct-rr63.3.1): without consent the file is preserved untouched; with consent the file is
+ * rewritten to the scaffold and the managed sections are repopulated from current activity. The
+ * default preserves — re-converge never happens silently.
+ */
+export async function reconvergeContextMd({ rootDir, consent = false, now = new Date() } = {}) {
+  if (!rootDir) return { ok: false, reason: 'rootDir-required' };
+  const contextMdPath = join(rootDir, '.cx', 'context.md');
+  if (!existsSync(contextMdPath)) return { ok: false, reason: 'no-context-md' };
+  if (!consent) return { ok: false, reason: 'consent-required', preserved: true };
+  writeFileSync(contextMdPath, CONTEXT_SCAFFOLD, 'utf8');
+  const refreshed = await refreshContextMd({ rootDir, now });
+  return { ok: true, reconverged: true, refreshed: refreshed.ok };
+}
+
 // ---------------------------------------------------------------------------
 // plan.md sync and archive
 // ---------------------------------------------------------------------------