@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/test-corpus-inventory.mjs

@@ -0,0 +1,313 @@
+/**
+ * lib/test-corpus-inventory.mjs — classify the Construct test corpus for certification traceability.
+ *
+ * Walks all test files under tests/, assigns layer and signal category per file, extracts
+ * @capability markers, and compares shipped capability-matrix rows against the behavior
+ * ledger to surface release-critical gaps. Output feeds tests/capabilities/corpus-inventory.json.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadCapabilityLedger } from './capability-ledger.mjs';
+
+export const CORPUS_CATEGORIES = Object.freeze([
+  'structural-guard',
+  'unit',
+  'integration',
+  'hook',
+  'functional',
+  'live-provider',
+  'visual',
+  'contract-subsystem',
+]);
+
+const STRUCTURAL_GUARD_NAMES = [
+  'agent-prompts',
+  'release-workflow',
+  'parity',
+  'comment-lint',
+  'agents-registry',
+  'cli-catalog-accuracy',
+  'auto-docs',
+  'docs-verify',
+  'sync-contract',
+  'release-gates',
+  'template-policy',
+];
+
+const SUBSYSTEM_DIRS = [
+  'profile',
+  'profiles',
+  'outcomes',
+  'flavors',
+  'knowledge',
+  'intake',
+  'roles',
+  'embed',
+  'doctor',
+  'integrations',
+  'graph',
+  'evals',
+  'reflect',
+  'hooks',
+  'functional',
+  'capabilities',
+  'fixtures',
+  'e2e',
+];
+
+const SHIPPED_MATRIX_CAPABILITIES = Object.freeze([
+  { id: 'document', ledgerHints: ['artifact', 'docs'] },
+  { id: 'research', ledgerHints: ['research', 'knowledge', 'ask'] },
+  { id: 'ingest', ledgerHints: ['document.ingest', 'ingest'] },
+  { id: 'diagram', ledgerHints: ['diagram', 'wireframe'] },
+  { id: 'demo', ledgerHints: ['demo'] },
+  { id: 'publish', ledgerHints: ['publish', 'artifact', 'export'] },
+]);
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json')) && fs.existsSync(path.join(current, 'tests'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export function defaultCorpusInventoryPath(rootDir = process.cwd()) {
+  return path.join(findConstructRoot(rootDir), 'tests', 'capabilities', 'corpus-inventory.json');
+}
+
+function listTestFiles(testsDir) {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.tmp') continue;
+        walk(absolute);
+        continue;
+      }
+      if (/\.test\.(mjs|js)$/.test(entry.name)) files.push(absolute);
+    }
+  };
+  walk(testsDir);
+  return files.sort();
+}
+
+function readHeaderNote(content) {
+  const block = content.match(/^\/\*\*([\s\S]*?)\*\//)?.[1] ?? content.match(/^\/\/\/([\s\S]*?)(?:\n\n|\nimport )/)?.[1];
+  if (!block) return '';
+  const line = block
+    .split('\n')
+    .map((row) => row.replace(/^\s*\*\s?/, '').trim())
+    .find((row) => row.length > 0 && !row.startsWith('@'));
+  return line?.slice(0, 160) ?? '';
+}
+
+function classifyLayer(relPath, content) {
+  const base = path.basename(relPath);
+  if (relPath.includes('tests/functional/') || base.includes('.functional.test.')) return 'functional';
+  if (base.includes('real-llm') || content.includes('CONSTRUCT_E2E_REAL_LLM')) return 'live-provider';
+  if (/visual/i.test(base) || /playwright/i.test(content)) return 'visual';
+  if (
+    /store/i.test(base)
+    || /postgres/i.test(base)
+    || /hybrid/i.test(base)
+    || /vector-client/i.test(base)
+    || relPath.includes('/hooks/')
+    || /hook/i.test(base)
+  ) return 'integration';
+  return 'unit';
+}
+
+function classifyCategory(relPath, layer, content) {
+  const base = path.basename(relPath);
+  const dir = path.dirname(relPath);
+  if (layer === 'functional') return 'functional';
+  if (layer === 'live-provider') return 'live-provider';
+  if (layer === 'visual') return 'visual';
+  if (dir.includes('/hooks/') || /\bhook/i.test(base)) return 'hook';
+  if (STRUCTURAL_GUARD_NAMES.some((name) => base.includes(name))) return 'structural-guard';
+  if (layer === 'integration') return 'integration';
+  if (SUBSYSTEM_DIRS.some((segment) => dir.split(path.sep).includes(segment))) return 'contract-subsystem';
+  if (/@capability\s+/.test(content) && layer === 'unit') return 'unit';
+  return 'unit';
+}
+
+function extractCapabilities(content) {
+  return [...content.matchAll(/@capability\s+([a-z][a-z0-9]*(?:[.-][a-z0-9]+)*)/g)].map((match) => match[1]);
+}
+
+function detectSkipped(content) {
+  return /\btest\.skip\s*\(|\bit\.skip\s*\(|\bdescribe\.skip\s*\(/.test(content);
+}
+
+export function classifyTestFile(relPath, content) {
+  const layer = classifyLayer(relPath, content);
+  return {
+    path: relPath.replace(/\\/g, '/'),
+    layer,
+    category: classifyCategory(relPath, layer, content),
+    capabilities: extractCapabilities(content),
+    skipped: detectSkipped(content),
+    maintainerNotes: readHeaderNote(content),
+  };
+}
+
+function countBy(items, key) {
+  const totals = {};
+  for (const item of items) totals[item[key]] = (totals[item[key]] ?? 0) + 1;
+  return totals;
+}
+
+function ledgerCoversHint(ledgerIds, hints) {
+  return hints.some((hint) => ledgerIds.some((id) => id.includes(hint)));
+}
+
+export function computeReleaseCriticalGaps(ledger) {
+  const allLedgerIds = (ledger?.capabilities ?? []).map((entry) => entry.id);
+  const gaps = [];
+
+  for (const row of SHIPPED_MATRIX_CAPABILITIES) {
+    if (ledgerCoversHint(allLedgerIds, row.ledgerHints)) continue;
+    gaps.push({
+      source: 'docs/audit/capability-matrix.md',
+      capability: row.id,
+      status: 'shipped',
+      reason: 'no ledger entry matches shipped capability hints',
+      suggestedLedgerHints: row.ledgerHints,
+    });
+  }
+
+  return gaps;
+}
+
+export function buildTestCorpusInventory({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const testsDir = path.join(root, 'tests');
+  const files = listTestFiles(testsDir);
+  const entries = files.map((absolute) => {
+    const rel = path.relative(root, absolute);
+    const content = fs.readFileSync(absolute, 'utf8');
+    return classifyTestFile(rel, content);
+  });
+
+  const { ledger } = loadCapabilityLedger({ rootDir: root });
+  const topLevel = entries.filter((entry) => entry.path.split('/').length === 2).length;
+  const nested = entries.length - topLevel;
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    generator: 'node scripts/generate-test-corpus-inventory.mjs',
+    summary: {
+      testFiles: entries.length,
+      topLevelTestFiles: topLevel,
+      nestedTestFiles: nested,
+      skippedFiles: entries.filter((entry) => entry.skipped).length,
+      capabilityMarkedFiles: entries.filter((entry) => entry.capabilities.length > 0).length,
+      byLayer: countBy(entries, 'layer'),
+      byCategory: countBy(entries, 'category'),
+    },
+    releaseCriticalGaps: computeReleaseCriticalGaps(ledger),
+    files: entries,
+  };
+}
+
+export function formatAuditAtAGlance(inventory) {
+  const { summary } = inventory;
+  const functional = summary.byCategory.functional ?? 0;
+  const subsystem = summary.byCategory['contract-subsystem'] ?? 0;
+  const hook = summary.byCategory.hook ?? 0;
+  return [
+    `- **${summary.testFiles} test files** total: ${summary.topLevelTestFiles} at \`tests/\` top level + ${summary.nestedTestFiles} in subdirectories.`,
+    `- **Layers:** ${Object.entries(summary.byLayer).map(([k, v]) => `${k} ${v}`).join(', ')}.`,
+    `- **Functional layer:** ${functional} file(s) under \`tests/functional/\` or \`*.functional.test.mjs\`. End-to-end checks spawn the real binary or import real modules in an isolated tmpdir.`,
+    `- **Contract subsystems:** ${subsystem} file(s) under profile/outcomes/hooks/knowledge/intake/graph/evals and related subdirs.`,
+    `- **Hook tests:** ${hook} file(s) (including \`tests/hooks/\`).`,
+    `- **Capability-marked:** ${summary.capabilityMarkedFiles} file(s) declare \`@capability\` markers.`,
+    `- **Skipped markers:** ${summary.skippedFiles} file(s) contain \`test.skip\` / \`describe.skip\` (see inventory for paths).`,
+    `- **Regenerate inventory:** \`node scripts/generate-test-corpus-inventory.mjs\`.`,
+  ].join('\n');
+}
+
+export function refreshAuditMarkdown(inventory, { rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const auditPath = path.join(root, 'tests', 'AUDIT.md');
+  const markdown = fs.readFileSync(auditPath, 'utf8');
+  const start = '## At a glance';
+  const end = '## Categories';
+  const startIdx = markdown.indexOf(start);
+  const endIdx = markdown.indexOf(end);
+  if (startIdx === -1 || endIdx === -1) throw new Error('tests/AUDIT.md missing At a glance section');
+  const replacement = `${start}\n\n${formatAuditAtAGlance(inventory)}\n\n`;
+  return `${markdown.slice(0, startIdx)}${replacement}${markdown.slice(endIdx)}`;
+}
+
+export function validateCorpusInventory({ rootDir, inventory: supplied } = {}) {
+  const root = findConstructRoot(rootDir);
+  const inventory = supplied ?? JSON.parse(fs.readFileSync(defaultCorpusInventoryPath(root), 'utf8'));
+  const errors = [];
+  const warnings = [];
+  const onDisk = listTestFiles(path.join(root, 'tests')).map((absolute) => path.relative(root, absolute).replace(/\\/g, '/'));
+  const indexed = new Set((inventory.files ?? []).map((entry) => entry.path));
+
+  if (inventory.version !== 1) errors.push('corpus-inventory.version must equal 1');
+  if (!Array.isArray(inventory.files) || inventory.files.length === 0) errors.push('corpus-inventory.files must be non-empty');
+
+  for (const rel of onDisk) {
+    if (!indexed.has(rel)) errors.push(`missing inventory entry: ${rel}`);
+  }
+  for (const entry of inventory.files ?? []) {
+    if (!onDisk.includes(entry.path)) errors.push(`stale inventory entry: ${entry.path}`);
+    if (!CORPUS_CATEGORIES.includes(entry.category)) errors.push(`${entry.path}: invalid category ${entry.category}`);
+    if (!entry.path.endsWith('.test.mjs') && !entry.path.endsWith('.test.js')) errors.push(`${entry.path}: not a test file path`);
+  }
+
+  if ((inventory.summary?.testFiles ?? 0) !== (inventory.files?.length ?? 0)) {
+    errors.push('summary.testFiles must equal files.length');
+  }
+
+  if (!Array.isArray(inventory.releaseCriticalGaps) || inventory.releaseCriticalGaps.length === 0) {
+    warnings.push('releaseCriticalGaps is empty');
+  }
+
+  return {
+    filePath: defaultCorpusInventoryPath(root),
+    fileCount: inventory.files?.length ?? 0,
+    errors,
+    warnings,
+    pass: errors.length === 0,
+  };
+}
+
+export function writeCorpusInventoryArtifacts({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const inventory = buildTestCorpusInventory({ rootDir: root });
+  const inventoryPath = defaultCorpusInventoryPath(root);
+  fs.mkdirSync(path.dirname(inventoryPath), { recursive: true });
+  fs.writeFileSync(inventoryPath, `${JSON.stringify(inventory, null, 2)}\n`);
+  fs.writeFileSync(path.join(root, 'tests', 'AUDIT.md'), refreshAuditMarkdown(inventory, { rootDir: root }));
+  return { inventoryPath, inventory };
+}
+
+export function runCorpusInventoryAuditCli(args = [], { rootDir } = {}) {
+  if (args.includes('--write')) {
+    const { inventoryPath, inventory } = writeCorpusInventoryArtifacts({ rootDir });
+    process.stdout.write(`Wrote ${inventoryPath} (${inventory.files.length} files)\n`);
+    process.stdout.write('Updated tests/AUDIT.md At a glance section\n');
+    return validateCorpusInventory({ rootDir, inventory });
+  }
+  const result = validateCorpusInventory({ rootDir });
+  if (args.includes('--json')) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    process.stdout.write(`Corpus inventory: ${result.fileCount} files\n`);
+    if (result.errors.length) result.errors.forEach((error) => process.stderr.write(`  ✗ ${error}\n`));
+    if (result.warnings.length) result.warnings.forEach((warning) => process.stderr.write(`  ⚠ ${warning}\n`));
+    process.stdout.write(result.pass ? '  Result: PASS\n' : '  Result: FAIL\n');
+  }
+  if (!result.pass) process.exitCode = 1;
+  return result;
+}

package/lib/uninstall/uninstall.mjs

@@ -38,11 +38,10 @@ import { fileURLToPath } from 'node:url';
 import { multiSelect } from '../tty-prompts.mjs';
 import { getUserConfigDir, getUserEnvPath } from '../env-config.mjs';
 import { removeTomlTables, tomlString } from '../codex-config.mjs';
+import { postgresContainerName, LEGACY_PG_CONTAINER } from '../home-namespace.mjs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..', '..');
-
-const POSTGRES_CONTAINER = 'construct-postgres';
 const PGVECTOR_IMAGE = 'pgvector/pgvector:pg16';
 const PRESSURE_GUARD_LABEL = 'dev.construct.pressure-release';
 const MEMORY_MCP_KEYS = ['memory', 'cass'];
@@ -75,6 +74,7 @@ export function parseArgs(argv) {
 }
 
 function buildCategories({ cwd, home, withImages = false }) {
+  const pgContainerName = postgresContainerName(process.env, home);
   const dotConstruct = path.join(cwd, '.construct');
   const dotClaudeAgents = path.join(cwd, '.claude', 'agents');
   const dotClaudeCommands = path.join(cwd, '.claude', 'commands');
@@ -213,10 +213,19 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-postgres-container',
       scope: 'machine',
       risk: 'ask',
-      label: `Docker container "${POSTGRES_CONTAINER}" (stop + remove, including data)`,
-      detect: () => dockerContainerExists(POSTGRES_CONTAINER),
-      describe: () => 'Stops and removes the construct-postgres Docker container AND its data volume. The pgvector image stays cached. This destroys indexed observations — skip if you might restore.',
-      execute: () => removeDockerContainer(POSTGRES_CONTAINER),
+      label: `Docker container "${pgContainerName}" (stop + remove, including data)`,
+      detect: () => dockerContainerExists(pgContainerName) || dockerContainerExists(LEGACY_PG_CONTAINER),
+      describe: () => 'Stops and removes the Postgres container and its named data volume. The pgvector image stays cached. This destroys indexed observations — skip if you might restore.',
+      execute: () => {
+        const results = [];
+        if (dockerContainerExists(pgContainerName)) {
+          results.push(removeDockerContainer(pgContainerName, `postgres_${pgContainerName}-data`));
+        }
+        if (dockerContainerExists(LEGACY_PG_CONTAINER)) {
+          results.push(removeDockerContainer(LEGACY_PG_CONTAINER));
+        }
+        return results.join(', ') || 'nothing to remove';
+      },
     },
     {
       id: 'machine-postgres-compose',
@@ -468,12 +477,15 @@ function dockerContainerExists(name) {
   return probe.stdout.trim() === name;
 }
 
-function removeDockerContainer(name) {
+function removeDockerContainer(name, namedVolume = null) {
   const stop = spawnSync('docker', ['stop', name], { encoding: 'utf8' });
   const rm = spawnSync('docker', ['rm', '-v', name], { encoding: 'utf8' });
   if (rm.status !== 0) {
     throw new Error((rm.stderr || '').trim() || 'docker rm failed');
   }
+  if (namedVolume) {
+    spawnSync('docker', ['volume', 'rm', namedVolume], { encoding: 'utf8' });
+  }
   return stop.status === 0 ? 'stopped and removed (with volume)' : 'removed (with volume)';
 }
 

package/lib/update.mjs

@@ -11,6 +11,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 import { writeVersionStamp } from './maintenance/cleanup.mjs';
+import { reclaimOrphanedDockerResources, formatReclaim } from './maintenance/docker-reclaim.mjs';
 
 const PACKAGE_NAME = '@geraldmaron/construct';
 
@@ -131,6 +132,17 @@ export function runUpdate({ cwd, env = process.env, spawn = spawnSync, stdout =
     runStep(step, { spawn, env, stdout });
   }
 
+  // Reclaim Postgres containers and volumes left behind by deleted home
+  // namespaces. An upgrade is the once-per-version moment to sweep machine
+  // state without taxing ordinary commands. The disable switch opts a machine
+  // out of every auto-maintenance pass, not this sweep alone.
+  if (env.CONSTRUCT_DISABLE_AUTO_CLEANUP !== '1') {
+    try {
+      const line = formatReclaim(reclaimOrphanedDockerResources({ env }));
+      if (line) stdout.write(`${line}\n`);
+    } catch { /* reclaim is best-effort */ }
+  }
+
   // Advance the cleanup stamp to the checkout version so the next CLI
   // invocation doesn't run a full cleanup pass on the assumption that
   // an upgrade just happened.

