@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/embedded-contract/workflow-invoke.mjs

@@ -4,9 +4,24 @@
  * Invokes a named Construct workflow non-interactively and returns a provenanced
  * execution plan: the selected roles (auto/explicit/constrained), each role's
  * rationale, the skills they apply, the resolved model, the evidence the chain
- * requires, and the output contract it will produce. Construct supplies the
- * orchestration plan and provenance; the host agent runtime performs the
- * specialist reasoning — so this contract never fabricates specialist output.
+ * requires, the bound persona reasoning framework (ADR-0062), and the output
+ * contract to be produced. Construct supplies the orchestration plan and
+ * provenance; the host agent runtime performs the specialist reasoning, so
+ * the contract never fabricates specialist output.
+ *
+ * Framework wiring (LMCP-F8, ADR-0062 §3): the primary role's framework is
+ * resolved through the same pack registry and tier precedence (E1/ADR-0055)
+ * that resolves persona prompts (lib/orchestration/worker.mjs), by matching a
+ * pack-declared framework's `appliesToRole` against the role. The resolved
+ * framework's ordered `steps` become prompt fragments in the plan, and its
+ * `emits` tokens (in step order) are the output contract's required fields —
+ * the host runtime that performs the reasoning must return one labeled output
+ * per token, in order. A role with no matching framework never falls back to
+ * silent generic reasoning: the plan carries `framework: { available: false,
+ * degraded: 'framework-missing', role }`, a visible flag a caller can branch
+ * on. Traces record `{frameworkId, version, source}` alongside the existing
+ * F1 provenance fields so a downstream audit can tell which reasoning
+ * procedure (if any) governed the run.
  *
  * Durable side effects are gated by approval mode (resolveWriteGate):
  *   - proposal-only           → status 'proposed', zero writes
@@ -19,10 +34,15 @@
  */
 
 import { randomUUID } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { addObservation } from '../observation-store.mjs';
 import { recordApprovalRequest } from '../roles/approval-surface.mjs';
+import { loadAllPacks } from '../packs/loader.mjs';
+import { resolveFramework } from '../frameworks/loader.mjs';
+import { parseFrameworkFile } from '../frameworks/schema.mjs';
 import { getWorkflowDef, WORKFLOW_TYPES } from './workflow-defs.mjs';
 import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
 import { resolveEmbeddedModel } from './model-resolve.mjs';
