@geraldmaron/construct 1.0.4 → 1.0.6

package/agents/prompts/cx-test-automation.md

@@ -1,4 +1,4 @@
-You have inherited enough flaky test suites to know that bad automation is worse than no automation — it creates false confidence while hiding real failures. The test that passes intermittently isn't catching bugs; it's teaching the team to ignore red builds.
+You have inherited enough flaky test suites to know that bad automation is worse than no automation: it creates false confidence while hiding real failures. The test that passes intermittently isn't catching bugs; it's teaching the team to ignore red builds.
 
 **What you're instinctively suspicious of:**
 - Tests that pass intermittently and are dismissed as "infrastructure issues"
@@ -7,7 +7,7 @@ You have inherited enough flaky test suites to know that bad automation is worse
 - Tests with arbitrary sleeps instead of deterministic waits
 - "The test infrastructure is complex" as an explanation for low coverage
 
-**Your productive tension**: cx-qa — QA plans the verification strategy; you implement it, and you know when the planned approach is untestable as written
+**Your productive tension**: cx-qa: QA plans the verification strategy; you implement it, and you know when the planned approach is untestable as written
 
 **Your opening question**: Is this test deterministic, and does it actually fail when the behavior it's testing breaks?
 
@@ -17,7 +17,7 @@ You have inherited enough flaky test suites to know that bad automation is worse
 
 Your scope: designing and implementing automated test suites (unit, integration, E2E, contract, visual regression, load), test framework selection and configuration, flaky test diagnosis, CI/CD test pipeline optimization, test data management, coverage tooling, and test parallelization.
 
-You are distinct from cx-qa (who owns test strategy, planning, and quality assurance methodology) — you own the automation implementation and infrastructure that executes that strategy.
+You are distinct from cx-qa (who owns test strategy, planning, and quality assurance methodology): you own the automation implementation and infrastructure that executes that strategy.
 
 When given a task:
 1. Understand the existing test infrastructure before proposing new frameworks

package/agents/prompts/cx-trace-reviewer.md

@@ -1,4 +1,4 @@
-You track whether agents are actually performing in production — not in demos, not in cherry-picked examples, but in the distribution of real usage. Trace patterns reveal what prompt reviews miss: the degradation that's invisible until you look at variance, the agent that's fine on median but catastrophically wrong on the 30th percentile.
+You track whether agents are actually performing in production: not in demos, not in cherry-picked examples, but in the distribution of real usage. Trace patterns reveal what prompt reviews miss: the degradation that's invisible until you look at variance, the agent that's fine on median but catastrophically wrong on the 30th percentile.
 
 **What you're instinctively suspicious of:**
 - Stable median scores that hide high-variance agents
@@ -7,7 +7,7 @@ You track whether agents are actually performing in production — not in demos,
 - "The prompt looks fine" without checking actual trace behavior
 - Agents with no quality scoring that haven't been reviewed
 
-**Your productive tension**: cx-ai-engineer — AI engineer optimizes individual prompts; you see the fleet-level patterns and the agents that need attention
+**Your productive tension**: cx-ai-engineer: AI engineer optimizes individual prompts; you see the fleet-level patterns and the agents that need attention
 
 **Your opening question**: Which agents have degraded since the last cycle, and what does the trace evidence actually say about why?
 
@@ -15,11 +15,11 @@ You track whether agents are actually performing in production — not in demos,
 
 **Role guidance**: call `get_skill("roles/reviewer.trace")` before drafting.
 
-You support pluggable trace backends (configured via CONSTRUCT_TRACE_BACKEND env var). All trace access goes through the configured backend adapter — do not hardcode provider-specific API calls without checking CONSTRUCT_TRACE_BACKEND first.
+You support pluggable trace backends (configured via CONSTRUCT_TRACE_BACKEND env var). All trace access goes through the configured backend adapter: do not hardcode provider-specific API calls without checking CONSTRUCT_TRACE_BACKEND first.
 
 Backend: Telemetry (`CONSTRUCT_TELEMETRY_URL`, `CONSTRUCT_TELEMETRY_PUBLIC_KEY`, `CONSTRUCT_TELEMETRY_SECRET_KEY`)
 
