@geraldmaron/construct 1.0.5 → 1.0.6

package/bin/construct

@@ -3994,18 +3994,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 +4081,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 +4205,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);

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.

package/commands/design/access.md

@@ -1,10 +1,10 @@
 <!--
-commands/design/access.md — Accessibility audit — WCAG 2.1 AA, keyboard, screen readers, contrast, motion
+commands/design/access.md (Accessibility audit) WCAG 2.1 AA, keyboard, screen readers, contrast, motion
 
-Accessibility audit — WCAG 2.1 AA, keyboard, screen readers, contrast, motion
+Accessibility audit: WCAG 2.1 AA, keyboard, screen readers, contrast, motion
 -->
 ---
-description: Accessibility audit — WCAG 2.1 AA, keyboard, screen readers, contrast, motion
+description: Accessibility audit: WCAG 2.1 AA, keyboard, screen readers, contrast, motion
 ---
 
 You are Construct. Audit: $ARGUMENTS

package/commands/design/flow.md

@@ -1,10 +1,10 @@
 <!--
-commands/design/flow.md — Map the user flow — entry to success, friction points, jobs-to-be-done
+commands/design/flow.md (Map the user flow) entry to success, friction points, jobs-to-be-done
 
-Map the user flow — entry to success, friction points, jobs-to-be-done
+Map the user flow: entry to success, friction points, jobs-to-be-done
 -->
 ---
-description: Map the user flow — entry to success, friction points, jobs-to-be-done
+description: Map the user flow: entry to success, friction points, jobs-to-be-done
 ---
 
 You are Construct. Map the user flow for: $ARGUMENTS

package/commands/design/ui.md

@@ -1,16 +1,16 @@
 <!--
-commands/design/ui.md — Design or review UI — visual hierarchy, states, interaction model, accessibility baseline
+commands/design/ui.md (Design or review UI) visual hierarchy, states, interaction model, accessibility baseline
 
-Design or review UI — visual hierarchy, states, interaction model, accessibility baseline
+Design or review UI: visual hierarchy, states, interaction model, accessibility baseline
 -->
 ---
-description: Design or review UI — visual hierarchy, states, interaction model, accessibility baseline
+description: Design or review UI: visual hierarchy, states, interaction model, accessibility baseline
 ---
 
 You are Construct. Design or review the UI for: $ARGUMENTS
 
 Every meaningful UI surface needs:
-- Clear hierarchy through scale contrast — not uniform emphasis
+- Clear hierarchy through scale contrast: not uniform emphasis
 - Every component state defined: empty, loading, error, success, edge cases
 - Hover, focus, and active states that feel designed
 - WCAG AA baseline: keyboard-navigable, 4.5:1 contrast, visible focus, ARIA labels

package/commands/measure/experiment.md

@@ -1,10 +1,10 @@
 <!--
-commands/measure/experiment.md — Design an experiment — hypothesis, test, evidence threshold, go/no-go decision
+commands/measure/experiment.md (Design an experiment) hypothesis, test, evidence threshold, go/no-go decision
 
-Design an experiment — hypothesis, test, evidence threshold, go/no-go decision
+Design an experiment: hypothesis, test, evidence threshold, go/no-go decision
 -->
 ---
-description: Design an experiment — hypothesis, test, evidence threshold, go/no-go decision
+description: Design an experiment: hypothesis, test, evidence threshold, go/no-go decision
 ---
 
 You are Construct. Design an experiment for: $ARGUMENTS
@@ -12,7 +12,7 @@ You are Construct. Design an experiment for: $ARGUMENTS
 Produce:
 - HYPOTHESIS: "We believe [X] will result in [Y] because [Z]."
 - KEY UNKNOWNS: a small set of questions (typically 3-7) whose answers most change the decision
-- EXPERIMENT: cheapest useful test per unknown — inputs, method, output artifact
+- EXPERIMENT: cheapest useful test per unknown: inputs, method, output artifact
 - EVIDENCE THRESHOLD: what result confirms or disconfirms? Be specific.
-- RECOMMENDATION: explore | prototype | build | kill — with rationale
+- RECOMMENDATION: explore | prototype | build | kill: with rationale
 - WHAT NOT TO LOCK IN YET: decisions that must not harden before evidence arrives

package/commands/measure/metrics.md

@@ -1,10 +1,10 @@
 <!--
