@geraldmaron/construct 1.0.16 → 1.0.17

package/lib/embedded-contract/redaction.mjs

@@ -0,0 +1,91 @@
+/**
+ * lib/embedded-contract/redaction.mjs — structural no-secrets guard for contract output.
+ *
+ * Every embedded-contract response passes through this module before
+ * serialization. `redact` masks values at secret-looking keys; `assertNoSecrets`
+ * is the load-bearing guard — it throws if any live credential value (drawn from
+ * the environment by key name) appears anywhere in the payload, so a contract
+ * surface can never leak a token even if a future field copies one in by
+ * mistake. The check is generic and decoupled from the provider registry: it
+ * derives the secret set from env keys at call time rather than a hardcoded list.
+ */
+
+const SECRET_KEY_RE = /(api[_-]?key|secret|token|password|passwd|credential|authorization|bearer|cookie|session[_-]?id|private[_-]?key|client[_-]?secret|access[_-]?key)/i;
+
+const REDACTED = '[redacted]';
+
+// Credential env values shorter than this are treated as non-secret (empty
+// flags, "1", port numbers) and excluded so the guard does not false-positive.
+
+const MIN_SECRET_LENGTH = 8;
+
+/**
+ * Deep-clone `value`, masking any value whose key name looks like a secret.
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+export function redact(value) {
+  if (Array.isArray(value)) return value.map((v) => redact(v));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (SECRET_KEY_RE.test(k) && (typeof v === 'string' || typeof v === 'number')) {
+        out[k] = REDACTED;
+      } else {
+        out[k] = redact(v);
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Collect non-trivial environment values whose key name looks like a secret.
+ *
+ * @param {Record<string,string>} [env]
+ * @returns {Set<string>}
+ */
+export function collectSecretValues(env = process.env) {
+  const out = new Set();
+  for (const [key, val] of Object.entries(env || {})) {
+    if (typeof val === 'string' && val.length >= MIN_SECRET_LENGTH && SECRET_KEY_RE.test(key)) {
+      out.add(val);
+    }
+  }
+  return out;
+}
+
+function walkStrings(value, visit, pathStr = '$') {
+  if (typeof value === 'string') {
+    visit(value, pathStr);
+  } else if (Array.isArray(value)) {
+    value.forEach((v, i) => walkStrings(v, visit, `${pathStr}[${i}]`));
+  } else if (value && typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) walkStrings(v, visit, `${pathStr}.${k}`);
+  }
+}
+
+/**
+ * Throw if any live credential value appears as a substring of any string in
+ * the payload. Returns the payload unchanged when clean.
+ *
+ * @param {*} value
+ * @param {{env?:Record<string,string>}} [opts]
+ * @returns {*}
+ */
+export function assertNoSecrets(value, { env = process.env } = {}) {
+  const secrets = collectSecretValues(env);
+  if (secrets.size === 0) return value;
+  const leaks = [];
+  walkStrings(value, (str, pathStr) => {
+    for (const secret of secrets) {
+      if (str.includes(secret)) leaks.push(pathStr);
+    }
+  });
+  if (leaks.length) {
+    throw new Error(`Secret value leaked into contract output at: ${[...new Set(leaks)].join(', ')}`);
+  }
+  return value;
+}

package/lib/embedded-contract/role-facts.mjs