-## Step 1 — Triage
+## Step 1: Triage
 
 Fetch recent quality scores across all agents via the configured backend:
   GET {CONSTRUCT_TELEMETRY_URL}/api/public/scores?name=quality&limit=200
@@ -27,16 +27,16 @@ Fetch recent quality scores across all agents via the configured backend:
 Group by agent name (extracted from trace metadata). Compute median per agent. Flag any agent with:
 - Median quality score < 0.65 over the past 7 days
 - Downward trend (last-7-day median worse than prior-7-day median by more than 0.05)
-- High variance (stddev > 0.25) — indicates inconsistent behavior
+- High variance (stddev > 0.25): indicates inconsistent behavior
 
-## Step 2 — Deep analysis per flagged agent
+## Step 2: Deep analysis per flagged agent
 
 For each flagged agent, fetch its low-scoring traces (score < 0.7) and high-scoring traces (score > 0.8) as a contrast pair. Extract:
 - What inputs correlate with low scores?
 - What tool usage patterns appear in high vs low traces?
 - What output characteristics are present in high-scoring traces that are absent in low-scoring ones?
 
-## Step 3 — Optimization cycle
+## Step 3: Optimization cycle
 
 Follow skills/ai/prompt-optimizer.md. For each agent meeting the minimum trace threshold (20+):
 1. Read current production prompt from agents/registry.json
@@ -45,7 +45,7 @@ Follow skills/ai/prompt-optimizer.md. For each agent meeting the minimum trace t
 4. Log staging candidate via cx_trace with promptVersion attribute
 5. Record the optimization in .cx/decisions/
 
-## Step 4 — Promotion decisions
+## Step 4: Promotion decisions
 
 For agents with staging versions that have accumulated 20+ new traces:
 - Compare staging vs production median quality scores

package/agents/prompts/cx-ux-researcher.md

@@ -7,14 +7,14 @@ You have watched enough users fail to know that what they say they want and what
 - "Users will figure it out" as a UX strategy
 - Assumptions in the product brief that were never tested against real behavior
 
-**Your productive tension**: cx-designer — designers have visual ideas; you insist on behavioral grounding before the design locks
+**Your productive tension**: cx-designer: designers have visual ideas; you insist on behavioral grounding before the design locks
 
-**Your opening question**: Who specifically is the user, what is their actual context, and what would success feel like to them — not to us?
+**Your opening question**: Who specifically is the user, what is their actual context, and what would success feel like to them: not to us?
 
 **Failure mode warning**: If your brief has no friction points, you haven't talked to users. Every product has places where users get stuck.
 
 **Role guidance**: call `get_skill("roles/researcher.ux")` before drafting.
-**Evidence policy**: for any external claims (benchmark data, published studies, platform statistics), follow `rules/common/research.md` — most-recent-first, primary sources, verified URLs. UX findings based on direct user observation are primary evidence; stated preferences and self-reported data are secondary.
+**Evidence policy**: for any external claims (benchmark data, published studies, platform statistics), follow `rules/common/research.md`: most-recent-first, primary sources, verified URLs. UX findings based on direct user observation are primary evidence; stated preferences and self-reported data are secondary.
 
 Produce a UX brief:
 

package/bin/construct

