@geraldmaron/construct 1.0.5 → 1.0.7

package/bin/construct

@@ -292,7 +292,7 @@ async function cmdList() {
 async function cmdDoctor() {
   const args = process.argv.slice(3);
 
-  const DAEMON_SUBS = new Set(['status', 'watch', 'stop', 'logs', 'tick', 'report']);
+  const DAEMON_SUBS = new Set(['status', 'watch', 'stop', 'logs', 'tick', 'report', 'consistency']);
   if (args.length > 0 && DAEMON_SUBS.has(args[0])) {
     const { runCli } = await import('../lib/doctor/cli.mjs');
     const code = await runCli(args);
@@ -1053,6 +1053,59 @@ async function cmdVersion() {
   println(`construct v${pkg.version}`);
 }
 
+async function cmdMigrate(args) {
+  const dryRun = args.includes('--dry-run');
+  const pathArg = args.find((a) => a.startsWith('--path='))?.split('=')[1];
+  const fromArg = args.find((a) => a.startsWith('--from='))?.split('=')[1];
+  const { runMigrations, planMigrations, CURRENT_SCHEMA_VERSION } = await import('../lib/migrations/index.mjs');
+
+  const candidates = pathArg
+    ? [pathArg]
+    : [
+        path.join(ROOT_DIR, 'agents', 'registry.json'),
+        path.join(ROOT_DIR, 'agents', 'contracts.json'),
+        path.join(ROOT_DIR, 'agents', 'role-manifests.json'),
+        path.join(process.cwd(), '.cx', 'config.json'),
+      ];
+
+  let anyFailed = false;
+  for (const artifactPath of candidates) {
+    if (!fs.existsSync(artifactPath)) continue;
+    let from;
+    try {
+      const data = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+      from = typeof data?.version === 'number' ? data.version : Number(fromArg) || 0;
+    } catch {
+      println(`  ⚠  ${artifactPath}: parse error, skipping`);
+      continue;
+    }
+
+    const plan = planMigrations(from, CURRENT_SCHEMA_VERSION);
+    if (plan === null) {
+      println(`  ✗  ${artifactPath}: no migration path from v${from} to v${CURRENT_SCHEMA_VERSION}`);
+      anyFailed = true;
+      continue;
+    }
+    if (plan.length === 0) {
+      println(`  ✓  ${artifactPath}: already at v${CURRENT_SCHEMA_VERSION}`);
+      continue;
+    }
+
+    println(`  ${dryRun ? '·' : '→'}  ${artifactPath}: ${plan.length} step(s) (v${from} → v${CURRENT_SCHEMA_VERSION})`);
+    const result = await runMigrations({ artifactPath, fromVersion: from, dryRun });
+    for (const step of result.applied) {
+      println(`     v${step.from}→v${step.to}: ${step.summary}`);
+    }
+    if (!result.ok) {
+      println(`  ✗  ${result.error}`);
+      anyFailed = true;
+    }
+  }
+
+  if (dryRun) println(`\n(dry-run — no files were written)`);
+  if (anyFailed) process.exit(1);
+}
+
 async function cmdReview(args) {
   fs.mkdirSync(path.join(HOME, '.cx', 'performance-reviews'), { recursive: true });
   const sub = args[0];
@@ -1550,13 +1603,16 @@ function printActiveConfig() {
   println(`Persisted at: ${getUserEnvPath(HOME)} (${DEPLOYMENT_MODE_ENV_KEY})`);
 }
 
-function printIntakeHelp() {
-  println('Construct intake — inspect and process the R&D intake queue.');
+async function printIntakeHelp() {
+  const { getRebrand } = await import('../lib/profiles/rebrand.mjs');
+  const { intakeQueueLabel, signalNoun } = getRebrand(process.cwd());
+  println(`Construct intake — inspect and process the ${intakeQueueLabel}.`);
   println('');
   println('Usage:');
-  println('  construct intake list                List pending intake packets (ID, type, stage, owner, action).');
+  println(`  construct intake list                List pending ${signalNoun}s (ID, type, stage, owner, action).`);
   println('  construct intake show <id>           Show a single packet: triage, source, excerpt, related docs.');
-  println('  construct intake done <id> [--notes=…]    Mark a pending packet processed.');
+  println('  construct intake done <id> [--notes=…] [--output=<path>] [--no-output=<rejected|deferred|merged>]');
+  println('                                       Mark a pending packet processed. --output stamps intake_id + confidence into the artifact frontmatter (provenance).');
   println('  construct intake skip <id> [--reason=…]   Mark a pending packet skipped (preserves audit trail).');
   println('  construct intake reopen <id>         Move a processed or skipped packet back to pending.');
   println('  construct intake metrics               Show pipeline volume, velocity, and processing stats.');
@@ -1580,11 +1636,12 @@ function parseKvFlags(args, keys) {
   return out;
 }
 
-function formatIntakeTable(rows) {
+function formatIntakeTable(rows, { intakeQueueLabel, signalNoun } = { intakeQueueLabel: 'Intake queue', signalNoun: 'signal' }) {
   if (rows.length === 0) {
-    println('No pending intake packets.');
+    println(`No pending ${signalNoun}s.`);
     return;
   }
+  println(`${intakeQueueLabel} (${rows.length} pending):`);
   const headers = ['ID', 'Type', 'Stage', 'Owner', 'Action'];
   const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] || '').length)));
   const fmt = (cells) => cells.map((c, i) => String(c || '').padEnd(widths[i])).join('  ');
@@ -1597,12 +1654,14 @@ async function cmdIntake(args) {
   const sub = args[0];
 
   if (!sub || sub === '--help' || sub === '-h') {
-    printIntakeHelp();
+    await printIntakeHelp();
     return;
   }
 
   const { createIntakeQueue } = await import('../lib/intake/queue.mjs');
+  const { getRebrand } = await import('../lib/profiles/rebrand.mjs');
   const cwd = process.cwd();
+  const rebrand = getRebrand(cwd);
   const queue = createIntakeQueue(cwd, process.env);
 
   if (sub === 'list') {
@@ -1611,7 +1670,7 @@ async function cmdIntake(args) {
       const t = p.triage || {};
       return [p.id, t.intakeType || 'unknown', t.rdStage || 'unknown', t.primaryOwner || '—', t.recommendedAction || '—'];
     });
-    formatIntakeTable(rows);
+    formatIntakeTable(rows, rebrand);
     return;
   }
 
@@ -1619,8 +1678,9 @@ async function cmdIntake(args) {
   if (sub === 'show') {
     if (!id) { errorln('Usage: construct intake show <id>'); process.exit(1); }
     const entry = queue.read(id);
-    if (!entry) { errorln(`No intake packet with id: ${id}`); process.exit(1); }
+    if (!entry) { errorln(`No ${rebrand.signalNoun} with id: ${id}`); process.exit(1); }
     const t = entry.triage || {};
+    println(`${rebrand.signalNoun.charAt(0).toUpperCase() + rebrand.signalNoun.slice(1)} ${entry.id}`);
     println(`ID:        ${entry.id}`);
     println(`Status:    ${entry.status}`);
     println(`Source:    ${entry.intake?.sourcePath || '(none)'}`);
@@ -1712,11 +1772,59 @@ async function cmdIntake(args) {
   }
 
   if (sub === 'done') {
-    if (!id) { errorln('Usage: construct intake done <id> [--notes=…]'); process.exit(1); }
-    const flags = parseKvFlags(args.slice(2), ['notes']);
+    if (!id) {
+      errorln('Usage: construct intake done <id> [--notes=…] [--output=<path>] [--no-output=<rejected|deferred|merged>]');
+      process.exit(1);
+    }
+    const flags = parseKvFlags(args.slice(2), ['notes', 'output', 'no-output']);
+    const outputPath = flags.output || null;
+    const noOutputOutcome = flags['no-output'] || null;
+
+    if (outputPath && noOutputOutcome) {
+      errorln('--output and --no-output are mutually exclusive');
+      process.exit(1);
+    }
+    if (noOutputOutcome && !['rejected', 'deferred', 'merged'].includes(noOutputOutcome)) {
+      errorln(`--no-output value must be one of: rejected, deferred, merged (got "${noOutputOutcome}")`);
+      process.exit(1);
+    }
+
+    let stamped = null;
+    if (outputPath) {
+      const packet = queue.read(id);
+      if (!packet) {
+        errorln(`No intake packet found: ${id}`);
+        process.exit(1);
+      }
+      const triage = packet.triage || {};
+      try {
+        const { stampIntakeProvenance } = await import('../lib/intake/traceability.mjs');
+        const path = (await import('node:path')).default;
+        const absPath = path.isAbsolute(outputPath) ? outputPath : path.join(cwd, outputPath);
+        stamped = stampIntakeProvenance(absPath, {
+          intakeId: id,
+          confidence: triage.confidence,
+          rationale: triage.rationale,
+        });
+      } catch (err) {
+        errorln(err.message || 'intake stamping failed');
+        process.exit(1);
+      }
+    }
+
+    const notes = flags.notes
+      || (noOutputOutcome ? `intake_outcome: ${noOutputOutcome}` : '')
+      || (outputPath ? `output: ${outputPath}` : '');
+
     try {
-      const r = queue.markProcessed(id, { processedBy: 'construct-intake-cli', notes: flags.notes || '' });
-      info(`Marked ${r.id} processed.`);
+      const r = queue.markProcessed(id, { processedBy: 'construct-intake-cli', notes });
+      if (stamped) {
+        info(`Marked ${r.id} processed. Stamped ${outputPath} with intake_id=${id} (confidence=${stamped.intake_confidence ?? 'n/a'}).`);
+      } else if (noOutputOutcome) {
+        info(`Marked ${r.id} processed (intake_outcome: ${noOutputOutcome}).`);
+      } else {
+        info(`Marked ${r.id} processed.`);
+      }
     } catch (err) {
       errorln(err.message || 'mark processed failed');
       process.exit(1);
@@ -2741,27 +2849,55 @@ async function cmdSeedTraces(args) {
 async function cmdCleanup() {
   const force = restArgsCache.includes('--pressure-release');
   const quiet = restArgsCache.includes('--quiet');
-  const report = runPressureRelease({ env: process.env, force });
-
-  if (!quiet) {
-    const swap = report.swapUsage
-      ? `${(report.swapUsage.usedBytes / (1024 ** 3)).toFixed(1)} GiB used`
-      : 'swap unavailable';
-    println(`Pressure guard: ${report.pressureTriggered ? 'triggered' : 'standby'} · ${swap}`);
-    for (const entry of report.warnings ?? []) {
-      const grace = entry.graceMinutes ? `; will terminate after ${entry.graceMinutes}m if still matched` : '';
-      println(`Warning pid ${entry.pid} (${entry.reason})${grace}`);
+  const dryRun = restArgsCache.includes('--dry-run');
+  const pressureOnly = restArgsCache.includes('--pressure-only');
+  const diskOnly = restArgsCache.includes('--disk-only');
+
+  // Process pressure release: kill stale dev-agent processes.
+  if (!diskOnly) {
+    const report = runPressureRelease({ env: process.env, force });
+    if (!quiet) {
+      const swap = report.swapUsage
+        ? `${(report.swapUsage.usedBytes / (1024 ** 3)).toFixed(1)} GiB used`
+        : 'swap unavailable';
+      println(`Pressure guard: ${report.pressureTriggered ? 'triggered' : 'standby'} · ${swap}`);
+      for (const entry of report.warnings ?? []) {
+        const grace = entry.graceMinutes ? `; will terminate after ${entry.graceMinutes}m if still matched` : '';
+        println(`Warning pid ${entry.pid} (${entry.reason})${grace}`);
+      }
+      if (report.killed.length) {
+        for (const entry of report.killed) {
+          println(`Stopped pid ${entry.pid} (${entry.reason})`);
+        }
+      } else {
+        println('No stale dev-agent processes needed cleanup.');
+      }
     }
   }
 
-  if (!report.killed.length) {
-    if (!quiet) println('No stale dev-agent processes needed cleanup.');
-    return;
-  }
-
-  if (!quiet) {
-    for (const entry of report.killed) {
-      println(`Stopped pid ${entry.pid} (${entry.reason})`);
+  // Disk maintenance: rotate oversized logs, prune stale cache entries.
+  if (!pressureOnly) {
+    const { runFullCleanup, formatBytes } = await import('../lib/maintenance/cleanup.mjs');
+    const summary = runFullCleanup({ homeDir: HOME, env: process.env, dryRun });
+    if (!quiet) {
+      const verb = dryRun ? 'Would free' : 'Freed';
+      println(`Disk maintenance${dryRun ? ' (dry-run)' : ''}: ${verb} ${formatBytes(summary.freedBytes)} in ${summary.durationMs}ms`);
+      const log = summary.embedLog;
+      if (log?.truncated?.length) {
+        for (const t of log.truncated) println(`  truncated ${path.relative(HOME, t.path)} (was ${formatBytes(t.sizeWas)})`);
+      }
+      if (log?.removed?.length) {
+        for (const r of log.removed) println(`  removed   ${path.relative(HOME, r.path)} (${formatBytes(r.size)})`);
+      }
+      if (summary.jsonlLogs?.truncated?.length) {
+        for (const t of summary.jsonlLogs.truncated) println(`  truncated ${path.relative(HOME, t.path)} (was ${formatBytes(t.sizeWas)} → ${formatBytes(t.sizeNow)})`);
+      }
+      if (summary.cacheDir?.removed?.length) {
+        println(`  pruned    ${summary.cacheDir.removed.length} stale cache file(s)`);
+      }
+      for (const err of summary.errors ?? []) {
+        println(`  ! ${err.step}: ${err.error}`);
+      }
     }
   }
 }
@@ -2970,6 +3106,12 @@ async function cmdMemory(args) {
 async function cmdLintComments(args) {
   const fix = args.includes('--fix');
   const staged = args.includes('--staged');
+  // CLI invocation enforces block severity for artifact-prose lint (see
+  // lib/comment-lint.mjs#checkArtifactBanned). Operators may opt back into
+  // warn-only by exporting CONSTRUCT_ARTIFACT_LINT_MODE=warn explicitly.
+  if (!process.env.CONSTRUCT_ARTIFACT_LINT_MODE) {
+    process.env.CONSTRUCT_ARTIFACT_LINT_MODE = 'block';
+  }
   const { lintRepo: lint, lintFile, formatResults: fmt } = await import('../lib/comment-lint.mjs');
 
   let results;
@@ -3053,6 +3195,18 @@ async function cmdLintAgents() {
   process.exit(1);
 }
 
+async function cmdLintContracts() {
+  const { validateContractsFile } = await import('../lib/contracts/validate.mjs');
+  const result = validateContractsFile({ repoRoot: ROOT_DIR });
+  if (result.ok) {
+    console.log('agents/contracts.json: 0 errors');
+    return;
+  }
+  console.error(`agents/contracts.json: ${result.errors.length} error(s)`);
+  for (const err of result.errors) console.error(`  ${err}`);
+  process.exit(1);
+}
+
 async function cmdBackup(args) {
   const sub = args[0];
 
@@ -3426,6 +3580,7 @@ const handlers = new Map([
   ['evals', cmdEvals],
   ['cleanup', cmdCleanup],
   ['version', cmdVersion],
+  ['migrate', cmdMigrate],
   ['docs:update', cmdDocsUpdate],
   ['docs:check', cmdDocsCheck],
   ['docs:site', cmdDocsSite],
@@ -3440,6 +3595,7 @@ const handlers = new Map([
   ['provider', cmdProvider],
   ['lint:research', cmdLintResearch],
   ['lint:agents', cmdLintAgents],
+  ['lint:contracts', cmdLintContracts],
   ['audit', async (args) => {
     const sub = args[0];
     if (sub === 'skills') return runAuditSkillsCli(args.slice(1));
@@ -3994,18 +4150,85 @@ const handlers = new Map([
     }
     if (sub === 'set') {
       const id = args[1];
-      if (!id) { errorln('Usage: construct profile set <id>'); process.exit(1); }
+      if (!id) {
+        errorln('Usage: construct profile set <id> [--yes] [--dry-run]');
+        process.exit(1);
+      }
       const target = loadProfile(id);
       if (!target) {
         errorln(`Unknown profile: ${id}. Available: ${listProfiles().join(', ')}`);
         process.exit(1);
       }
+      const skipConfirm = args.includes('--yes') || args.includes('-y') || args.includes('--non-interactive');
+      const dryRun = args.includes('--dry-run');
+      const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+
       const { findProjectConfigPath, loadProjectConfig, writeProjectConfig, PROJECT_CONFIG_FILENAME } = await import('../lib/config/project-config.mjs');
-      const fsMod = await import('node:fs');
       const pathMod = await import('node:path');
       const found = findProjectConfigPath(process.cwd());
       const cfgPath = found || pathMod.join(process.cwd(), PROJECT_CONFIG_FILENAME);
-      const cfg = found ? (loadProjectConfig(process.cwd()) || { version: 1 }) : { version: 1 };
+      // loadProjectConfig returns a wrapper { path, raw, config, source, errors };
+      // operate on the raw user-authored object so the write call sees the
+      // version field that validateProjectConfig requires.
+      const loaded = found ? loadProjectConfig(process.cwd()) : null;
+      const cfg = loaded?.raw ? structuredClone(loaded.raw) : { version: 1 };
+      if (!cfg.version) cfg.version = 1;
+
+      const currentId = cfg.profile || 'rnd';
+      if (currentId === id) {
+        println(`Profile already set to ${id} (${target.displayName}). Nothing to do.`);
+        return;
+      }
+      const current = loadProfile(currentId) || { id: currentId, displayName: currentId, roles: [], intake: { types: [], stages: [] }, departments: [] };
+
+      // Render a structural diff so the operator sees what loop they are switching into.
+      const setDiff = (label, before, after) => {
+        const b = new Set(before || []);
+        const a = new Set(after || []);
+        const added = [...a].filter((x) => !b.has(x));
+        const removed = [...b].filter((x) => !a.has(x));
+        const unchanged = [...a].filter((x) => b.has(x));
+        println(`  ${label}:`);
+        if (added.length) println(`    + ${added.join(', ')}`);
+        if (removed.length) println(`    - ${removed.join(', ')}`);
+        if (!added.length && !removed.length) println(`    (no change, ${unchanged.length} entr${unchanged.length === 1 ? 'y' : 'ies'})`);
+      };
+
+      println('');
+      println(`About to switch active profile:`);
+      println(`  from:  ${currentId} (${current.displayName})`);
+      println(`  to:    ${id} (${target.displayName})`);
+      println('');
+      println(`Structural diff:`);
+      setDiff('roles', current.roles, target.roles);
+      setDiff('intake.types', current.intake?.types, target.intake?.types);
+      setDiff('intake.stages', current.intake?.stages, target.intake?.stages);
+      const cDept = (current.departments || []).map((d) => d.id);
+      const tDept = (target.departments || []).map((d) => d.id);
+      setDiff('departments', cDept, tDept);
+      println('');
+      println(`Files that will change:`);
+      println(`  ${pathMod.relative(process.cwd(), cfgPath)}  (profile field: ${currentId} -> ${id})`);
+      println('');
+      println(`The change only writes the profile field. No specialists are added or removed.`);
+      println(`Sync runs against the new profile on next \`construct sync\`.`);
+      println('');
+
+      if (dryRun) {
+        println(`[dry-run] No files were written.`);
+        return;
+      }
+      if (!skipConfirm && isTTY) {
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((res) => rl.question(`Switch profile to ${id}? (Y/n) `, (a) => res(a.trim().toLowerCase())));
+        rl.close();
+        if (answer && answer !== 'y' && answer !== 'yes') {
+          println('Aborted. No config was changed.');
+          return;
+        }
+      }
+
       cfg.profile = id;
       writeProjectConfig(cfgPath, cfg, { validate: true });
       process.stdout.write(`✓ profile set to ${id} (${target.displayName})\n`);
@@ -4014,36 +4237,111 @@ const handlers = new Map([
     if (sub === 'create') {
       const id = args[1];
       if (!id) {
-        errorln('Usage: construct profile create <id> [--display="..."] [--role=<id>...] [--department=<id>:<displayName>...]');
+        errorln('Usage: construct profile create <id> [--display="..."] [--role=<id>...] [--department=<id>:<displayName>...] [--yes]');
+        errorln('  Run with no flags for interactive mode; pass --yes to skip the confirmation prompt.');
+        process.exit(1);
+      }
+      if (!/^[a-z][a-z0-9-]{1,30}$/.test(id)) {
+        errorln(`Invalid id "${id}". Must match ^[a-z][a-z0-9-]{1,30}$.`);
         process.exit(1);
       }
+
       const displayArg = args.find((a) => a.startsWith('--display='));
-      const displayName = displayArg ? displayArg.split('=')[1] : id;
-      const seedRoles = args
+      const skipConfirm = args.includes('--yes') || args.includes('-y') || args.includes('--non-interactive');
+      const dryRun = args.includes('--dry-run');
+      const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+
+      let displayName = displayArg ? displayArg.split('=')[1] : null;
+      let seedRoles = args
         .filter((a) => a.startsWith('--role='))
         .map((a) => a.slice('--role='.length))
         .filter(Boolean);
-      const seedDepartments = args
+      let seedDepartments = args
         .filter((a) => a.startsWith('--department='))
         .map((a) => a.slice('--department='.length))
         .map((spec) => {
           const [deptId, deptDisplay] = spec.split(':');
           return { id: deptId, displayName: deptDisplay || deptId };
         });
+
+      // Interactive gather. Only prompt when stdin is a real terminal and the
+      // operator did not pass enough flags to scaffold without input. A
+      // non-TTY invocation with no flags falls through to an empty scaffold
+      // so scripts and CI can still create drafts non-interactively.
+      const needsInteractive = isTTY && !skipConfirm && (!displayName || (seedRoles.length === 0 && seedDepartments.length === 0));
+      if (needsInteractive) {
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q, def = '') => new Promise((res) => rl.question(`${q}${def ? ` [${def}]` : ''} `, (a) => res(a.trim() || def)));
+
+        println('');
+        println(`Scaffolding a new profile draft. Three questions, then a preview.`);
+        println(`Background: docs/concepts/persona-research.md and docs/concepts/profile-lifecycle.md`);
+        println('');
+        if (!displayName) displayName = await ask('Display name?', id);
+        if (seedDepartments.length === 0) {
+          const dInput = await ask('Departments (id:Name, id:Name, ...)?', '');
+          if (dInput) seedDepartments = dInput.split(',').map((s) => s.trim()).filter(Boolean).map((spec) => {
+            const [dId, dName] = spec.split(':').map((x) => x.trim());
+            return { id: dId, displayName: dName || dId };
+          });
+        }
+        if (seedRoles.length === 0) {
+          const rInput = await ask('Roles (role-id, role-id, ...)?', '');
+          if (rInput) seedRoles = rInput.split(',').map((s) => s.trim()).filter(Boolean);
+        }
+        rl.close();
+      }
+      if (!displayName) displayName = id;
+
+      const pathMod = await import('node:path');
+      const draftRoot = pathMod.join(process.cwd(), '.cx', 'profiles', `draft-${id}`);
+
+      println('');
+      println(`About to scaffold a draft profile:`);
+      println(`  id:           ${id}`);
+      println(`  displayName:  ${displayName}`);
+      println(`  departments:  ${seedDepartments.length}${seedDepartments.length ? ` (${seedDepartments.map((d) => d.id).join(', ')})` : ''}`);
+      println(`  roles:        ${seedRoles.length}${seedRoles.length ? ` (${seedRoles.join(', ')})` : ''}`);
+      println('');
+      println(`Files that will be written under ${pathMod.relative(process.cwd(), draftRoot)}/:`);
+      println(`  profile.json                       structural manifest`);
+      println(`  requirements.md                    research brief naming each cx-* specialist`);
+      for (const r of seedRoles) println(`  personas/${r}.md`.padEnd(40) + `  persona artifact (filled during discover)`);
+      for (const d of seedDepartments) println(`  departments/${d.id}.md`.padEnd(40) + `  department charter (filled during frame)`);
+      println('');
+      println(`Nothing else is touched. No config is changed, no active profile is switched.`);
+      println(`To activate this profile after promotion: construct profile set ${id}`);
+      println('');
+
+      if (dryRun) {
+        println(`[dry-run] No files were written.`);
+        return;
+      }
+      if (!skipConfirm && isTTY) {
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((res) => rl.question('Create draft? (Y/n) ', (a) => res(a.trim().toLowerCase())));
+        rl.close();
+        if (answer && answer !== 'y' && answer !== 'yes') {
+          println('Aborted. Nothing was written.');
+          return;
+        }
+      }
+
       const { createDraftProfile } = await import('../lib/profiles/lifecycle.mjs');
       try {
         const result = createDraftProfile({ cwd: process.cwd(), id, displayName, seedRoles, seedDepartments });
-        const pathMod = await import('node:path');
-        process.stdout.write(`✓ draft created for ${id}\n`);
-        process.stdout.write(`  brief:        ${pathMod.relative(process.cwd(), result.briefPath)}\n`);
-        process.stdout.write(`  draft:        ${pathMod.relative(process.cwd(), result.draftPath)}\n`);
-        if (result.personaPaths.length) process.stdout.write(`  personas:     ${result.personaPaths.length} scaffold(s) under personas/\n`);
-        if (result.departmentPaths.length) process.stdout.write(`  departments:  ${result.departmentPaths.length} charter(s) under departments/\n`);
-        process.stdout.write(`\nNext steps (in order, per docs/concepts/profile-lifecycle.md):\n`);
-        process.stdout.write(`  1. Discover: dispatch cx-ux-researcher to fill personas/<role>.md from interviews + primary sources.\n`);
-        process.stdout.write(`  2. Frame:    dispatch cx-product-manager to fill departments/<dept>.md charters and the intake taxonomy in profile.json.\n`);
-        process.stdout.write(`  3. Architect: dispatch cx-architect to reconcile role reuse vs new, and to populate departments[].\n`);
-        process.stdout.write(`  4. Validate: dispatch cx-evaluator to run persona-eval and classifier-eval against representative signals.\n`);
+        println('');
+        println(`✓ draft created at ${pathMod.relative(process.cwd(), result.dir)}`);
+        println('');
+        println(`Next steps (in order, per docs/concepts/profile-lifecycle.md):`);
+        println(`  1. Discover  (cx-ux-researcher): fill personas/<role>.md from interviews + primary sources.`);
+        println(`  2. Frame     (cx-product-manager): fill departments/<dept>.md charters and intake taxonomy.`);
+        println(`  3. Architect (cx-architect): reconcile role reuse vs new; populate departments[] in profile.json.`);
+        println(`  4. Validate  (cx-evaluator): run persona-eval and classifier-eval against representative signals.`);
+        println('');
+        println(`Inspect the brief:  open ${pathMod.relative(process.cwd(), result.briefPath)}`);
         return;
       } catch (err) {
         errorln(err.message);
@@ -4063,12 +4361,84 @@ const handlers = new Map([
     if (sub === 'archive') {
       const id = args[1];
       const reasonArg = args.find((a) => a.startsWith('--reason='));
-      const reason = reasonArg ? reasonArg.split('=')[1] : '';
-      if (!id) { errorln('Usage: construct profile archive <id> --reason="..."'); process.exit(1); }
+      let reason = reasonArg ? reasonArg.split('=')[1] : '';
+      if (!id) {
+        errorln('Usage: construct profile archive <id> --reason="..." [--yes] [--dry-run]');
+        process.exit(1);
+      }
+      const skipConfirm = args.includes('--yes') || args.includes('-y') || args.includes('--non-interactive');
+      const dryRun = args.includes('--dry-run');
+      const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+
+      const pathMod = await import('node:path');
+      const fsMod = await import('node:fs');
+      const target = loadProfile(id);
+      if (!target) {
+        errorln(`Unknown profile: ${id}. Curated catalog: ${listProfiles().join(', ')}`);
+        process.exit(1);
+      }
+      const fileURL = await import('node:url');
+      const moduleDir = pathMod.dirname(fileURL.fileURLToPath(import.meta.url));
+      const repoRoot = pathMod.resolve(moduleDir, '..');
+      const srcProfile = pathMod.join(repoRoot, 'profiles', `${id}.json`);
+      const tableRel = typeof target?.intake?.classificationTable === 'string' ? target.intake.classificationTable : null;
+      const srcTable = tableRel ? pathMod.join(repoRoot, tableRel) : null;
+      const dstDir = pathMod.join(repoRoot, 'archive', 'profiles', id);
+
+      // Gather reason interactively if missing. The lifecycle module already
+      // enforces a >= 8 char reason, but the operator should see why before
+      // the call fails.
+      if (!reason && isTTY && !skipConfirm) {
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        reason = await new Promise((res) => rl.question('Archive reason (>= 8 chars): ', (a) => res(a.trim())));
+        rl.close();
+      }
+      if (!reason || reason.trim().length < 8) {
+        errorln('A substantive --reason (>= 8 chars) is required. Archiving is permanent in repo history; the reason becomes the archive note.');
+        process.exit(1);
+      }
+
+      println('');
+      println(`About to archive curated profile:`);
+      println(`  id:           ${id}`);
+      println(`  displayName:  ${target.displayName || id}`);
+      println(`  reason:       ${reason}`);
+      println('');
+      println(`Files that will move:`);
+      println(`  ${pathMod.relative(process.cwd(), srcProfile)}`);
+      println(`    -> ${pathMod.relative(process.cwd(), pathMod.join(dstDir, `${id}.json`))}`);
+      if (srcTable && fsMod.existsSync(srcTable)) {
+        println(`  ${pathMod.relative(process.cwd(), srcTable)}`);
+        println(`    -> ${pathMod.relative(process.cwd(), pathMod.join(dstDir, pathMod.basename(srcTable)))}`);
+      }
+      println(`  ${pathMod.relative(process.cwd(), pathMod.join(dstDir, 'archive-note.md'))}  (new)`);
+      println('');
+      println(`What stays:`);
+      println(`  Observations under .cx/observations/ are not touched.`);
+      println(`  Outcomes under .cx/outcomes/ are not touched.`);
+      println(`  Any project still configured with profile=${id} will fall back to rnd on next load.`);
+      println('');
+
+      if (dryRun) {
+        println(`[dry-run] No files were moved.`);
+        return;
+      }
+      if (!skipConfirm && isTTY) {
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((res) => rl.question(`Archive ${id}? (y/N) `, (a) => res(a.trim().toLowerCase())));
+        rl.close();
+        if (answer !== 'y' && answer !== 'yes') {
+          println('Aborted. Nothing was archived.');
+          return;
+        }
+      }
+
       const { archiveProfile } = await import('../lib/profiles/lifecycle.mjs');
       try {
         const { archived } = archiveProfile({ id, reason });
-        process.stdout.write(`✓ archived ${id} to ${archived}\n`);
+        process.stdout.write(`✓ archived ${id} to ${pathMod.relative(process.cwd(), archived)}\n`);
         return;
       } catch (err) {
         errorln(err.message);
@@ -4117,6 +4487,27 @@ if (!handler) {
   process.exit(1);
 }
 
+// Self-maintenance on version change. Skipped for high-frequency hook calls
+// (the harness invokes `construct hook <name>` many times per session and
+// must stay fast). When the installed version differs from the stamp at
+// ~/.construct/.cleanup-stamp, we run a single bounded cleanup pass and
+// update the stamp. Subsequent invocations are a single file read.
+if (command !== 'hook') {
+  try {
+    const { maybeRunCleanupOnUpgrade, formatBytes } = await import('../lib/maintenance/cleanup.mjs');
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf8'));
+    const result = maybeRunCleanupOnUpgrade({ homeDir: HOME, env: process.env, currentVersion: pkg.version });
+    if (result.ran && result.summary?.freedBytes > 1024 * 1024) {
+      const previous = result.previousVersion ? ` from v${result.previousVersion}` : '';
+      process.stderr.write(`[construct] Maintenance after upgrade${previous} to v${pkg.version}: freed ${formatBytes(result.summary.freedBytes)}.\n`);
+    }
+  } catch (err) {
+    // Maintenance must never block the actual command. Surface the failure
+    // but continue. The next invocation will retry.
+    process.stderr.write(`[construct] startup maintenance skipped: ${err.message}\n`);
+  }
+}
+
 // First-invocation resource probe — skipped for hooks, setup, uninstall,
 // doctor, and once BOOTSTRAP_CHECKED=1 is cached in ~/.construct/config.env.
 // On TTY: if anything's missing, prints the status table and offers to run