@@ -0,0 +1,66 @@
+/**
+ * lib/embedded-contract/role-facts.mjs — shared role/contract enrichment.
+ *
+ * Both the triage/planning and workflow-invocation contracts need the same
+ * facts about a role chain: per-role rationale, the union of declared skills,
+ * and the evidence a role requires plus the outputs it must produce. Those facts
+ * come only from verifiable sources — the role catalog (registry) and the
+ * specialist contracts — so this module centralizes the lookups and keeps the
+ * two contracts consistent and free of invented requirements.
+ */
+
+import { listRoles } from '../roles/catalog.mjs';
+import { getIncomingContracts } from '../specialist-contracts.mjs';
+
+/**
+ * Map of role id → catalog descriptor for the current registry.
+ * @returns {Map<string, object>}
+ */
+export function roleMap() {
+  return new Map(listRoles().map((role) => [role.id, role]));
+}
+
+/**
+ * Per-role rationale for a chain, drawn from each role's catalog description.
+ *
+ * @param {string[]} chain
+ * @param {Map<string,object>} [map]
+ * @returns {Array<{role:string, reason:string}>}
+ */
+export function roleRationale(chain, map = roleMap()) {
+  return chain.map((id) => ({
+    role: `cx-${id}`,
+    reason: map.get(id)?.description || 'No role description available.',
+  }));
+}
+
+/**
+ * Union of declared skills across a role chain, de-duplicated.
+ *
+ * @param {string[]} chain
+ * @param {Map<string,object>} [map]
+ * @returns {string[]}
+ */
+export function skillsForChain(chain, map = roleMap()) {
+  return [...new Set(chain.flatMap((id) => map.get(id)?.skills || []))];
+}
+
+/**
+ * Evidence a role requires and the outputs it must produce, taken from the
+ * role's incoming specialist contract (input.mustContain + preconditions /
+ * output.mustContain). Returns empty arrays when no contract is declared.
+ *
+ * @param {string} roleId   Bare role id (no cx- prefix).
+ * @returns {{evidenceRequirements:string[], expectedOutputs:string[]}}
+ */
+export function contractFacts(roleId) {
+  const contracts = getIncomingContracts(`cx-${roleId}`) || [];
+  const evidence = new Set();
+  const outputs = new Set();
+  for (const c of contracts) {
+    for (const item of c.input?.mustContain || []) evidence.add(item);
+    for (const pre of c.preconditions || []) evidence.add(pre);
+    for (const item of c.output?.mustContain || []) outputs.add(item);
+  }
+  return { evidenceRequirements: [...evidence], expectedOutputs: [...outputs] };
+}

package/lib/embedded-contract/triage.mjs

