@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/templates/visual-requirements.mjs

@@ -1,66 +1,47 @@
 /**
- * lib/templates/visual-requirements.mjs — required visuals per document type.
+ * lib/templates/visual-requirements.mjs — required visuals and structure per document type.
  *
- * The machine-readable form of docs/concepts/doc-visual-matrix.md: which doc
- * types must carry which visual (a diagram of a given kind, or a table with given
- * columns), expressed as postcondition checks so the existing validate.mjs engine
- * enforces them. The shipped template for each listed type must satisfy its own
- * requirements — pinned by tests/template-visuals.test.mjs — so the templates can
- * never drift out of step with the matrix (beads wvbf.10 / wvbf.11).
+ * Loads structure and visual requirements from specialists/artifact-manifest.json
+ * (single source of truth) and merges legacy types not yet in the manifest.
+ * Paired with docs/concepts/doc-visual-matrix.md; pinned by template tests.
  */
 
 import { validateArtifactPostconditions } from '../contracts/validate.mjs';
+import {
+  structureRequirementsFromManifest,
+  visualRequirementsFromManifest,
+  getArtifactEntry,
+} from '../artifact-manifest.mjs';
+
+const LEGACY_STRUCTURE = {
+  'persona-artifact': ['Goals', 'Frustrations', 'Decision rights', 'Output contract', 'Failure modes', 'Evidence'],
+  'skill-artifact': ['What this skill produces', 'When to invoke it', 'Competency rubric', 'Failure modes', 'Worked example'],
+  'research-finding': ['SOURCES', 'FINDINGS', 'INFERENCES', 'CONFIDENCE', 'GAPS', 'RECOMMENDATION'],
+};
+
+export const STRUCTURE_REQUIREMENTS = {
+  ...structureRequirementsFromManifest(),
+  ...LEGACY_STRUCTURE,
+};
 
 export const VISUAL_REQUIREMENTS = {
-  runbook: [
-    { id: 'runbook-diagnostic-flowchart', check: 'artifact-has-mermaid', diagram: 'flowchart' },
-  ],
-  'incident-report': [
-    { id: 'incident-timeline-table', check: 'artifact-table-has-columns', columns: ['Time (UTC)', 'Event'] },
-  ],
-  rfc: [
-    { id: 'rfc-sequence-diagram', check: 'artifact-has-mermaid', diagram: 'sequenceDiagram' },
-  ],
+  ...visualRequirementsFromManifest(),
 };
 
 export function visualRequirementTypes() {
   return Object.keys(VISUAL_REQUIREMENTS);
 }
 
-// The structural floor of the quality rubric (ADR-0018): the sections a domain
-// expert expects for each doc type. Each shipped template must satisfy its own
-// entry — pinned by tests/structure-requirements.test.mjs — so a template can
-// never quietly drop a required section. Section requirements compose with the
-// VISUAL_REQUIREMENTS above; lintDocStructure runs both.
-
-export const STRUCTURE_REQUIREMENTS = {
-  adr: ['Problem', 'Decision', 'Rejected alternatives', 'Consequences', 'Reversibility'],
-  rfc: ['Summary', 'Motivation', 'Proposed design', 'Risks', 'Verification'],
-  prd: ['Problem', 'Goals', 'Success metrics', 'Risks and mitigations'],
-  'research-brief': ['Sources', 'Findings', 'Confidence summary', 'Recommendation'],
-  'incident-report': ['Summary', 'Severity rationale', 'Impact', 'Timeline', 'Trigger', 'Root cause', 'Contributing factors', 'Action items'],
-  runbook: ['Alert trigger', 'Symptoms', 'Impact', 'Severity and response', 'Diagnostic steps', 'Remediation', 'Rollback', 'Escalation'],
-  strategy: ['Vision', 'Bets', 'Non-bets', 'North Star Metric', 'Metrics', 'Milestones', 'Risks'],
-  'signal-brief': ['Signal', 'Evidence', 'Counter-signal', 'What would make this actionable'],
-  prfaq: ['Problem statement', 'Press release', 'External FAQ', 'Internal FAQ', 'Evidence appendix'],
-  'customer-profile': ['Snapshot', 'Active pain points', 'Open asks', 'Evidence links'],
-  'one-pager': ['Problem', 'Proposal', 'Why now', 'Success measure', 'Cost', 'Asks'],
-  'product-intelligence-report': ['Executive readout', 'Evidence base', 'Themes', 'Customer asks', 'Product implications', 'Recommended actions', 'Gaps and risks'],
-  'backlog-proposal': ['Source evidence', 'Proposed changes', 'Duplicate and conflict check', 'Approval request'],
-  'persona-artifact': ['Goals', 'Frustrations', 'Decision rights', 'Output contract', 'Failure modes', 'Evidence'],
-  'skill-artifact': ['What this skill produces', 'When to invoke it', 'Competency rubric', 'Failure modes', 'Worked example'],
-  'research-finding': ['SOURCES', 'FINDINGS', 'INFERENCES', 'CONFIDENCE', 'GAPS', 'RECOMMENDATION'],
-};
-
 export function structureRequirementTypes() {
   return [...new Set([...Object.keys(STRUCTURE_REQUIREMENTS), ...Object.keys(VISUAL_REQUIREMENTS)])];
 }
 
-/**
- * Lint one document against both the required sections and required visuals for
- * its type. Returns an array of violation strings (empty when satisfied or when
- * the type declares no requirements).
- */
+export function resolveTemplatePath(type, rootDir) {
+  const entry = getArtifactEntry(type, { rootDir });
+  if (entry?.template) return entry.template;
+  return `templates/docs/${type}.md`;
+}
+
 export function lintDocStructure(filePath, type) {
   const sectionChecks = (STRUCTURE_REQUIREMENTS[type] || []).map((section) => ({
     id: `${type}-section-${section}`,
@@ -72,11 +53,6 @@ export function lintDocStructure(filePath, type) {
   return validateArtifactPostconditions({ contract: { postconditions }, artifactPath: filePath });
 }
 
-/**
- * Lint one document against the visual requirements for its type. Returns an
- * array of violation strings (empty when satisfied, or when the type has no
- * declared visual requirements).
- */
 export function lintDocVisuals(filePath, type) {
   const postconditions = VISUAL_REQUIREMENTS[type];
   if (!postconditions) return [];

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;