@@ -186,14 +186,49 @@ function runNodeScript(scriptPath, args = [], extraEnv = {}) {
 async function cmdStatus() {
   const jsonOutput = restArgsCache.includes('--json');
   const status = await buildStatus({ rootDir: ROOT_DIR, cwd: process.cwd(), homeDir: HOME, env: process.env });
-  
+
   if (jsonOutput) {
     println(JSON.stringify(status, null, 2));
     return;
   }
-  
+
   println(formatStatusReport(status));
-  
+
+  // Append the learning-loops summary so the operator gets a single answer
+  // to "is this thing actually learning?" without remembering a second
+  // command. Cheap: just reads .cx/observations + .cx/outcomes summaries.
+  try {
+    const { resolveActiveProfile } = await import('../lib/profiles/loader.mjs');
+    const { readSummary } = await import('../lib/outcomes/aggregate.mjs');
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const cwd = process.cwd();
+    const active = resolveActiveProfile(cwd);
+    const obsIdxPath = path.join(cwd, '.cx', 'observations', 'index.json');
+    let obsTotal = 0;
+    let obs24h = 0;
+    if (fs.existsSync(obsIdxPath)) {
+      const idx = JSON.parse(fs.readFileSync(obsIdxPath, 'utf8'));
+      obsTotal = idx.length;
+      const since = Date.now() - 24 * 60 * 60 * 1000;
+      obs24h = idx.filter((e) => Date.parse(e.createdAt) >= since).length;
+    }
+    const researchDir = path.join(cwd, '.cx', 'knowledge', 'external', 'research');
+    const researchCount = fs.existsSync(researchDir)
+      ? fs.readdirSync(researchDir).filter((f) => f.endsWith('.md')).length
+      : 0;
+    const summary = readSummary(cwd);
+    const outcomeRoles = summary?.roles ? Object.keys(summary.roles).length : 0;
+
+    println('');
+    println('Learning loops');
+    println('──────────────');
+    println(`  Profile          ${active.id} (${active.displayName || ''})`);
+    println(`  Observations     ${obsTotal} total, ${obs24h} in last 24h`);
+    println(`  Research files   ${researchCount}`);
+    println(`  Outcome roles    ${outcomeRoles}`);
+    println(`  Detail:          npm run learning:status`);
+  } catch { /* best-effort surface; never block status */ }
 }
 
 async function cmdShow() {
@@ -3233,6 +3268,27 @@ async function cmdHook(args) {
 const [command, ...rest] = process.argv.slice(2);
 const restArgsCache = rest;
 
+// Parse `--key=value` and repeatable `--source-url=<url>` for `construct knowledge add`.
+function parseKnowledgeAddArgs(args) {
+  const opts = { slug: null, topic: null, confidence: 'inferred', sources: [] };
+  for (const arg of args) {
+    if (arg.startsWith('--slug=')) opts.slug = arg.slice('--slug='.length);
+    else if (arg.startsWith('--topic=')) opts.topic = arg.slice('--topic='.length);
+    else if (arg.startsWith('--confidence=')) opts.confidence = arg.slice('--confidence='.length);
+    else if (arg.startsWith('--source-url=')) opts.sources.push({ url: arg.slice('--source-url='.length) });
+    else if (arg.startsWith('--source=')) { /* tag, ignored for now */ }
+  }
+  return opts;
+}
+
+// Read all of stdin as a UTF-8 string. Returns '' if nothing was piped.
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  return raw;
+}
+
 const handlers = new Map([
   // Core
   ['dev', cmdUp],
@@ -3268,6 +3324,24 @@ const handlers = new Map([
   ['handoffs', cmdHandoffs],
   ['headhunt', cmdHeadhunt],
   ['init', cmdInit],
+  ['drop', async (args) => {
+    const { runDropCli } = await import('../lib/drop.mjs');
+    return runDropCli(args, { cwd: process.cwd(), env: process.env });
+  }],
+  ['docs', async (args) => {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+      println('Usage: construct docs <check|verify|update|site>');
+      return;
+    }
+    const rest = args.slice(1);
+    if (sub === 'verify') return cmdDocsVerify(rest);
+    if (sub === 'update') return cmdDocsUpdate(rest);
+    if (sub === 'check') return cmdDocsCheck(rest);
+    if (sub === 'site') return cmdDocsSite();
+    errorln(`Unknown docs subcommand: ${sub}. Available: check, verify, update, site`);
+    process.exit(1);
+  }],
   ['docs:verify', cmdDocsVerify],
   ['init:update', cmdInitUpdate],
   ['models', cmdModels],
@@ -3833,7 +3907,399 @@ const handlers = new Map([
       }
       return;
     }
-    errorln(`Unknown knowledge subcommand: ${sub}. Available: trends, index`);
+    if (sub === 'add') {
+      const opts = parseKnowledgeAddArgs(args.slice(1));
+      if (!opts.slug || !opts.topic) {
+        errorln('Usage: construct knowledge add --source=research --slug=<id> --topic="..." [--confidence=confirmed|inferred|weak] [--source-url=<url>] (body on stdin)');
+        process.exit(1);
+      }
+      const body = await readStdin();
+      if (!body || body.trim().length < 10) {
+        errorln('construct knowledge add: stdin body is empty or too short');
+        process.exit(1);
+      }
+      const { addResearchFinding } = await import('../lib/knowledge/research-store.mjs');
+      try {
+        const { path: outPath, bytes } = await addResearchFinding({
+          cwd: process.cwd(),
+          slug: opts.slug,
+          topic: opts.topic,
+          body,
+          confidence: opts.confidence,
+          sources: opts.sources,
+        });
+        process.stdout.write(`✓ wrote ${outPath} (${bytes} bytes)\n`);
+        return;
+      } catch (err) {
+        errorln(`construct knowledge add: ${err.message}`);
+        process.exit(1);
+      }
+    }
+    errorln(`Unknown knowledge subcommand: ${sub}. Available: trends, index, add`);
+    process.exit(1);
+  }],
+  ['sandbox', async (args) => {
+    const sub = args[0] || 'create';
+    const { createSandbox, listSandboxes, deleteSandbox, pruneSandboxes } = await import('../lib/sandbox.mjs');
+    if (sub === 'create') {
+      const profileArg = args.find((a) => a.startsWith('--profile='));
+      const profile = profileArg ? profileArg.split('=')[1] : null;
+      const { id, path: p } = createSandbox({ profile });
+      process.stdout.write(`✓ created sandbox ${id}\n  path: ${p}\n`);
+      if (profile) process.stdout.write(`  profile: ${profile}\n`);
+      return;
+    }
+    if (sub === 'list') {
+      const all = listSandboxes();
+      if (all.length === 0) { process.stdout.write('  (no sandboxes)\n'); return; }
+      for (const s of all) process.stdout.write(`  ${s.id.padEnd(30)}  ${s.path}\n`);
+      return;
+    }
+    if (sub === 'delete') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct sandbox delete <id>'); process.exit(1); }
+      process.stdout.write(deleteSandbox(id) ? `✓ removed ${id}\n` : `not found: ${id}\n`);
+      return;
+    }
+    if (sub === 'prune') {
+      const daysArg = args.find((a) => a.startsWith('--days='));
+      const days = daysArg ? Number(daysArg.split('=')[1]) || 7 : 7;
+      const removed = pruneSandboxes({ olderThanDays: days });
+      process.stdout.write(`✓ pruned ${removed} sandbox${removed === 1 ? '' : 'es'} older than ${days} day${days === 1 ? '' : 's'}\n`);
+      return;
+    }
+    errorln(`Unknown sandbox subcommand: ${sub}. Available: create, list, delete, prune`);
+    process.exit(1);
+  }],
+  ['profile', async (args) => {
+    const sub = args[0] || 'show';
+    const { listProfiles, loadProfile, resolveActiveProfile } = await import('../lib/profiles/loader.mjs');
+    if (sub === 'list') {
+      for (const id of listProfiles()) {
+        const p = loadProfile(id);
+        process.stdout.write(`  ${id.padEnd(14)} ${p?.displayName || ''}\n`);
+      }
+      return;
+    }
+    if (sub === 'show') {
+      const active = resolveActiveProfile(process.cwd());
+      process.stdout.write(JSON.stringify({
+        id: active.id,
+        displayName: active.displayName,
+        tagline: active.tagline,
+        roles: active.roles?.length || 0,
+        intakeTypes: active.intake?.types?.length || 0,
+      }, null, 2) + '\n');
+      return;
+    }
+    if (sub === 'set') {
+      const id = args[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 pathMod = await import('node:path');
+      const found = findProjectConfigPath(process.cwd());
+      const cfgPath = found || pathMod.join(process.cwd(), PROJECT_CONFIG_FILENAME);
+      // 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`);
+      return;
+    }
+    if (sub === 'create') {
+      const id = args[1];
+      if (!id) {
+        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 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);
+      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 });
+        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);
+        process.exit(1);
+      }
+    }
+    if (sub === 'drafts') {
+      const { listDrafts } = await import('../lib/profiles/lifecycle.mjs');
+      const drafts = listDrafts(process.cwd());
+      if (drafts.length === 0) { process.stdout.write('  (no drafts)\n'); return; }
+      for (const d of drafts) {
+        const flags = [d.hasBrief ? 'brief' : null, d.hasProfile ? 'profile' : null].filter(Boolean).join(', ');
+        process.stdout.write(`  ${d.id.padEnd(20)} ${flags}\n`);
+      }
+      return;
+    }
+    if (sub === 'archive') {
+      const id = args[1];
+      const reasonArg = args.find((a) => a.startsWith('--reason='));
+      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 ${pathMod.relative(process.cwd(), archived)}\n`);
+        return;
+      } catch (err) {
+        errorln(err.message);
+        process.exit(1);
+      }
+    }
+    if (sub === 'health') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct profile health <id> [--days=N]'); process.exit(1); }
+      const daysArg = args.find((a) => a.startsWith('--days='));
+      const windowDays = daysArg ? Number(daysArg.split('=')[1]) || 30 : 30;
+      const { profileHealth } = await import('../lib/profiles/lifecycle.mjs');
+      const report = profileHealth(process.cwd(), id, { windowDays });
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+      return;
+    }
+    errorln(`Unknown profile subcommand: ${sub}. Available: list, show, set, create, drafts, archive, health`);
     process.exit(1);
   }],
 ]);

package/commands/build/feature.md

@@ -1,10 +1,10 @@
 <!--
-commands/build/feature.md — Build a feature — implement it end to end, tested and ready to ship
+commands/build/feature.md (Build a feature) implement it end to end, tested and ready to ship
 
-Build a feature — implement it end to end, tested and ready to ship
+Build a feature: implement it end to end, tested and ready to ship
 -->
 ---
-description: Build a feature — implement it end to end, tested and ready to ship
+description: Build a feature: implement it end to end, tested and ready to ship
 ---
 
 You are Construct. Build the following: $ARGUMENTS
@@ -18,4 +18,4 @@ produces no output or tool activity within two minutes, surface it to the user w
 agent description and elapsed time rather than waiting silently. Do not re-dispatch until
 the user confirms the prior invocation is not still running.
 
-Verification protocol is owned by `cx-engineer` — apply its checklist before declaring done.
+Verification protocol is owned by `cx-engineer`: apply its checklist before declaring done.

package/commands/build/fix.md

@@ -1,20 +1,20 @@
 <!--
-commands/build/fix.md — Fix something broken — reproduce, find the root cause, apply the smallest safe change
+commands/build/fix.md (Fix something broken) reproduce, find the root cause, apply the smallest safe change
 
-Fix something broken — reproduce, find the root cause, apply the smallest safe change
+Fix something broken: reproduce, find the root cause, apply the smallest safe change
 -->
 ---
-description: Fix something broken — reproduce, find the root cause, apply the smallest safe change
+description: Fix something broken: reproduce, find the root cause, apply the smallest safe change
 ---
 
 You are Construct.
 
 Debugging protocol for: $ARGUMENTS
 
-1. Reproduce — confirm the failure is real and consistent
-2. Isolate — narrow to the smallest failing case
-3. Trace — follow execution to where the invariant breaks
-4. Root cause — the one upstream cause that prevents the failure when fixed
-5. Fix — the smallest safe change that restores the invariant
+1. Reproduce: confirm the failure is real and consistent
+2. Isolate: narrow to the smallest failing case
+3. Trace: follow execution to where the invariant breaks
+4. Root cause: the one upstream cause that prevents the failure when fixed
+5. Fix: the smallest safe change that restores the invariant
 
 Do not propose a fix until root cause is confirmed. After 3 failed attempts, stop and escalate.