-commands/measure/metrics.md — Define metrics — what to measure, baselines, success thresholds, instrumentation needed
+commands/measure/metrics.md (Define metrics) what to measure, baselines, success thresholds, instrumentation needed
 
-Define metrics — what to measure, baselines, success thresholds, instrumentation needed
+Define metrics: what to measure, baselines, success thresholds, instrumentation needed
 -->
 ---
-description: Define metrics — what to measure, baselines, success thresholds, instrumentation needed
+description: Define metrics: what to measure, baselines, success thresholds, instrumentation needed
 ---
 
 You are Construct. Define metrics for: $ARGUMENTS

package/commands/measure/results.md

@@ -1,17 +1,17 @@
 <!--
-commands/measure/results.md — Analyze results — interpret data, separate signal from noise, produce a recommendation
+commands/measure/results.md (Analyze results) interpret data, separate signal from noise, produce a recommendation
 
-Analyze results — interpret data, separate signal from noise, produce a recommendation
+Analyze results: interpret data, separate signal from noise, produce a recommendation
 -->
 ---
-description: Analyze results — interpret data, separate signal from noise, produce a recommendation
+description: Analyze results: interpret data, separate signal from noise, produce a recommendation
 ---
 
 You are Construct. Analyze: $ARGUMENTS
 
 For each finding:
 - FINDING: what the data shows (with specific numbers)
-- CONFIDENCE: high / medium / low — based on sample size and data quality
+- CONFIDENCE: high / medium / low: based on sample size and data quality
 - INFERENCE: what this means for the decision (clearly labeled as interpretation)
 - GAPS: what additional data would increase confidence
 

package/commands/plan/api.md

@@ -1,10 +1,10 @@
 <!--
-commands/plan/api.md — Design an API — contracts, endpoints, error model, data schema
+commands/plan/api.md (Design an API) contracts, endpoints, error model, data schema
 
-Design an API — contracts, endpoints, error model, data schema
+Design an API: contracts, endpoints, error model, data schema
 -->
 ---
-description: Design an API — contracts, endpoints, error model, data schema
+description: Design an API: contracts, endpoints, error model, data schema
 ---
 
 You are Construct. Design the API for: $ARGUMENTS

package/commands/plan/challenge.md

@@ -1,10 +1,10 @@
 <!--
-commands/plan/challenge.md — Challenge a plan — stress-test assumptions, surface failure modes and risks
+commands/plan/challenge.md (Challenge a plan) stress-test assumptions, surface failure modes and risks
 
-Challenge a plan — stress-test assumptions, surface failure modes and risks
+Challenge a plan: stress-test assumptions, surface failure modes and risks
 -->
 ---
-description: Challenge a plan — stress-test assumptions, surface failure modes and risks
+description: Challenge a plan: stress-test assumptions, surface failure modes and risks
 ---
 
 You are Construct. Challenge the following: $ARGUMENTS

package/commands/plan/decide.md

@@ -1,10 +1,10 @@
 <!--
-commands/plan/decide.md — Record a decision — context, options considered, consequences, what it locks in
+commands/plan/decide.md (Record a decision) context, options considered, consequences, what it locks in
 
-Record a decision — context, options considered, consequences, what it locks in
+Record a decision: context, options considered, consequences, what it locks in
 -->
 ---
-description: Record a decision — context, options considered, consequences, what it locks in
+description: Record a decision: context, options considered, consequences, what it locks in
 ---
 
 You are Construct. Document the decision about: $ARGUMENTS

package/commands/plan/feature.md

@@ -1,30 +1,30 @@
 <!--
-commands/plan/feature.md — Plan a feature and turn it into a tracker-linked implementation plan
+commands/plan/feature.md: Plan a feature and turn it into a tracker-linked implementation plan
 
 Produces a structured spec using the canonical Construct plan format, saves it
 to .cx/plans/ as a durable planning artifact linked to the active tracker slice.
 -->
 ---
-description: Plan a feature — produce a structured spec and link it to the active tracker-backed plan
+description: Plan a feature: produce a structured spec and link it to the active tracker-backed plan
 ---
 
 You are Construct. Plan the following: $ARGUMENTS
 
 Use the code-backed orchestration policy for routing/escalation decisions; this prompt only defines the plan artifact shape.
 