package/lib/upgrade.mjs

@@ -8,9 +8,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { sanitizeNpmSpawnEnv } from './npm-spawn-env.mjs';
 import { fileURLToPath } from 'node:url';
 
 import { writeVersionStamp } from './maintenance/cleanup.mjs';
+import { reclaimOrphanedDockerResources, formatReclaim } from './maintenance/docker-reclaim.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, '..');
@@ -31,6 +33,7 @@ function getLatestVersion() {
   const result = spawnSync('npm', ['view', PACKAGE_NAME, 'version'], {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
+    env: sanitizeNpmSpawnEnv(process.env),
   });
   if (result.status !== 0) return null;
   return result.stdout.trim();
@@ -154,6 +157,17 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
     }
   }
 
+  // Reclaim Postgres containers and volumes left behind by deleted home
+  // namespaces. An upgrade is the once-per-version moment to sweep machine
+  // state without taxing ordinary commands. The disable switch opts a machine
+  // out of every auto-maintenance pass, not this sweep alone.
+  if (env.CONSTRUCT_DISABLE_AUTO_CLEANUP !== '1') {
+    try {
+      const line = formatReclaim(reclaimOrphanedDockerResources({ env }));
+      if (line) stdout.write(`${line}\n`);
+    } catch { /* reclaim is best-effort */ }
+  }
+
   // Advance the cleanup stamp so the next CLI invocation doesn't re-run a
   // full cleanup pass under the assumption that the user just upgraded.
   // Without this, every command pays the cleanup cost until something