@@ -0,0 +1,134 @@
+/**
+ * lib/embedded-contract/triage.mjs — embedded triage and planning contract.
+ *
+ * Classifies an artifact and returns a role-aware plan without enqueuing or
+ * executing anything. Wraps the deterministic classifier (lib/intake/classify)
+ * and enriches it from real sources only: the role catalog supplies role
+ * rationale and skills, the specialist contracts supply evidence requirements
+ * and expected outputs. Classification confidence (how sure the classifier is)
+ * is reported as a distinct, labeled field from any downstream generation
+ * confidence, which is produced only when a workflow actually runs.
+ *
+ * Pure and side-effect-free: no queue write, no disk artifact, no model call.
+ */
+
+import { classifyRdIntake } from '../intake/classify.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
+import { workflowTypeForIntake } from './workflow-defs.mjs';
+
+const CONFIDENCE_FLOOR = 0.6;
+
+function buildRiskFactors(triage) {
+  const factors = [];
+  if (triage.intakeType === 'unknown') factors.push('classification is unknown — no keywords matched');
+  if (typeof triage.confidence === 'number' && triage.confidence < CONFIDENCE_FLOOR) {
+    factors.push(`low classification confidence (${triage.confidence.toFixed(2)})`);
+  }
+  const ambiguous = (triage.rationale || '').includes('ambiguous');
+  if (ambiguous) factors.push('top two classifications are close (ambiguous)');
+  return factors;
+}
+
+/**
+ * Produce a role-aware plan for an artifact without enqueuing or executing it.
+ *
+ * @param {object} request
+ * @param {string} [request.input]          Artifact text to classify.
+ * @param {string} [request.sourcePath]     Filename/source hint for the classifier.
+ * @param {string} [request.artifactType]   Optional artifact-type hint (advisory).
+ * @param {string} [request.domain]
+ * @param {string} [request.desiredOutcome]
+ * @param {string[]} [request.constraints]
+ * @param {string[]} [request.availableRoles]  Restrict the plan to these role ids.
+ * @param {object} [request.profile]
+ * @param {object} [opts]   { env, cwd }
+ * @returns {object}
+ */
+export function recommendPlan(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
+  const { input = '', sourcePath = '', artifactType, availableRoles, profile = null, ingestion = null } = request;
+  const warnings = [];
+
+  // Surface extraction provenance and flag low-yield/truncated inputs so a
+  // sparse classification is attributable to thin source text, not silent loss.
+
+  if (ingestion) {
+    if (ingestion.error) warnings.push(`ingestion: ${ingestion.error.code} — ${ingestion.error.reason}`);
+    for (const drop of ingestion.droppedInfo || []) {
+      warnings.push(`ingestion: ${drop.kind || 'dropped-content'}${drop.recoverable ? ' (recoverable)' : ''}.`);
+    }
+    if (ingestion.truncated) warnings.push('ingestion: source text was truncated before classification.');
+    if (ingestion.note) warnings.push(`ingestion: ${ingestion.note}`);
+  }
+
+  const triage = classifyRdIntake({ sourcePath: sourcePath || (artifactType ? `${artifactType}.md` : ''), extractedText: input, profile });
+  const roles = roleMap();
+
+  let chain = [...(triage.recommendedChain || [])];
+  const primaryOwner = triage.primaryOwner;
+
+  if (Array.isArray(availableRoles) && availableRoles.length) {
+    const allowed = new Set(availableRoles);
+    const dropped = chain.filter((r) => !allowed.has(r));
+    if (dropped.length) warnings.push(`Roles not in availableRoles were dropped from the chain: ${dropped.join(', ')}.`);
+    chain = chain.filter((r) => allowed.has(r));
+    if (primaryOwner && !allowed.has(primaryOwner)) {
+      warnings.push(`Primary owner ${primaryOwner} is not in availableRoles; the plan cannot be executed as recommended.`);
+    }
+  }
+
+  const rationale = roleRationale(chain, roles);
+  const suggestedSkills = skillsForChain(chain, roles);
+
+  const { evidenceRequirements, expectedOutputs } = contractFacts(primaryOwner);
+  if (!evidenceRequirements.length) {
+    warnings.push(`No declared evidence contract for cx-${primaryOwner}; evidence requirements are unspecified.`);
+  }
+
+  const deploymentMode = getDeploymentMode(env, { cwd });
+  const requiresApproval = Boolean(triage.requiresApproval) || deploymentMode === 'enterprise';
+  const approvalRequirements = {
+    requiresApproval,
+    reason: triage.requiresApproval
+      ? 'The classified work type requires approval before durable changes.'
+      : (deploymentMode === 'enterprise' ? 'Enterprise deployment mode mandates approval for durable changes.' : 'No approval required before proposing changes.'),
+  };
+
+  const ownerAvailable = !primaryOwner || !Array.isArray(availableRoles) || !availableRoles.length || availableRoles.includes(primaryOwner);
+  const canExecute = triage.intakeType !== 'unknown'
+    && typeof triage.confidence === 'number' && triage.confidence >= CONFIDENCE_FLOOR
+    && chain.length > 0
+    && ownerAvailable;
+  const canExecuteReason = canExecute
+    ? 'Classification is confident and maps to a role chain that can be invoked.'
+    : 'Execution is not recommended: classification is unknown, low-confidence, or no usable role chain remains.';
+
+  const nextStepOptions = [
+    { action: 'enqueue', description: 'Add to the intake queue for processing (construct intake process).' },
+  ];
+  if (canExecute) nextStepOptions.push({ action: 'invoke-workflow', description: 'Invoke the recommended role chain as an embedded workflow.' });
+  if (!canExecute) nextStepOptions.push({ action: 'clarify', description: 'Request more detail; classification confidence is low or unknown.' });
+
+  return {
+    classification: { intakeType: triage.intakeType, rdStage: triage.rdStage },
+    ingestion,
+    confidenceKind: 'classification',
+    classificationConfidence: triage.confidence,
+    primaryOwner,
+    recommendedAction: triage.recommendedAction,
+    recommendedChain: chain,
+    suggestedWorkflowType: workflowTypeForIntake(triage.intakeType),
+    roleRationale: rationale,
+    suggestedSkills,
+    evidenceRequirements,
+    expectedOutputs,
+    approvalRequirements,
+    risks: { level: triage.risk || 'unknown', factors: buildRiskFactors(triage) },
+    nextStepOptions,
+    canExecute,
+    canExecuteReason,
+    rationale: triage.rationale,
+    candidates: triage.candidates || [],
+    warnings,
+  };
+}

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