-## Step 1 — Scope
+## Step 1: Scope
 Produce:
 - **GOAL**: restate the objective in one sentence
 - **APPROACH**: chosen strategy and why (alternatives considered)
 - **RISKS**: top 3 risks and mitigations
 
-## Step 2 — Task breakdown
+## Step 2: Task breakdown
 
 Produce tasks in the canonical Construct plan format:
 
 ## Tasks
 
-### T1 — {Task title}
+### T1: {Task title}
 - **Owner**: {cx-specialist}
 - **Phase**: implement
 - **Files**: {comma-separated list of files this task will touch}
@@ -38,12 +38,12 @@ Produce tasks in the canonical Construct plan format:
 (repeat for each task)
 
 Rules:
-- Each task is atomic — one agent, one deliverable
+- Each task is atomic: one agent, one deliverable
 - Files lists must be disjoint across parallel tasks
 - Acceptance criteria are binary: pass or fail, no "it should be good"
 - Do not change must list every file outside scope that could be accidentally touched
 
-## Step 3 — Save and import
+## Step 3: Save and import
 1. Save this full plan to `.cx/plans/{slug}-plan.md`
 2. If the project uses Beads or another external tracker, include the issue id in the plan and keep the current `plan.md` aligned with it
 3. Declare file ownership explicitly so parallel work still follows the single-writer rule

package/commands/plan/requirements.md

@@ -1,10 +1,10 @@
 <!--
-commands/plan/requirements.md — Define requirements — what needs to be true for this to be done
+commands/plan/requirements.md (Define requirements) what needs to be true for this to be done
 
-Define requirements — what needs to be true for this to be done
+Define requirements: what needs to be true for this to be done
 -->
 ---
-description: Define requirements — what needs to be true for this to be done
+description: Define requirements: what needs to be true for this to be done
 ---
 
 You are Construct. Define requirements for: $ARGUMENTS

package/commands/remember/context.md

@@ -1,10 +1,10 @@
 <!--
-commands/remember/context.md — Save project context — update .cx/context.md so the next session picks up where this one left off
+commands/remember/context.md (Save project context) update .cx/context.md so the next session picks up where this one left off
 
-Save project context — update .cx/context.md so the next session picks up where this one left off
+Save project context: update .cx/context.md so the next session picks up where this one left off
 -->
 ---
-description: Save project context — update .cx/context.md so the next session picks up where this one left off
+description: Save project context: update .cx/context.md so the next session picks up where this one left off
 ---
 
 You are Construct. Save context for: $ARGUMENTS
@@ -12,10 +12,10 @@ You are Construct. Save context for: $ARGUMENTS
 Update `.cx/context.json` as canonical state and refresh `.cx/context.md` as the readable mirror:
 
 ## Active Work
-- [title] — [status: in-progress | blocked | in-review]
+- [title]: [status: in-progress | blocked | in-review]
 
 ## Recent Decisions
-- [date] [decision] — [rationale]
+- [date] [decision]: [rationale]
 
 ## Architecture Notes
 - [constraint or invariant future contributors need to know]

package/commands/remember/handoff.md

@@ -1,10 +1,10 @@
 <!--
-commands/remember/handoff.md — Write a handoff — transfer context so the next session or person can continue without loss
+commands/remember/handoff.md (Write a handoff) transfer context so the next session or person can continue without loss
 
-Write a handoff — transfer context so the next session or person can continue without loss
+Write a handoff: transfer context so the next session or person can continue without loss
 -->
 ---
-description: Write a handoff — transfer context so the next session or person can continue without loss
+description: Write a handoff: transfer context so the next session or person can continue without loss
 ---
 
 You are Construct. Write a handoff for: $ARGUMENTS

package/commands/remember/runbook.md

@@ -1,10 +1,10 @@
 <!--
-commands/remember/runbook.md — Write a runbook — step-by-step procedure for a recurring task or incident
+commands/remember/runbook.md (Write a runbook) step-by-step procedure for a recurring task or incident
 
-Write a runbook — step-by-step procedure for a recurring task or incident
+Write a runbook: step-by-step procedure for a recurring task or incident
 -->
 ---
-description: Write a runbook — step-by-step procedure for a recurring task or incident
+description: Write a runbook: step-by-step procedure for a recurring task or incident
 ---
 
 You are Construct. Write a runbook for: $ARGUMENTS