package/lib/wireframe.mjs

@@ -19,6 +19,7 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { INK, FONTS } from './brand-tokens.mjs';
 
 const TYPES = ['flow', 'state', 'sequence', 'er', 'layout', 'user-journey'];
 
@@ -134,38 +135,43 @@ function mermaidUserJourney(description, keywords) {
 
 const SKETCH_CSS = `
 :root {
-  --ink: #222;
-  --paper: #fefdf8;
-  --rough: #6b6b6b;
-  --hint: #a9a9a9;
-  --accent: #2c5282;
+  --ink: ${INK.inkBody};
+  --paper: ${INK.paper};
+  --rough: ${INK.muted};
+  --hint: ${INK.faint};
+  --accent: ${INK.ink};
+  --hairline: ${INK.hairline};
+  --surface: ${INK.surface};
 }
 * { box-sizing: border-box; }
 body {
   margin: 0; padding: 2rem;
-  font-family: "Caveat", "Bradley Hand", "Comic Sans MS", cursive;
+  font-family: ${FONTS.sans};
   background: var(--paper);
   color: var(--ink);
-  line-height: 1.4;
+  line-height: 1.45;
+  font-size: 15px;
 }
 .wireframe { max-width: 1200px; margin: 0 auto; }
 .wireframe header, .wireframe nav, .wireframe main,
 .wireframe aside, .wireframe section, .wireframe footer,
 .block, .card {
-  border: 2px solid var(--ink);
-  border-radius: 6px;
+  border: 1px solid var(--hairline);
+  border-radius: 8px;
   padding: 1rem;
   margin: 0.5rem 0;
   position: relative;
-  background: var(--paper);
-  box-shadow: 3px 3px 0 var(--hint);
+  background: var(--surface);
+  box-shadow: none;
 }
-.wireframe header { background: #f3f0e7; }
+.wireframe header { background: var(--surface); }
 .label {
   position: absolute; top: -10px; left: 10px;
   background: var(--paper); padding: 0 6px;
-  font-size: 0.85em; color: var(--rough);
-  font-family: ui-monospace, Menlo, monospace;
+  font-size: 0.75rem; color: var(--rough);
+  font-family: ${FONTS.mono};
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
 }
 .row { display: grid; grid-template-columns: repeat(var(--cols, 3), 1fr); gap: 1rem; }
 .row-2 { --cols: 2; }

package/lib/worker/run.mjs

@@ -27,6 +27,7 @@ import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { emitTraceEvent, newTraceId, newSpanId } from './trace.mjs';
+import { ensureDiskWrite, warnBudgetOnce } from '../resources/budget.mjs';
 
 const DEFAULT_TIMEOUT_SECONDS = 300;
 const ARTIFACTS_SUBDIR = '.cx/runtime/worker';
@@ -120,8 +121,17 @@ export async function runJob({
   });
   clearTimeout(timer);
 
-  writeFileSync(stdoutPath, stdout, 'utf8');
-  writeFileSync(stderrPath, stderr, 'utf8');
+  const outBytes = Buffer.byteLength(stdout, 'utf8');
+  const errBytes = Buffer.byteLength(stderr, 'utf8');
+  const gate = ensureDiskWrite(rootDir, 'worker-logs', outBytes + errBytes, process.env);
+  let budgetSkipped = false;
+  if (gate.ok) {
+    writeFileSync(stdoutPath, stdout, 'utf8');
+    writeFileSync(stderrPath, stderr, 'utf8');
+  } else {
+    budgetSkipped = true;
+    warnBudgetOnce(gate.message || 'worker log write blocked by .cx/ disk budget', process.env);
+  }
 
   const durationMs = Date.now() - started;
   const status = timedOut ? 'timeout' : exitCode === 0 ? 'passed' : 'failed';
@@ -135,7 +145,10 @@ export async function runJob({
     stdoutPath,
     stderrPath,
     durationMs,
-    artifacts: [{ path: stdoutPath, kind: 'stdout' }, { path: stderrPath, kind: 'stderr' }],
+    artifacts: budgetSkipped
+      ? []
+      : [{ path: stdoutPath, kind: 'stdout' }, { path: stderrPath, kind: 'stderr' }],
+    budgetSkipped,
     traceId,
     spanId,
   };
@@ -147,7 +160,7 @@ export async function runJob({
     spanId,
     project: job.project,
     taskId: job.taskId,
-    metadata: { jobId: job.jobId, status, exitCode, durationMs, stdoutPath, stderrPath, timedOut },
+    metadata: { jobId: job.jobId, status, exitCode, durationMs, stdoutPath, stderrPath, timedOut, budgetSkipped },
   });
 
   return result;

package/lib/worker/trace.mjs

@@ -33,6 +33,7 @@ import path from 'node:path';
 import { createTelemetryClient } from '../telemetry/client.mjs';
 import { ensureCxDir } from '../project-init-shared.mjs';
 import { appendWithRotationSync } from '../logging/rotate.mjs';
+import { ensureDiskWrite, warnBudgetOnce } from '../resources/budget.mjs';
 
 const TRACE_SUBDIR = '.cx/traces';
 
@@ -183,9 +184,16 @@ export function emitTraceEvent({
     createdAt: new Date().toISOString(),
   };
   const shardPath = path.join(dir, `${todayShard()}.jsonl`);
-  appendWithRotationSync(shardPath, `${JSON.stringify(event)}\n`, {
-    maxBytes: traceMaxBytes(env),
-  });
+  const line = `${JSON.stringify(event)}\n`;
+  const gate = ensureDiskWrite(rootDir, 'traces', Buffer.byteLength(line), env);
+  if (gate.ok) {
+    appendWithRotationSync(shardPath, line, {
+      maxBytes: traceMaxBytes(env),
+    });
+  } else {
+    warnBudgetOnce(gate.message || 'trace write blocked by .cx/ disk budget', env);
+    return { ...event, budgetSkipped: true, budgetReason: gate.reason || 'budget-exceeded' };
+  }
 
   // Fire-and-forget export to the configured remote adapter. Silent no-op when not configured.
   exportToRemote(event, env, rootDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -26,7 +26,6 @@
     "platforms/**",
     "templates/**",
     "templates/distribution/**",
-    "db/**",
     "scripts/sync-specialists.mjs",
     "README.md",
     ".env.example"
@@ -57,20 +56,28 @@
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
     "lint:js": "eslint bin/construct \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"tests/**/*.mjs\"",
     "coverage": "c8 --reporter=text-summary --reporter=lcov --src=lib --src=bin node scripts/run-tests.mjs --exclude=tests/functional",
-    "docs:init": "node lib/init-docs.mjs --yes",
+    "docs:init": "node -e \"console.error('docs:init is deprecated — use: construct init --docs-preset=lean|product|full'); process.exit(1)\"",
     "docs:update": "node ./bin/construct docs:update",
     "docs:site": "node ./bin/construct docs:site",
-    "docs:dev": "npm --prefix apps/docs run dev",
-    "docs:build": "npm --prefix apps/docs run build",
+    "docs:dev": "node scripts/npm-run.mjs npm --prefix apps/docs run dev",
+    "docs:build": "node scripts/npm-run.mjs npm --prefix apps/docs run build",
     "lint:comments": "node ./bin/construct lint:comments",
     "lint:contracts": "node ./bin/construct lint:contracts",
     "lint:agents": "node ./bin/construct lint:agents",
     "build:sea": "esbuild bin/construct --bundle --platform=node --target=node20 --packages=external --outfile=dist/construct-bundle.cjs 2>&1 || (echo 'esbuild not found — install with: npm install -g esbuild' && exit 1)",
+    "build:chat": "esbuild apps/chat/tui/index.jsx --bundle --platform=node --format=esm --packages=external --jsx=automatic --jsx-import-source=react --outfile=apps/chat/dist/tui.mjs",
+    "build:chat-desktop": "node scripts/build-chat-desktop.mjs",
+    "build:chat-desktop:bundle": "node scripts/npm-run.mjs npm install --prefix apps/chat/desktop --include=dev && node scripts/npm-run.mjs npm --prefix apps/chat/desktop run build",
+    "build:dashboard": "node scripts/npm-run.mjs npm install --prefix apps/dashboard && node scripts/npm-run.mjs npm --prefix apps/dashboard run build",
+    "examples:deck": "node scripts/generate-deck-examples.mjs",
+    "examples:distribution": "node scripts/generate-distribution-examples.mjs",
+    "clean:artifacts": "node scripts/clean-artifacts.mjs",
     "lint:profiles": "node scripts/lint-profiles.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
-    "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node scripts/lint-commits-pr.mjs",
+    "adapters": "node lib/adapters-sync.mjs",
+    "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct docs:site --check && node ./bin/construct registry:generate-docs --check && node ./bin/construct docs:verify --strict && node scripts/alignment/census.mjs --ratchet && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node ./bin/construct certify gate && node scripts/lint-commits-pr.mjs",
     "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
     "audit:published": "node scripts/audit-published-artifact.mjs",
     "version": "node scripts/sync-construct-version.mjs && git add .construct/version",
@@ -86,23 +93,30 @@
     "js-yaml": "^4.2.0"
   },
   "optionalDependencies": {
+    "@ai-sdk/anthropic": "^3.0.85",
+    "@ai-sdk/openai": "^3.0.73",
+    "@ai-sdk/openai-compatible": "^2.0.51",
     "@huggingface/transformers": "^4.2.0",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/core": "^2.7.1",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
-    "@opentelemetry/resources": "^2.7.1",
-    "@opentelemetry/sdk-trace-node": "^1.25.0",
-    "@opentelemetry/semantic-conventions": "^1.25.0",
+    "ai": "^6.0.208",
+    "ink": "^7.1.0",
     "mammoth": "^1.12.0",
-    "unpdf": "^1.6.2"
+    "pptx-embed-fonts": "^0.0.6",
+    "pptxgenjs": "^4.0.1",
+    "react": "^19.2.7",
+    "unpdf": "^1.6.2",
+    "zod": "^4.4.3"
   },
   "overrides": {
-    "express-rate-limit": "8.5.1"
+    "express-rate-limit": "8.5.1",
+    "undici": "6.27.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "c8": "^11.0.0",
+    "esbuild": "^0.28.1",
     "eslint": "^10.4.1",
-    "globals": "^17.6.0"
+    "globals": "^17.6.0",
+    "ink-testing-library": "^4.0.0"
   }
 }