@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/contracts/validate.mjs

@@ -9,10 +9,28 @@
  *   3. Runtime handoff: a single artifact validated against the schema referenced
  *      by a producer→consumer contract, with mustContain post-conditions.
  *
+ * A contract's `postconditions` array is classified per-entry via
+ * `postconditionType` ('executable' | 'advisory' — see construct-rf26.12).
+ * Four real enforcement mechanisms back the executable ones:
+ *   - `contract.output.mustContain` / `mustContainOneOf` / `mustMatchEnum` —
+ *     declarative field-presence and enum checks against the handoff artifact.
+ *   - `contract.output.schema` — recursive required+enum validation against
+ *     the referenced lib/contract-schemas/*.json (not just top-level required).
+ *   - `contract.postconditions[].check` — structured checks against the
+ *     on-disk artifact (see validateArtifactPostconditions), for markdown
+ *     deliverables (sections, citations, tables).
+ *   - lib/specialists/postconditions.mjs POSTCONDITIONS table — binary,
+ *     producer-keyed packet invariants, referenced from a postcondition via
+ *     `enforcedVia: 'binary-postcondition'`.
+ * Advisory entries are prose that no mechanism above can decide (subjective
+ * quality, cross-document consistency, sequencing/process guarantees) —
+ * documented, not silently "enforced."
+ *
  * Surfaces:
  *   - scripts/sync-specialists.mjs invokes validateContractsFile at sync time.
  *   - bin/construct lint:contracts invokes the same path in CI.
  *   - workflowContractValidate (runtime) invokes validateHandoff per handoff.
+ *   - lib/contracts/coverage.mjs reports executable-vs-advisory coverage.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -238,11 +256,12 @@ export function validateHandoff(opts = {}) {
     }
   }
 
-  // A handoff carries a producer's output, which is the consumer's input. The
-  // input contract is what the consumer expects to receive; check mustContain
-  // against that first. Output.schema validation only applies when the artifact
-  // declares the matching `type` (e.g. the consumer is forwarding its own
-  // produced artifact downstream).
+  // A handoff carries a producer's output, which is the consumer's input: the
+  // same physical packet, checked from both ends. `input.mustContain` is what
+  // the consumer expects to receive; `output.mustContain` / `mustContainOneOf` /
+  // `mustMatchEnum` is what the producer is contractually required to have put
+  // there. Both apply to the same `artifact` value — there is no separate
+  // "producer's copy" to check.
   const inputMustContain = contract.input?.mustContain || [];
   for (const field of inputMustContain) {
     if (!hasField(artifact, field)) {
@@ -250,6 +269,36 @@ export function validateHandoff(opts = {}) {
     }
   }
 
+  const outputSpec = contract.output || {};
+  for (const field of outputSpec.mustContain || []) {
+    if (!isPresentValue(artifact?.[field])) {
+      errors.push(`artifact missing required output field: ${field}`);
+    }
+  }
+  for (const group of outputSpec.mustContainOneOf || []) {
+    if (!Array.isArray(group) || group.length === 0) continue;
+    if (!group.some((field) => isPresentValue(artifact?.[field]))) {
+      errors.push(`artifact missing one of required output fields: ${group.join('|')}`);
+    }
+  }
+  if (outputSpec.mustMatchEnum && typeof outputSpec.mustMatchEnum === 'object') {
+    for (const [field, allowed] of Object.entries(outputSpec.mustMatchEnum)) {
+      if (!Array.isArray(allowed) || allowed.length === 0) continue;
+      const value = artifact?.[field];
+      if (value === undefined || value === null) continue;
+      if (!allowed.includes(value)) {
+        errors.push(`artifact field '${field}' value '${value}' not in allowed set: ${allowed.join(', ')}`);
+      }
+    }
+  }
+
+  // Output.schema validation only applies when the artifact declares the
+  // matching `type` — several contracts share one schema file (e.g.
+  // implementation.json), so `type` disambiguates which schema this
+  // particular packet claims to satisfy. Once matched, the check recurses
+  // into nested `required` and `enum` constraints (e.g. a `verificationChecklist`
+  // sub-object's required booleans, or a `findings[].severity` enum) rather
+  // than stopping at top-level required-field presence.
   const outputType = contract.output?.type;
   const schemaRef = contract.output?.schema;
   if (schemaRef && outputType && artifact && artifact.type === outputType) {
@@ -258,9 +307,7 @@ export function validateHandoff(opts = {}) {
       errors.push(`contract output.schema '${schemaRef}' does not exist on disk`);
     } else {
       const schema = readJson(schemaPath);
-      for (const field of schema.required || []) {
-        if (!hasField(artifact, field)) errors.push(`artifact missing schema-required field: ${field}`);
-      }
+      collectSchemaShapeErrors(artifact, schema, 'artifact', errors);
     }
   }
 
@@ -304,6 +351,43 @@ function hasField(obj, field) {
   return Object.prototype.hasOwnProperty.call(obj, field) && obj[field] != null && obj[field] !== '';
 }
 
+// Stricter than hasField: an empty array counts as "declared but empty", not
+// present. Used for output.mustContain / mustContainOneOf, mirroring
+// lib/specialist-contracts.mjs's validatePacket — a reviewer with
+// findings: [] and no noIssuesFoundAt must not read as "findings present".
+
+function isPresentValue(value) {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string' && value.trim() === '') return false;
+  if (Array.isArray(value) && value.length === 0) return false;
+  return true;
+}
+
+/**
+ * Recursively validate `value` against a JSON-schema-shaped `schema`,
+ * collecting `required` and `enum` violations (both top-level and nested
+ * through `properties` and array `items`). Bounded to the constraint kinds
+ * contract output schemas actually use — not a general JSON Schema validator.
+ */
+function collectSchemaShapeErrors(value, schema, pathLabel, errors) {
+  if (!schema || typeof schema !== 'object') return;
+  if (value === undefined || value === null) return;
+  for (const field of schema.required || []) {
+    if (!hasField(value, field)) errors.push(`${pathLabel} missing schema-required field: ${field}`);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${pathLabel} value '${value}' not in schema enum: ${schema.enum.join(', ')}`);
+  }
+  if (schema.properties && typeof value === 'object' && !Array.isArray(value)) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (key in value) collectSchemaShapeErrors(value[key], propSchema, `${pathLabel}.${key}`, errors);
+    }
+  }
+  if (schema.type === 'array' && schema.items && Array.isArray(value)) {
+    value.forEach((item, i) => collectSchemaShapeErrors(item, schema.items, `${pathLabel}[${i}]`, errors));
+  }
+}
+
 /**
  * Validate team boundary enforcement on a contract.
  * Returns array of error strings (empty if validation passes).
@@ -471,21 +555,26 @@ function claimsHaveCitations(body) {
 
 /**
  * Run structured postcondition checks against a handoff's output artifact on
- * disk. Postconditions can be strings (descriptive, ignored here) or objects
- * with { id, check, field?, section? }. Returns an array of error strings.
+ * disk. Every postcondition is classified via `postconditionType`:
+ * `executable` entries carry a `check` this function runs; `advisory`
+ * entries are documented but deliberately not mechanically checked (see
+ * lib/decisions/registry.mjs's contract-decision classification). Bare
+ * strings are a legacy shape, tolerated but never executed. Returns an
+ * array of error strings.
  */
 export function validateArtifactPostconditions({ contract, artifactPath, cwd = process.cwd(), rootDir } = {}) {
   if (!contract?.postconditions?.length) return [];
+  const executableDeclared = contract.postconditions.filter((p) => typeof p === 'object' && p !== null && p.check);
   if (!artifactPath || !existsSync(artifactPath)) {
-    const structured = contract.postconditions.filter((p) => typeof p === 'object');
-    if (structured.length === 0) return [];
+    if (executableDeclared.length === 0) return [];
     return [`postcondition checks declared but artifact not found on disk: ${artifactPath}`];
   }
   const text = readFileSync(artifactPath, 'utf8');
   const { frontmatter, body } = parseArtifactFrontmatter(text);
   const errors = [];
   for (const pc of contract.postconditions) {
-    if (typeof pc !== 'object') continue;
+    if (typeof pc !== 'object' || pc === null) continue;
+    if (pc.postconditionType === 'advisory' || !pc.check) continue;
     const tag = pc.id || pc.check;
     switch (pc.check) {
       case 'artifact-has-frontmatter-field': {

package/lib/contracts/violation-log.mjs

@@ -100,6 +100,49 @@ function violationMatchesTail(tail, contractId, direction, missing, packet) {
     && JSON.stringify(tailKeys) === JSON.stringify(keys);
 }
 
+const BARE_GOAL_FIELD_LABELS = ['intent', 'workCategory', 'riskFlags', 'acceptanceCriteria'];
+
+const RESEARCHER_PROBE_MISSING = [
+  'artifact missing required field: question',
+  'artifact missing required field: method',
+  'artifact missing required field: sources',
+  'artifact missing required field: findings',
+  'artifact missing required field: confidence',
+];
+
+const A11Y_PROBE_MISSING = [
+  'artifact missing required field: findings',
+  'artifact missing required field: wcagCriterion',
+  'artifact missing required field: userImpact',
+];
+
+function missingBareGoalConstructFields(missing) {
+  if (!Array.isArray(missing) || missing.length !== BARE_GOAL_FIELD_LABELS.length) return false;
+  return BARE_GOAL_FIELD_LABELS.every((field) =>
+    missing.some((entry) => String(entry).includes(field)),
+  );
+}
+
+function isBareGoalConstructViolation(row) {
+  if (row?.contractId !== 'construct-to-orchestrator') return false;
+  if (!missingBareGoalConstructFields(row.missing)) return false;
+  const keys = row.packet_keys ?? row.packetKeys;
+  return Array.isArray(keys) && keys.length === 1 && keys[0] === 'goal';
+}
+
+function isEmptyProbeViolation(row, contractId, expectedMissing) {
+  if (row?.contractId !== contractId) return false;
+  const keys = row.packet_keys ?? row.packetKeys;
+  if (!Array.isArray(keys) || keys.length !== 0) return false;
+  return JSON.stringify(row.missing) === JSON.stringify(expectedMissing);
+}
+
+export function isDevSessionContractNoise(row) {
+  return isBareGoalConstructViolation(row)
+    || isEmptyProbeViolation(row, 'researcher-to-architect', RESEARCHER_PROBE_MISSING)
+    || isEmptyProbeViolation(row, 'accessibility-to-qa', A11Y_PROBE_MISSING);
+}
+
 function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
 
 function readLastAgent() {
@@ -160,12 +203,12 @@ export function logViolation(contractId, direction, missing, packet, extra = {})
  * Rotated segments are intentionally not included — this is the doctor
  * surface, scoped to the active window.
  */
-export function recentViolations({ windowMs = 24 * 60 * 60 * 1000, repoRoot } = {}) {
+export function recentViolations({ windowMs = 24 * 60 * 60 * 1000, repoRoot, excludeDevNoise = false, limit = Infinity, now = Date.now() } = {}) {
   const file = logFile(repoRoot);
   if (!existsSync(file)) return [];
   const supersedeCutoff = readViolationSupersedeCutoff(repoRoot);
   try {
-    const windowCutoff = Date.now() - windowMs;
+    const windowCutoff = now - windowMs;
     return readFileSync(file, 'utf8')
       .trim()
       .split('\n')
@@ -175,8 +218,11 @@ export function recentViolations({ windowMs = 24 * 60 * 60 * 1000, repoRoot } =
         if (!r) return false;
         const ts = new Date(r.ts).getTime();
         if (supersedeCutoff != null && ts <= supersedeCutoff) return false;
-        return ts >= windowCutoff;
-      });
+        if (ts < windowCutoff) return false;
+        if (excludeDevNoise && isDevSessionContractNoise(r)) return false;
+        return true;
+      })
+      .slice(-limit);
   } catch { return []; }
 }
 

package/lib/db/migrate.mjs

@@ -0,0 +1,69 @@
+/**
+ * lib/db/migrate.mjs — Postgres migration runner.
+ *
+ * The runner only operates when a SQL client is explicitly configured. Migration
+ * files are repo-owned SQL, so sql.unsafe is limited to this static directory.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DB_DIR = path.dirname(fileURLToPath(import.meta.url));
+export const MIGRATIONS_DIR = path.join(DB_DIR, 'migrations');
+export const MIGRATIONS_TABLE = 'construct_schema_migrations';
+
+function migrationId(filePath) {
+  return path.basename(filePath).replace(/\.sql$/i, '');
+}
+
+export function listMigrationFiles({ migrationsDir = MIGRATIONS_DIR } = {}) {
+  if (!fs.existsSync(migrationsDir)) return [];
+  return fs.readdirSync(migrationsDir)
+    .filter((name) => /^\d+_.+\.sql$/i.test(name))
+    .sort()
+    .map((name) => path.join(migrationsDir, name));
+}
+
+export async function ensureMigrationsTable(sql) {
+  await sql`
+    CREATE TABLE IF NOT EXISTS construct_schema_migrations (
+      id TEXT PRIMARY KEY,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `;
+}
+
+export async function getAppliedMigrations(sql) {
+  await ensureMigrationsTable(sql);
+  const rows = await sql`SELECT id, applied_at FROM construct_schema_migrations ORDER BY id`;
+  return rows.map((row) => ({ id: row.id, appliedAt: row.applied_at }));
+}
+
+export async function getMigrationStatus(sql, opts = {}) {
+  const files = listMigrationFiles(opts);
+  const applied = new Set((await getAppliedMigrations(sql)).map((row) => row.id));
+  return files.map((file) => {
+    const id = migrationId(file);
+    return { id, file, applied: applied.has(id) };
+  });
+}
+
+export async function applyMigrations(sql, opts = {}) {
+  await ensureMigrationsTable(sql);
+  const applied = new Set((await getAppliedMigrations(sql)).map((row) => row.id));
+  const appliedNow = [];
+
+  for (const file of listMigrationFiles(opts)) {
+    const id = migrationId(file);
+    if (applied.has(id)) continue;
+    const body = fs.readFileSync(file, 'utf8');
+    await sql.begin(async (tx) => {
+      await tx.unsafe(body);
+      await tx`INSERT INTO construct_schema_migrations (id) VALUES (${id})`;
+    });
+    appliedNow.push(id);
+  }
+
+  return { applied: appliedNow, status: await getMigrationStatus(sql, opts) };
+}

package/lib/db/migrations/001_orchestration_runs.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS construct_orchestration_runs (
+  run_id TEXT,
+  project TEXT,
+  created_at TEXT,
+  status TEXT,
+  execution_mode TEXT,
+  payload JSONB,
+  PRIMARY KEY (run_id, project)
+);

package/lib/db/migrations/002_queue_provider.sql

@@ -0,0 +1,50 @@
+CREATE TABLE IF NOT EXISTS construct_queue_items (
+  project TEXT NOT NULL,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  queue_name TEXT NOT NULL DEFAULT 'intake',
+  item_id TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (
+    status IN ('pending', 'claimed', 'processed', 'skipped', 'awaiting_approval', 'dead_letter')
+  ),
+  payload JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  available_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  attempt INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL DEFAULT 3,
+  claimed_by TEXT,
+  lease_expires_at TIMESTAMPTZ,
+  processed_at TIMESTAMPTZ,
+  processed_by TEXT,
+  skipped_at TIMESTAMPTZ,
+  skipped_by TEXT,
+  terminal_reason TEXT,
+  PRIMARY KEY (project, tenant_id, queue_name, item_id)
+);
+
+CREATE INDEX IF NOT EXISTS construct_queue_items_claim_idx
+  ON construct_queue_items (project, tenant_id, queue_name, status, available_at, created_at);
+
+CREATE INDEX IF NOT EXISTS construct_queue_items_lease_idx
+  ON construct_queue_items (project, tenant_id, queue_name, lease_expires_at)
+  WHERE status = 'claimed';
+
+CREATE TABLE IF NOT EXISTS construct_queue_claims (
+  claim_id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  queue_name TEXT NOT NULL DEFAULT 'intake',
+  item_id TEXT NOT NULL,
+  worker_id TEXT NOT NULL,
+  attempt INTEGER NOT NULL,
+  claimed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  lease_expires_at TIMESTAMPTZ NOT NULL,
+  released_at TIMESTAMPTZ,
+  release_reason TEXT,
+  FOREIGN KEY (project, tenant_id, queue_name, item_id)
+    REFERENCES construct_queue_items (project, tenant_id, queue_name, item_id)
+    ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS construct_queue_claims_item_idx
+  ON construct_queue_claims (project, tenant_id, queue_name, item_id, claimed_at DESC);

package/lib/db/migrations/003_worker_registry.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS construct_workers (
+  project TEXT NOT NULL,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  worker_id TEXT NOT NULL,
+  host TEXT,
+  pid INTEGER,
+  capabilities JSONB NOT NULL DEFAULT '[]'::jsonb,
+  registered_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  heartbeat_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  lease_ttl_seconds INTEGER NOT NULL DEFAULT 120,
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'stale', 'stopped')),
+  metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+  PRIMARY KEY (project, tenant_id, worker_id)
+);
+
+CREATE INDEX IF NOT EXISTS construct_workers_heartbeat_idx
+  ON construct_workers (project, tenant_id, heartbeat_at);

package/lib/db/migrations/004_trace_events.sql

@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS construct_trace_events (
+  project TEXT NOT NULL,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  trace_id TEXT NOT NULL,
+  span_id TEXT NOT NULL,
+  parent_span_id TEXT,
+  event_type TEXT NOT NULL,
+  role TEXT,
+  task_id TEXT,
+  metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (project, tenant_id, trace_id, span_id)
+);
+
+CREATE INDEX IF NOT EXISTS construct_trace_events_trace_idx
+  ON construct_trace_events (project, tenant_id, trace_id, created_at);

package/lib/db/migrations/005_shared_memory.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS construct_shared_memory (
+  id TEXT NOT NULL,
+  project TEXT NOT NULL,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  category TEXT NOT NULL,
+  summary TEXT,
+  content TEXT,
+  tags JSONB NOT NULL DEFAULT '[]'::jsonb,
+  provenance JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (project, tenant_id, id)
+);
+
+CREATE INDEX IF NOT EXISTS construct_shared_memory_project_idx
+  ON construct_shared_memory (project, tenant_id, created_at);

package/lib/db/migrations/006_orchestration_runs_tenant.sql

@@ -0,0 +1,5 @@
+ALTER TABLE construct_orchestration_runs
+  ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'local';
+
+CREATE INDEX IF NOT EXISTS construct_orchestration_runs_tenant_idx
+  ON construct_orchestration_runs (project, tenant_id, created_at);

package/lib/decisions/enforced-baseline.json

@@ -14,11 +14,9 @@
     "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",

package/lib/decisions/registry.mjs

@@ -165,8 +165,9 @@ function contractDecisions({ repoRoot, bindings }) {
     const checks = [];
     let advisoryPostconditions = 0;
     for (const pc of c.postconditions || []) {
-      if (typeof pc === 'string') advisoryPostconditions += 1;
-      else if (pc && pc.check) checks.push(pc.id || pc.check);
+      if (typeof pc !== 'object' || pc === null) { advisoryPostconditions += 1; continue; }
+      if (pc.check) checks.push(pc.id || pc.check);
+      else if (pc.postconditionType === 'advisory' || !pc.postconditionType) advisoryPostconditions += 1;
     }
     const enforcingTests = bindings.get(c.id) || [];
     out.push({

package/lib/deployment/parity-contract.mjs

@@ -25,7 +25,7 @@ export const PARITY_CONTRACT = {
   queue: {
     parityClass: 'parity',
     capability: 'Work intake queue (enqueue, list pending, mark processed)',
-    rationale: 'Filesystem queue (solo) and Postgres queue (team) implement one interface via lib/intake/queue.mjs.',
+    rationale: 'One kind:queue contract via lib/intake/queue.mjs; filesystem is the solo default and Postgres is the team/enterprise default with explicit degraded git fallback.',
     evidence: 'tests/intake-queue-factory.test.mjs',
   },
   memory: {

package/lib/deployment-mode.mjs

@@ -7,13 +7,20 @@
  * (`getDeploymentMode(env, {cwd})`); the resource topology for each mode
  * is derived here, not stored.
  */
+import fs from 'node:fs';
+import path from 'node:path';
 import { loadProjectConfig } from './config/project-config.mjs';
+import { resolveTenantContext, TenantResolutionError } from './tenant/context.mjs';
 
 export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
 export const DEFAULT_DEPLOYMENT_MODE = 'solo';
 
 export const DEPLOYMENT_MODE_ENV_KEY = 'CONSTRUCT_DEPLOYMENT_MODE';
 
+// The queue dimension names the default kind:'queue' provider, not a hardcoded
+// backend. Solo keeps the zero-dependency local provider; team/enterprise now
+// default to Postgres so distributed claims are row-locked and lease-backed.
+
 const RESOURCE_TOPOLOGY = {
   solo: {
     queue: 'filesystem',
@@ -45,8 +52,8 @@ const RESOURCE_TOPOLOGY = {
 };
 
 const MODE_DESCRIPTIONS = {
-  solo: 'Individual usage. Filesystem queue, local repo state, optional Postgres/Docker/telemetry.',
-  team: 'Shared usage. Postgres queue, shared memory, Docker worker pool, central telemetry, brokered MCP.',
+  solo: 'Individual usage. Filesystem intake queue, local repo state, optional Postgres/Docker/telemetry.',
+  team: 'Shared usage. Postgres intake queue, shared memory, Docker worker pool, central telemetry, brokered MCP.',
   enterprise: 'Hardened usage. Adds tenant isolation, RBAC/ABAC scaffolding, isolated worker containers, signed MCP allowlists, mandatory audit on top of team.',
 };
 
@@ -80,7 +87,76 @@ export function resolveResourceMode(mode = DEFAULT_DEPLOYMENT_MODE) {
   return { ...topology };
 }
 
+// ADR-0057 (A7) IMPLEMENT-NOW: enterprise mode without a resolvable tenant id
+// fails closed at startup rather than running unlabeled multi-tenant traffic.
+// Solo/team resolve to the explicit default tenant 'local' and never throw
+// here. Call once per process/runtime start (CLI entry, MCP server boot,
+// orchestration runtime) — resolveTenantContext itself is cheap and pure, so
+// re-validating per call is safe but redundant beyond the first.
+
+export function validateTenantAtStartup(env = process.env, { cwd } = {}) {
+  const mode = getDeploymentMode(env, { cwd });
+  let config = null;
+  try {
+    ({ config } = loadProjectConfig(cwd, env));
+  } catch { /* loader is best-effort — resolveTenantContext still sees env */ }
+  return resolveTenantContext({ env, config, mode });
+}
+
+export { TenantResolutionError };
+
 export function describeResourceLine(mode = DEFAULT_DEPLOYMENT_MODE) {
   const r = resolveResourceMode(mode);
   return `queue:${r.queue} · memory:${r.memory} · workers:${r.workers} · telemetry:${r.telemetry}`;
 }
+
+// Thrown when a team/enterprise mode requires a capability that is unavailable
+// and the caller has not opted into degraded operation via CONSTRUCT_DEGRADED_OK.
+
+export class DeploymentModeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DeploymentModeError';
+  }
+}
+
+/**
+ * requireTeamCapabilityOrDegrade(subsystem, isAvailable, env, { cwd } = {})
+ *
+ * Enforces mode honesty: team/enterprise modes must not silently fall back to
+ * solo behavior when a required subsystem is unavailable.
+ *
+ * - If mode is solo: no-op (solo degrades gracefully by design).
+ * - If mode is team/enterprise AND isAvailable is true: no-op.
+ * - If mode is team/enterprise AND isAvailable is false:
+ *   - If CONSTRUCT_DEGRADED_OK includes `subsystem` → logs a durable degradation
+ *     record to `.cx/degradation.jsonl` (if cwd is available) and returns normally.
+ *   - Otherwise → throws DeploymentModeError.
+ */
+export function requireTeamCapabilityOrDegrade(subsystem, isAvailable, env = process.env, { cwd } = {}) {
+  const mode = getDeploymentMode(env, { cwd });
+  if (mode === 'solo') return; // solo is always best-effort
+  if (isAvailable) return;
+
+  const degradedOk = String(env?.CONSTRUCT_DEGRADED_OK || '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (!degradedOk.includes(subsystem)) {
+    throw new DeploymentModeError(
+      `team mode requires ${subsystem}; set CONSTRUCT_DEGRADED_OK=${subsystem} to allow degraded operation`,
+    );
+  }
+
+  // Degraded operation is explicitly permitted — write a durable record and continue.
+  const record = JSON.stringify({
+    ts: new Date().toISOString(),
+    mode,
+    subsystem,
+    degradedOk: true,
+  });
+  if (cwd) {
+    try {
+      const cxDir = path.join(cwd, '.cx');
+      fs.mkdirSync(cxDir, { recursive: true });
+      fs.appendFileSync(path.join(cxDir, 'degradation.jsonl'), record + '\n', 'utf8');
+    } catch { /* degradation log is best-effort */ }
+  }
+}

package/lib/diagram-export.mjs

@@ -53,7 +53,16 @@ const MERMAID_INIT = `%%{init: {
   'look': 'handDrawn',
   'fontFamily': '${MERMAID_FONT}',
   'flowchart': {
-    'htmlLabels': false
+    'htmlLabels': false,
+    'nodeSpacing': 46,
+    'rankSpacing': 56,
+    'padding': 12
+  },
+  'quadrantChart': {
+    'chartWidth': 620,
+    'chartHeight': 460,
+    'pointLabelFontSize': 13,
+    'pointRadius': 4
   },
   'themeVariables': {
     'fontFamily': '${MERMAID_FONT}',

package/lib/distill.mjs

@@ -17,6 +17,7 @@ import {
   UTF8_TEXT_EXTS,
   extractDocumentText as extractSharedDocumentText,
 } from './document-extract.mjs';
+import { isMainModule } from './roots.mjs';
 
 const TEXT_EXTS = EXTRACTABLE_DOCUMENT_EXTS;
 
@@ -359,7 +360,9 @@ export async function distill(dir, { format = 'summary', query = '', mode = 'aut
   const result = await withGenAiSpan('chat', {
     [GenAiAttrs.SYSTEM]: 'anthropic',
     [GenAiAttrs.OPERATION_NAME]: 'chat',
-    [GenAiAttrs.REQUEST_MODEL]: process.env.CONSTRUCT_MODEL || 'claude-3-5-sonnet',
+    // Telemetry label only — the real model is whatever the user's claude CLI
+    // resolves; never imply a pinned model id here.
+    [GenAiAttrs.REQUEST_MODEL]: process.env.CONSTRUCT_MODEL || 'claude-cli-default',
     'construct.operation': 'distill',
     'construct.prompt_chars': prompt.length,
   }, async (span) => {
@@ -412,7 +415,7 @@ export async function runDistillCli(argv = process.argv.slice(2)) {
   });
 }
 
-const isMain = import.meta.url === `file://${process.argv[1]}`;
+const isMain = isMainModule(import.meta.url);
 if (isMain) {
   const { positional, flags } = parseArgs(process.argv.slice(2));
   const dir = positional[0];

package/lib/docs-verify.mjs

@@ -23,6 +23,7 @@ import { statSync, readFileSync, existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { hasIntakeReference } from "./intake/traceability.mjs";
 import { ensureCxDir } from "./project-init-shared.mjs";
+import { isMainModule } from './roots.mjs';
 
 const args = process.argv.slice(2);
 const quickMode = args.includes("--quick");
@@ -463,7 +464,7 @@ function main() {
   process.exit(0);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main();
 }
 

package/lib/doctor/cli.mjs

@@ -85,6 +85,7 @@ export async function runCli(args) {
       import('./watchers/service-health.mjs'),
       import('./watchers/bd-watch.mjs'),
       import('./watchers/consistency.mjs'),
+      import('./watchers/orchestration-runs.mjs'),
     ]);
     for (const w of watchers) {
       const r = await w.tick();