@@ -31,6 +51,89 @@ import { resolveWriteGate, newTraceId, DEFAULT_APPROVAL_MODE } from './audit.mjs
 
 const VALID_STRATEGIES = ['auto', 'explicit', 'constrained'];
 
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(HERE, '..', '..');
+
+// Mirrors lib/orchestration/worker.mjs sortByTierPrecedence: a project pack's
+// framework for a role must win over a builtin pack's framework for the same
+// role, not just over another version of the same pack id (ADR-0055).
+
+const PACK_TIER_RANK = { project: 0, user: 1, builtin: 2, unknown: 3 };
+
+function sortByTierPrecedence(packs) {
+  return [...packs].sort((a, b) => (PACK_TIER_RANK[a._tier] ?? 3) - (PACK_TIER_RANK[b._tier] ?? 3));
+}
+
+/**
+ * Find the frameworkId a pack registry binds to a role, honoring tier
+ * precedence. A framework equips a role via its own frontmatter
+ * `appliesToRole` (ADR-0062 §2) — there is no separate specialist→framework
+ * map to consult, so packs are walked in precedence order and the first
+ * framework file whose parsed `appliesToRole` matches wins.
+ *
+ * @param {string} roleId   bare role id, e.g. 'product-manager'
+ * @param {object[]} packs  tier-precedence ordered pack list
+ * @param {string} packageRoot
+ * @returns {string|null}
+ */
+function frameworkIdForRole(roleId, packs, packageRoot) {
+  for (const pack of packs) {
+    const frameworks = pack?.frameworks || {};
+    const root = pack?._packDir || packageRoot;
+    for (const [frameworkId, relPath] of Object.entries(frameworks)) {
+      if (typeof relPath !== 'string' || !relPath) continue;
+      const parsed = parseFrameworkFile(join(root, relPath));
+      if (parsed.valid && parsed.frontmatter?.appliesToRole === roleId) return frameworkId;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the persona reasoning framework bound to a role through the pack
+ * registry (E1 precedence), or a visible degradation flag when no pack
+ * declares one for this role — never a silent fallback to generic reasoning
+ * (ADR-0062 §3).
+ *
+ * @param {string} roleId
+ * @param {object} opts
+ * @param {object} opts.env
+ * @param {string} opts.cwd
+ * @returns {{available:true, frameworkId:string, version:*, source:string, steps:object[], requiredOutputFields:string[]} | {available:false, degraded:'framework-missing', role:string}}
+ */
+function resolveRoleFramework(roleId, { env, cwd }) {
+  const deploymentMode = getDeploymentMode(env, { cwd });
+  const { packs } = loadAllPacks({ deploymentMode, env, rootDir: cwd, packageRoot: PACKAGE_ROOT });
+  const ordered = sortByTierPrecedence(packs);
+
+  const frameworkId = frameworkIdForRole(roleId, ordered, PACKAGE_ROOT);
+  if (!frameworkId) {
+    return { available: false, degraded: 'framework-missing', role: roleId };
+  }
+
+  const resolved = resolveFramework(frameworkId, { packs: ordered, packageRoot: PACKAGE_ROOT });
+  if (!resolved.found) {
+    return { available: false, degraded: 'framework-missing', role: roleId };
+  }
+
+  const steps = (resolved.frontmatter.steps || []).map((step) => ({
+    id: step.id,
+    move: step.move,
+    question: step.question,
+    emits: step.emits,
+    cites: step.cites,
+  }));
+
+  return {
+    available: true,
+    frameworkId: resolved.frontmatter.id,
+    version: resolved.frontmatter.version,
+    source: resolved.packId,
+    steps,
+    requiredOutputFields: steps.map((s) => s.emits),
+  };
+}
+
 function selectRoles({ strategy, defChain, requestedRoles, map, warnings }) {
   const filterKnown = (ids) => ids.filter((id) => {
     if (map.has(id)) return true;
@@ -63,6 +166,7 @@ function errorResult({ workflowId, traceId, approvalMode, code, message, warning
     roleRationale: [],
     skillsApplied: [],
     modelResolution: null,
+    framework: null,
     outputs: null,
     recommendations: [],
     evidence: { requirements: [], satisfied: [], traceId },
@@ -71,6 +175,7 @@ function errorResult({ workflowId, traceId, approvalMode, code, message, warning
     approvalMode: approvalMode || DEFAULT_APPROVAL_MODE,
     durableWritesPerformed: [],
     traceId,
+    trace: { role: null, frameworkId: null, frameworkVersion: null, frameworkSource: null, degraded: null },
     errors: [{ code, message }],
     warnings,
   };
@@ -154,6 +259,15 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   const skillsApplied = skillsForChain(selectedRoles, map);
   const rationale = roleRationale(selectedRoles, map);
 
+  // The bound framework equips the plan's primary role only — the role the
+  // output contract and evidence requirements are already scoped to
+  // (contractFacts(primaryOwner) above) — not every role in the chain.
+
+  const framework = resolveRoleFramework(primaryOwner, { env, cwd });
+  if (!framework.available) {
+    warnings.push(`framework: no reasoning framework bound for role '${primaryOwner}'; proceeding without a reasoning scaffold (degraded: framework-missing).`);
+  }
+
   // Evidence is satisfied only when a requirement key is actually present in the
   // caller-supplied context; missing requirements are reported, never assumed.
 
@@ -165,9 +279,14 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   const mode = approvalMode || def.defaultApprovalMode;
   const gate = resolveWriteGate({ approvalMode: mode, deploymentMode });
 
+  // requiredOutputFields carries the framework's `emits` tokens IN STEP ORDER
+  // (ADR-0062 §3): the host runtime must return one labeled output per token,
+  // in that order, so the reasoning procedure is checkable, not just prose.
+
   const outputs = {
     schema: def.outputSchema,
     expected: facts.expectedOutputs,
+    requiredOutputFields: framework.available ? framework.requiredOutputFields : [],
     note: 'Construct returns the orchestration plan and output contract; specialist reasoning is performed by the host agent runtime.',
   };
   const recommendations = [`Run roles in order: ${selectedRoles.map((r) => `cx-${r}`).join(' → ')}.`];
@@ -176,7 +295,11 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   const riskFactors = [];
   if (missingEvidence.length) riskFactors.push(`missing required evidence: ${missingEvidence.join(', ')}`);
   if (modelResolution.error) riskFactors.push(`model could not be resolved: ${modelResolution.error.reason}`);
-  const risks = { level: missingEvidence.length || modelResolution.error ? 'medium' : 'low', factors: riskFactors };
+  if (!framework.available) riskFactors.push(`no reasoning framework bound for role '${primaryOwner}' (degraded: framework-missing)`);
+  const risks = {
+    level: missingEvidence.length || modelResolution.error || !framework.available ? 'medium' : 'low',
+    factors: riskFactors,
+  };
 
   const durableWritesPerformed = [];
   const errors = [];
@@ -214,6 +337,21 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
     status = 'proposed';
   }
 
+  // Trace provenance (LMCP-F1 alignment): a downstream audit reads
+  // {frameworkId, frameworkVersion, frameworkSource} off the trace to know
+  // which reasoning procedure (if any) governed this run, the same way F1
+  // already records {specialistId, packId, promptVersion} for the persona
+  // that ran. traceId itself is already carried (and correlated) at the top
+  // level, so it is not duplicated here.
+
+  const traceProvenance = {
+    role: primaryOwner,
+    frameworkId: framework.available ? framework.frameworkId : null,
+    frameworkVersion: framework.available ? framework.version : null,
+    frameworkSource: framework.available ? framework.source : null,
+    degraded: framework.available ? null : framework.degraded,
+  };
+
   return {
     workflowId,
     workflowType,
@@ -225,6 +363,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
     skillsApplied,
     modelResolution,
     execution,
+    framework,
     outputs,
     recommendations,
     evidence: { requirements: facts.evidenceRequirements, satisfied, missing: missingEvidence, traceId },
@@ -233,6 +372,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
     approvalMode: gate.approvalMode,
     durableWritesPerformed,
     traceId,
+    trace: traceProvenance,
     errors,
     warnings,
   };

package/lib/embedded-contract/workflows/architecture-review.manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "architecture-review",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["architect", "security", "reviewer"],
+  "defaultApprovalMode": "requires-human-approval",
+  "outputSchema": { "artifact": "review-report" },
+  "durableStateModel": "none",
+  "tier": "reasoning",
+  "description": "Review an architecture or design for trade-offs, failure modes, and security exposure.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/data-structure.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "data-structure",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["data-analyst", "engineer"],
+  "defaultApprovalMode": "proposal-only",
+  "durableStateModel": "none",
+  "tier": "standard",
+  "description": "Parse, validate, and profile a raw dataset into a structured, described shape.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/evidence-ingest.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "evidence-ingest",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["researcher", "data-analyst"],
+  "defaultApprovalMode": "proposal-only",
+  "durableStateModel": "none",
+  "tier": "fast",
+  "description": "Ingest and structure raw evidence (notes, documents, signals) into a normalized summary.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/memo-draft.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "memo-draft",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["operations", "reviewer"],
+  "defaultApprovalMode": "proposal-only",
+  "durableStateModel": "none",
+  "tier": "fast",
+  "description": "Draft a decision or status memo from a problem statement and context.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/operations-triage.manifest.json

@@ -0,0 +1,18 @@
+{
+  "id": "operations-triage",
+  "version": "1.0.0",
+  "type": "embed",
+  "defaultApprovalMode": "proposal-only",
+  "compatVersion": 1,
+  "owner": "construct-core",
+  "description": "Triage preset: the operations specialist reviews new/changed Jira tickets, detects duplicates and under-specified issues, then proposes triage actions (duplicate-link, needs-info comment) held for approval. Never auto-executes writes.",
+  "embed": {
+    "specialist": "cx-operations",
+    "providerBindings": ["atlassian-jira", "atlassian-confluence", "directory"],
+    "framework": "cx-ops-dependency-sequencing",
+    "outputContract": "operations-triage",
+    "proposalAuthority": "propose-only",
+    "runtime": "auto",
+    "cadence": { "every": "PT2H" }
+  }
+}

package/lib/embedded-contract/workflows/operations.manifest.json

@@ -0,0 +1,18 @@
+{
+  "id": "operations",
+  "version": "1.0.0",
+  "type": "embed",
+  "defaultApprovalMode": "proposal-only",
+  "compatVersion": 1,
+  "owner": "construct-core",
+  "description": "TPM preset: the operations specialist reads Jira, product docs (Confluence), and Slack, then produces a recurring briefing — work missing versus the PRDs, timeline-risk findings with evidence, and proposed Jira tickets held for approval. Never auto-creates issues.",
+  "embed": {
+    "specialist": "cx-operations",
+    "providerBindings": ["atlassian-jira", "atlassian-confluence", "slack"],
+    "framework": "cx-ops-dependency-sequencing",
+    "outputContract": "operations-tpm-briefing",
+    "proposalAuthority": "propose-only",
+    "runtime": "auto",
+    "cadence": { "every": "PT4H" }
+  }
+}

package/lib/embedded-contract/workflows/pm-feedback.manifest.json

@@ -0,0 +1,18 @@
+{
+  "id": "pm-feedback",
+  "version": "1.0.0",
+  "type": "embed",
+  "defaultApprovalMode": "proposal-only",
+  "compatVersion": 1,
+  "owner": "construct-core",
+  "description": "PM feedback preset: the product-manager specialist reads customer feedback and PRDs (Confluence), clusters feedback by theme, scores each theme with the user-value rubric, cross-references PRD requirements, and emits a requirements-candidates artifact. Artifact-only — proposes no provider write.",
+  "embed": {
+    "specialist": "cx-product-manager",
+    "providerBindings": ["feedback", "atlassian-confluence"],
+    "framework": "cx-pm-value-tradeoff",
+    "outputContract": "pm-requirements-candidates",
+    "proposalAuthority": "propose-only",
+    "runtime": "auto",
+    "cadence": { "every": "PT24H" }
+  }
+}

package/lib/embedded-contract/workflows/prd-draft.manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "prd-draft",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["product-manager", "architect"],
+  "defaultApprovalMode": "proposal-only",
+  "outputSchema": { "artifact": "decision" },
+  "durableStateModel": "none",
+  "tier": "standard",
+  "description": "Draft a product requirements document from a problem statement and supporting evidence.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/proposal-review.manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "proposal-review",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["reviewer"],
+  "defaultApprovalMode": "requires-human-approval",
+  "outputSchema": { "artifact": "review-report" },
+  "durableStateModel": "none",
+  "tier": "standard",
+  "description": "Review a proposal for correctness, risk, and hidden assumptions before acceptance.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/research-synthesis.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "research-synthesis",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["researcher", "data-analyst", "reviewer"],
+  "defaultApprovalMode": "proposal-only",
+  "durableStateModel": "none",
+  "tier": "reasoning",
+  "description": "Synthesize multiple sources into a cited, evidence-graded research summary.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/risk-review.manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "risk-review",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["reviewer", "security"],
+  "defaultApprovalMode": "requires-human-approval",
+  "outputSchema": { "artifact": "review-report" },
+  "durableStateModel": "none",
+  "tier": "reasoning",
+  "description": "Stress-test a plan for risk: failure modes, security, and compliance exposure.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/structure-notes.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "structure-notes",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["orchestrator", "researcher"],
+  "defaultApprovalMode": "proposal-only",
+  "durableStateModel": "none",
+  "tier": "fast",
+  "description": "Structure an unclassified brain-dump or rough notes into a normalized summary with extracted intents.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/transcript-process.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "transcript-process",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo", "team"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["researcher", "data-analyst"],
+  "defaultApprovalMode": "proposal-only",
+  "durableStateModel": "none",
+  "tier": "fast",
+  "description": "Process a meeting/call transcript into a summary, decisions, and action items.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/embedded-contract/workflows/triage.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "triage",
+  "version": "1.0.0",
+  "type": "linear",
+  "modes": ["solo"],
+  "surfaces": ["mcp", "cli"],
+  "roleChain": ["orchestrator", "researcher"],
+  "defaultApprovalMode": "proposal-only",
+  "durableStateModel": "none",
+  "tier": "fast",
+  "description": "Classify and route unstructured input to the appropriate workflow.",
+  "owner": "construct-core",
+  "compatVersion": 1
+}

package/lib/env-config.mjs

@@ -8,6 +8,13 @@
  * order — project .env over config.env — so a key resolves the same way on both
  * paths. Backs setup, model-router, and the MCP server when they resolve API keys
  * and model overrides without leaking secrets.
+ *
+ * The `rootDir` param is the project .env tier's location and must be the
+ * user's project root, not the toolkit install checkout — bin/construct and
+ * lib/mcp/server.mjs both resolve it via lib/roots.mjs's resolveProjectRoot()
+ * (walk up from cwd to a `.cx/` or `package.json` marker) before calling
+ * loadConstructEnv/prepareConstructEnv, so a `.env` in the user's repo loads
+ * on both surfaces.
  */
 import fs from 'node:fs';
 import os from 'node:os';
@@ -16,10 +23,15 @@ import { configDir } from './config/xdg.mjs';
 import { API_KEY_CREDENTIALS } from './providers/credential-catalog.mjs';
 import { extractOpRef } from './providers/secret-resolver.mjs';
 
-export function parseEnvFile(filePath) {
-  if (!filePath || !fs.existsSync(filePath)) return {};
+// The single dotenv-line parser: strips a leading and/or trailing quote
+// independently (an unpaired quote — `KEY="abc` — still loses its one quote
+// character rather than being left untouched). lib/providers/secret-resolver.mjs's
+// file tier calls this same function so a value never differs between the two
+// dotenv readers.
+
+export function parseEnvContent(content) {
   const env = {};
-  for (const rawLine of fs.readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+  for (const rawLine of String(content ?? '').split(/\r?\n/)) {
     const line = rawLine.trim();
     if (!line || line.startsWith('#')) continue;
     const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
@@ -30,6 +42,11 @@ export function parseEnvFile(filePath) {
   return env;
 }
 
+export function parseEnvFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return {};
+  return parseEnvContent(fs.readFileSync(filePath, 'utf8'));
+}
+
 export function getUserConfigDir(homeDir = os.homedir()) {
   return configDir(homeDir);
 }
@@ -52,7 +69,15 @@ export function writeEnvValues(filePath, values = {}) {
     .filter(([, value]) => value !== undefined && value !== null && value !== '')
     .map(([key, value]) => `${key}=${value}`)
     .join('\n');
-  fs.writeFileSync(filePath, `${content}\n`, 'utf8');
+  fs.writeFileSync(filePath, `${content}\n`, { encoding: 'utf8', mode: 0o600 });
+
+  // config.env can hold plaintext credentials. writeFileSync keeps an existing inode's
+  // mode, so the mode option does not tighten a file an earlier write (or a caller that
+  // skipped its own chmod) left 0644; re-apply 0600 on every write so the credential
+  // file is never group/world readable.
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(filePath, 0o600); } catch { /* exotic filesystem */ }
+  }
 }
 
 function cleanEnvValue(value) {
@@ -103,7 +128,7 @@ function isOpReference(value) {
   return Boolean(extractOpRef(value));
 }
 
-function preferInjectedCredential(envValue, fileValue) {
+export function preferInjectedCredential(envValue, fileValue) {
   return Boolean(
     envValue
     && !isOpReference(envValue)
@@ -111,7 +136,35 @@ function preferInjectedCredential(envValue, fileValue) {
   );
 }
 
-export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = process.env, warn = true } = {}) {
+// The canonical resolver for a non-negative numeric env setting (milliseconds,
+// byte caps, counts, loop bounds). An explicit 0 is a valid, meaningful value
+// (disable / no-cap), so only null/undefined/blank or a non-finite/negative parse
+// falls back — `Number(env) || fallback` would silently rewrite an explicit 0.
+// Mirrors the "0 disables" convention documented at lib/mcp/server.mjs.
+
+export function resolveNonNegativeSetting(env, key, fallback) {
+  const val = env?.[key];
+  if (val === undefined || val === null) return fallback;
+  if (typeof val === 'string' && val.trim() === '') return fallback;
+  const raw = Number(val);
+  return Number.isFinite(raw) && raw >= 0 ? raw : fallback;
+}
+
+// The env-vs-file shadow winner differs by surface: the MCP server and other
+// callers use loadConstructEnv's file-wins return, but bin/construct copies only
+// the keys missing from process.env, so on a conflict the shell value wins there.
+// The caller declares which value actually wins so the warning names the truth
+// rather than asserting file-wins on every surface.
+
+export function shadowWarningMessage(key, shadowWinner = 'file') {
+  const winnerClause = shadowWinner === 'shell'
+    ? 'The shell value will be used'
+    : 'The config file will be used';
+  return `[construct] WARNING: process.env.${key} differs from the config file value. `
+    + `${winnerClause}. To silence: unset the shell variable or update the config file to match.`;
+}
+
+export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = process.env, warn = true, shadowWinner = 'file' } = {}) {
   const rootEnv = rootDir ? parseEnvFile(path.join(rootDir, '.env')) : {};
   const userEnv = parseEnvFile(getUserEnvPath(homeDir));
 
@@ -145,11 +198,7 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
       if (!env[key]) continue;
       if (key in fileEnv && fileEnv[key] !== env[key]) {
         if (preferInjectedCredential(env[key], fileEnv[key])) continue;
-        process.stderr.write(
-          `[construct] WARNING: process.env.${key} differs from the config file value. ` +
-          `The config file will be used. To silence: unset the shell variable or ` +
-          `update the config file to match.\n`,
-        );
+        process.stderr.write(`${shadowWarningMessage(key, shadowWinner)}\n`);
       }
     }
   }

package/lib/export-validate.mjs

@@ -86,21 +86,53 @@ export function contentRoundtrip({ exportPath, format, sourceMarkdown, env = pro
 }
 
 // Local image and link targets must resolve on disk; remote URLs, anchors, and mailto are out of
-// scope for an on-disk integrity check.
+// scope for an on-disk integrity check. Three reference forms in source are covered: ![]() syntax,
+// raw inline <img src> HTML, and reference-style definitions ([id]: ./path). The produced HTML
+// file's own <img src> references are also scanned, catching assets referenced only in the export.
 
-export function referenceIntegrity(sourceMarkdown, baseDir) {
+export function referenceIntegrity(sourceMarkdown, baseDir, exportPath = null) {
   const body = sourceMarkdown.replace(/```[\s\S]*?```/g, '');
   const missingImages = [];
   const brokenLinks = [];
+
+  // Standard Markdown image syntax: ![alt](path)
   for (const match of body.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
     const ref = match[1].split(/\s+/)[0];
     if (/^https?:|^data:/.test(ref)) continue;
     if (!fs.existsSync(path.resolve(baseDir, ref))) missingImages.push(ref);
   }
+
+  // Raw inline HTML <img src> in source markdown
+  for (const match of body.matchAll(/<img[^>]+src\s*=\s*["']([^"']+)["']/gi)) {
+    const ref = match[1];
+    if (/^https?:|^data:|^#/.test(ref)) continue;
+    if (!fs.existsSync(path.resolve(baseDir, ref))) missingImages.push(ref);
+  }
+
+  // Reference-style image/link definitions: [id]: ./path
+  for (const match of body.matchAll(/^\[[^\]]+\]:\s+(\S+)/gm)) {
+    const ref = match[1];
+    if (/^https?:|^#|^mailto:/.test(ref)) continue;
+    if (!fs.existsSync(path.resolve(baseDir, ref))) missingImages.push(ref);
+  }
+
+  // Standard Markdown link syntax: [text](path) (non-image)
   for (const match of body.matchAll(/(?<!!)\[[^\]]*\]\(([^)]+)\)/g)) {
     const ref = match[1].split(/\s+/)[0];
     if (/^https?:|^#|^mailto:/.test(ref)) continue;
     if (!fs.existsSync(path.resolve(baseDir, ref))) brokenLinks.push(ref);
   }
+
+  // Produced HTML file: scan internal <img src> references that may not appear in source markdown
+  if (exportPath && exportPath.endsWith('.html') && fs.existsSync(exportPath)) {
+    let html = '';
+    try { html = fs.readFileSync(exportPath, 'utf8'); } catch { /* skip */ }
+    for (const match of html.matchAll(/<img[^>]+src\s*=\s*["']([^"']+)["']/gi)) {
+      const ref = match[1];
+      if (/^https?:|^data:|^#/.test(ref)) continue;
+      if (!fs.existsSync(path.resolve(baseDir, ref))) missingImages.push(ref);
+    }
+  }
+
   return { ok: missingImages.length === 0 && brokenLinks.length === 0, missingImages, brokenLinks };
 }