@@ -0,0 +1,125 @@
+/**
+ * lib/embedded-contract/workflow-defs.mjs — embedded workflow type definitions.
+ *
+ * The single source of truth for the workflow types an embedding application can
+ * invoke. Each definition names a default role chain (real registry role ids), a
+ * model tier, a default approval mode, an optional output-schema artifact, and a
+ * one-line description. Skills are not hardcoded here — they are derived from the
+ * selected roles' declared skills (role-facts) so this file never names a skill
+ * id that does not exist. Capability discovery reads these definitions so the
+ * published workflow list cannot drift from what invocation actually supports.
+ */
+
+const DEFS = {
+  'evidence-ingest': {
+    tier: 'fast',
+    defaultApprovalMode: 'proposal-only',
+    chain: ['researcher', 'data-analyst'],
+    outputSchema: null,
+    description: 'Ingest and structure raw evidence (notes, documents, signals) into a normalized summary.',
+  },
+  'proposal-review': {
+    tier: 'standard',
+    defaultApprovalMode: 'requires-human-approval',
+    chain: ['reviewer', 'devil-advocate'],
+    outputSchema: 'review-report',
+    description: 'Review a proposal for correctness, risk, and hidden assumptions before acceptance.',
+  },
+  'prd-draft': {
+    tier: 'standard',
+    defaultApprovalMode: 'proposal-only',
+    chain: ['product-manager', 'architect'],
+    outputSchema: 'decision',
+    description: 'Draft a product requirements document from a problem statement and supporting evidence.',
+  },
+  'architecture-review': {
+    tier: 'reasoning',
+    defaultApprovalMode: 'requires-human-approval',
+    chain: ['architect', 'security', 'devil-advocate'],
+    outputSchema: 'review-report',
+    description: 'Review an architecture or design for trade-offs, failure modes, and security exposure.',
+  },
+  'risk-review': {
+    tier: 'reasoning',
+    defaultApprovalMode: 'requires-human-approval',
+    chain: ['devil-advocate', 'security', 'legal-compliance'],
+    outputSchema: 'review-report',
+    description: 'Stress-test a plan for risk: failure modes, security, and compliance exposure.',
+  },
+  'research-synthesis': {
+    tier: 'reasoning',
+    defaultApprovalMode: 'proposal-only',
+    chain: ['researcher', 'data-analyst', 'evaluator'],
+    outputSchema: null,
+    description: 'Synthesize multiple sources into a cited, evidence-graded research summary.',
+  },
+  'transcript-process': {
+    tier: 'fast',
+    defaultApprovalMode: 'proposal-only',
+    chain: ['researcher', 'data-analyst'],
+    outputSchema: null,
+    description: 'Process a meeting/call transcript into a summary, decisions, and action items.',
+  },
+  'data-structure': {
+    tier: 'standard',
+    defaultApprovalMode: 'proposal-only',
+    chain: ['data-analyst', 'data-engineer'],
+    outputSchema: null,
+    description: 'Parse, validate, and profile a raw dataset into a structured, described shape.',
+  },
+  'memo-draft': {
+    tier: 'fast',
+    defaultApprovalMode: 'proposal-only',
+    chain: ['docs-keeper', 'reviewer'],
+    outputSchema: null,
+    description: 'Draft a decision or status memo from a problem statement and context.',
+  },
+  'structure-notes': {
+    tier: 'fast',
+    defaultApprovalMode: 'proposal-only',
+    chain: ['orchestrator', 'researcher'],
+    outputSchema: null,
+    description: 'Structure an unclassified brain-dump or rough notes into a normalized summary with extracted intents.',
+  },
+};
+
+// Maps a classifier intakeType to the workflow type that would carry it out, so
+// the triage contract can suggest a directly-invokable workflow. Returns null
+// when no workflow covers the classification (the plan is not directly invokable).
+
+const INTAKE_TO_WORKFLOW = {
+  proposal: 'proposal-review',
+  prd: 'prd-draft',
+  'meta-prd': 'prd-draft',
+  architecture: 'architecture-review',
+  rfc: 'architecture-review',
+  risk: 'risk-review',
+  security: 'risk-review',
+  research: 'research-synthesis',
+  'research-note': 'research-synthesis',
+  signal: 'evidence-ingest',
+  'user-signal': 'evidence-ingest',
+  evidence: 'evidence-ingest',
+  memo: 'memo-draft',
+  transcript: 'transcript-process',
+  'raw-data': 'data-structure',
+  unknown: 'structure-notes',
+};
+
+export const WORKFLOW_TYPES = Object.keys(DEFS);
+
+export function getWorkflowDef(type) {
+  return DEFS[type] || null;
+}
+
+/**
+ * Public, secret-free description of every workflow type for capability discovery.
+ * @returns {Array<object>}
+ */
+export function listWorkflowDefs() {
+  return WORKFLOW_TYPES.map((type) => ({ type, ...DEFS[type] }));
+}
+
+export function workflowTypeForIntake(intakeType) {
+  return INTAKE_TO_WORKFLOW[intakeType] || null;
+}

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

@@ -0,0 +1,218 @@
+/**
+ * lib/embedded-contract/workflow-invoke.mjs — embedded workflow invocation contract.
+ *
+ * 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.
+ *
+ * Durable side effects are gated by approval mode (resolveWriteGate):
+ *   - proposal-only           → status 'proposed', zero writes
+ *   - requires-human-approval → status 'awaiting-approval', an approval request
+ *                               is recorded, zero durable writes
+ *   - allow-durable-write     → status 'recorded', the invocation is written to
+ *                               the observation store as durable provenance
+ * On team/enterprise deployments, durable writes are flagged as mandatorily
+ * audited. A traceId correlates the call with downstream provenance.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { addObservation } from '../observation-store.mjs';
+import { recordApprovalRequest } from '../roles/approval-surface.mjs';
+import { getWorkflowDef, WORKFLOW_TYPES } from './workflow-defs.mjs';
+import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
+import { resolveEmbeddedModel } from './model-resolve.mjs';
+import { resolveWriteGate, newTraceId, DEFAULT_APPROVAL_MODE } from './audit.mjs';
+
+const VALID_STRATEGIES = ['auto', 'explicit', 'constrained'];
+
+function selectRoles({ strategy, defChain, requestedRoles, map, warnings }) {
+  const filterKnown = (ids) => ids.filter((id) => {
+    if (map.has(id)) return true;
+    warnings.push(`Unknown role id ignored: ${id}.`);
+    return false;
+  });
+
+  if (strategy === 'explicit') {
+    if (!Array.isArray(requestedRoles) || requestedRoles.length === 0) {
+      warnings.push('roleStrategy=explicit requires requestedRoles; using the workflow default chain.');
+      return [...defChain];
+    }
+    return filterKnown(requestedRoles);
+  }
+  if (strategy === 'constrained') {
+    const allowed = new Set(requestedRoles || []);
+    const dropped = defChain.filter((id) => !allowed.has(id));
+    if (dropped.length) warnings.push(`Constrained: roles outside requestedRoles dropped from the default chain: ${dropped.join(', ')}.`);
+    return defChain.filter((id) => allowed.has(id));
+  }
+  return [...defChain];
+}
+
+function errorResult({ workflowId, traceId, approvalMode, code, message, warnings }) {
+  return {
+    workflowId,
+    status: 'error',
+    selectedRoles: [],
+    roleStrategy: null,
+    roleRationale: [],
+    skillsApplied: [],
+    modelResolution: null,
+    outputs: null,
+    recommendations: [],
+    evidence: { requirements: [], satisfied: [], traceId },
+    risks: { level: 'unknown', factors: [] },
+    requiresApproval: false,
+    approvalMode: approvalMode || DEFAULT_APPROVAL_MODE,
+    durableWritesPerformed: [],
+    traceId,
+    errors: [{ code, message }],
+    warnings,
+  };
+}
+
+/**
+ * Invoke an embedded workflow. Async because durable provenance and approval
+ * records are written through existing stores. Returns a result object carrying
+ * a `warnings` array (lifted into the envelope by the calling surface).
+ *
+ * @param {object} request
+ * @param {string} request.workflowType
+ * @param {string} [request.input]
+ * @param {object} [request.context]
+ * @param {string} [request.roleStrategy]    auto | explicit | constrained
+ * @param {string[]} [request.requestedRoles]
+ * @param {string} [request.approvalMode]     proposal-only | requires-human-approval | allow-durable-write
+ * @param {boolean} [request.trace=true]
+ * @param {string} [request.host]
+ * @param {string} [request.hostModel]
+ * @param {string} [request.hostProvider]
+ * @param {object} [opts]   { env, cwd }
+ * @returns {Promise<object>}
+ */
+export async function invokeWorkflow(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
+  const {
+    workflowType, context = {}, roleStrategy = 'auto', requestedRoles,
+    approvalMode, trace = true, host, hostModel, hostProvider, ingestion = null,
+  } = request;
+  const warnings = [];
+  if (ingestion) {
+    if (ingestion.error) warnings.push(`ingestion: ${ingestion.error.code} — ${ingestion.error.reason}`);
+    for (const drop of ingestion.droppedInfo || []) warnings.push(`ingestion: ${drop.kind || 'dropped-content'}${drop.recoverable ? ' (recoverable)' : ''}.`);
+    if (ingestion.truncated) warnings.push('ingestion: source text was truncated before invocation.');
+    if (ingestion.note) warnings.push(`ingestion: ${ingestion.note}`);
+  }
+  const traceId = trace ? newTraceId() : null;
+  const workflowId = `wf-${randomUUID()}`;
+
+  const def = getWorkflowDef(workflowType);
+  if (!def) {
+    return errorResult({ workflowId, traceId, approvalMode, code: 'UNKNOWN_WORKFLOW_TYPE', message: `Unknown workflowType "${workflowType}". Known: ${WORKFLOW_TYPES.join(', ')}.`, warnings });
+  }
+
+  const strategy = VALID_STRATEGIES.includes(roleStrategy) ? roleStrategy : 'auto';
+  if (strategy !== roleStrategy) warnings.push(`Unknown roleStrategy "${roleStrategy}"; defaulting to auto.`);
+
+  const map = roleMap();
+  const selectedRoles = selectRoles({ strategy, defChain: def.chain, requestedRoles, map, warnings });
+  if (selectedRoles.length === 0) {
+    return errorResult({ workflowId, traceId, approvalMode, code: 'NO_ROLES_SELECTED', message: 'Role selection produced an empty chain.', warnings });
+  }
+
+  const { warnings: modelWarnings = [], ...modelResolution } = resolveEmbeddedModel(
+    { workflowType, requestedTier: def.tier, host, hostModel, hostProvider },
+    { env },
+  );
+  for (const w of modelWarnings) warnings.push(`model-resolution: ${w}`);
+
+  const primaryOwner = selectedRoles[0];
+  const facts = contractFacts(primaryOwner);
+  const skillsApplied = skillsForChain(selectedRoles, map);
+  const rationale = roleRationale(selectedRoles, map);
+
+  // Evidence is satisfied only when a requirement key is actually present in the
+  // caller-supplied context; missing requirements are reported, never assumed.
+
+  const contextKeys = new Set(Object.keys(context || {}));
+  const satisfied = facts.evidenceRequirements.filter((req) => contextKeys.has(req));
+  const missingEvidence = facts.evidenceRequirements.filter((req) => !contextKeys.has(req));
+
+  const deploymentMode = getDeploymentMode(env, { cwd });
+  const mode = approvalMode || def.defaultApprovalMode;
+  const gate = resolveWriteGate({ approvalMode: mode, deploymentMode });
+
+  const outputs = {
+    schema: def.outputSchema,
+    expected: facts.expectedOutputs,
+    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(' → ')}.`];
+  if (missingEvidence.length) recommendations.push(`Supply missing evidence before execution: ${missingEvidence.join(', ')}.`);
+
+  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 };
+
+  const durableWritesPerformed = [];
+  const errors = [];
+  let status;
+
+  if (gate.requiresApproval) {
+    try {
+      await recordApprovalRequest({
+        personaId: primaryOwner,
+        action: `embedded-workflow:${workflowType}`,
+        target: workflowId,
+        reason: `Embedded workflow ${workflowType} awaiting human approval.`,
+        context: { workflowType, selectedRoles, traceId },
+      });
+    } catch (err) {
+      warnings.push(`Could not record approval request: ${err.message}`);
+    }
+    status = 'awaiting-approval';
+  } else if (gate.allowWrites) {
+    try {
+      const obs = await addObservation(cwd, {
+        role: primaryOwner,
+        category: 'decision',
+        summary: `Embedded workflow invoked: ${workflowType}`,
+        content: `roles=${selectedRoles.join(',')}; tier=${def.tier}; model=${modelResolution.selectedModel || 'unresolved'}; traceId=${traceId}`,
+        tags: ['embedded-contract', `workflow/${workflowType}`],
+        source: 'embedded-contract',
+      });
+      durableWritesPerformed.push({ kind: 'observation', id: obs?.id ?? null, store: '.cx/observations', audited: gate.mandatoryAudit });
+    } catch (err) {
+      errors.push({ code: 'DURABLE_WRITE_FAILED', message: err.message });
+    }
+    status = errors.length ? 'error' : 'recorded';
+  } else {
+    status = 'proposed';
+  }
+
+  return {
+    workflowId,
+    workflowType,
+    status,
+    ingestion,
+    selectedRoles,
+    roleStrategy: strategy,
+    roleRationale: rationale,
+    skillsApplied,
+    modelResolution,
+    outputs,
+    recommendations,
+    evidence: { requirements: facts.evidenceRequirements, satisfied, missing: missingEvidence, traceId },
+    risks,
+    requiresApproval: gate.requiresApproval,
+    approvalMode: gate.approvalMode,
+    durableWritesPerformed,
+    traceId,
+    errors,
+    warnings,
+  };
+}

package/lib/hooks/config-protection.mjs

@@ -6,8 +6,8 @@
  * prettier / tsconfig / biome / stylelint configs. Those rules are a contract
  * with the codebase; weakening them is almost always a bug fix in disguise.
  *
- * Meta-system files (hooks, registry, settings template, install.sh) are
- * audited but NOT blocked. Editing them is normal development work on
+ * Meta-system files (hooks, registry, settings template, install/setup
+ * entrypoints) are audited but NOT blocked. Editing them is normal work on
  * Construct itself. The previous block-with-CX_ALLOW_META_EDIT pattern was a
  * sticky env-var toggle: friction the first time, zero protection thereafter
  * because it stayed on. Layers that actually work for self-modification
@@ -31,22 +31,29 @@ const filePath = process.env.TOOL_INPUT_FILE_PATH || (() => {
 
 if (!filePath) process.exit(0);
 
+// Lint-RULE configs are hard contracts with the codebase: weakening a rule is
+// almost always a bug fix in disguise, so edits are blocked. tsconfig is the TS
+// COMPILER config — its options legitimately change with the toolchain (e.g. a
+// version-compat flag like ignoreDeprecations on a major TS bump), so it is
+// audited as a meta edit rather than blocked. Quality-relevant tsconfig changes
+// still surface in code review and the type-checked build.
 const PROTECTED = [
   /\.eslintrc(\.[a-z]+)?$/i,
   /eslint\.config(\.[a-z]+)?$/i,
   /\.prettierrc(\.[a-z]+)?$/i,
   /prettier\.config(\.[a-z]+)?$/i,
-  /tsconfig(\.[^/]+)?\.json$/i,
   /biome\.json$/i,
   /\.stylelintrc(\.[a-z]+)?$/i,
   /stylelint\.config(\.[a-z]+)?$/i,
 ];
 
 const META_FILES = [
-  /(?:^|\/)agents\/registry\.json$/,
-  /(?:^|\/)install\.sh$/,
+  /(?:^|\/)specialists\/registry\.json$/,
+  /(?:^|\/)lib\/setup\.mjs$/,
+  /(?:^|\/)bin\/construct-postinstall\.mjs$/,
   /(?:^|\/)claude\/settings\.template\.json$/,
   /(?:^|\/)lib\/hooks\/[^/]+\.mjs$/,
+  /(?:^|\/)tsconfig(\.[^/]+)?\.json$/i,
 ];
 
 async function emitEvent(type, category, summary) {