@geraldmaron/construct 1.0.4 → 1.0.6

package/lib/outcomes/record.mjs

@@ -0,0 +1,115 @@
+/**
+ * lib/outcomes/record.mjs — Specialist outcome recorder.
+ *
+ * Records the result of every dispatched specialist into
+ * `.cx/outcomes/<role>.jsonl`. The aggregator (lib/outcomes/aggregate.mjs)
+ * reads these files to produce per-role rolling success rates, which the
+ * classifier consumes as a soft tiebreaker.
+ *
+ * Schema (one JSONL line per outcome):
+ *   { ts, role, intakeId, profile, success, escalated, durationMs, notes,
+ *     source: 'agent-tracker' | 'feedback' | 'manual' }
+ *
+ * Files rotate at 10k lines per role to keep disk bounded. The rotated file
+ * is named `<role>.<yyyymm>.jsonl`. Current is always `<role>.jsonl`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { withFileLockSync } from '../storage/file-lock.mjs';
+
+const ROTATE_AT = 10_000;
+const MAX_NOTES = 500;
+
+function safeRole(role) {
+  return String(role || 'unknown').replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 60) || 'unknown';
+}
+
+function outcomesDir(cwd) {
+  return path.join(cwd, '.cx', 'outcomes');
+}
+
+function activeFile(cwd, role) {
+  return path.join(outcomesDir(cwd), `${safeRole(role)}.jsonl`);
+}
+
+function rotatedFile(cwd, role) {
+  const stamp = new Date().toISOString().slice(0, 7).replace('-', ''); // yyyymm
+  return path.join(outcomesDir(cwd), `${safeRole(role)}.${stamp}.jsonl`);
+}
+
+function countLines(file) {
+  try {
+    const buf = fs.readFileSync(file);
+    let n = 0;
+    for (let i = 0; i < buf.length; i++) if (buf[i] === 0x0a) n++;
+    return n;
+  } catch { return 0; }
+}
+
+/**
+ * Record a specialist outcome. Best-effort: any IO failure is swallowed and
+ * the caller proceeds. Outcomes are telemetry, never on the critical path.
+ *
+ * @param {string} cwd - project root
+ * @param {object} payload
+ * @param {string} payload.role - specialist id (cx-engineer → 'engineer')
+ * @param {string} [payload.intakeId]
+ * @param {string} [payload.profile] - active profile id
+ * @param {boolean} payload.success
+ * @param {boolean} [payload.escalated]
+ * @param {number} [payload.durationMs]
+ * @param {string} [payload.notes]
+ * @param {string} [payload.source='manual']
+ * @returns {string|null} path to the file written, or null on failure
+ */
+export function recordOutcome(cwd, payload) {
+  if (!cwd || !payload || typeof payload.success !== 'boolean') return null;
+  try {
+    fs.mkdirSync(outcomesDir(cwd), { recursive: true });
+    const file = activeFile(cwd, payload.role);
+
+    if (countLines(file) >= ROTATE_AT) {
+      try { fs.renameSync(file, rotatedFile(cwd, payload.role)); } catch { /* race */ }
+    }
+
+    const entry = {
+      ts: new Date().toISOString(),
+      role: safeRole(payload.role),
+      intakeId: payload.intakeId || null,
+      profile: payload.profile || null,
+      success: !!payload.success,
+      escalated: !!payload.escalated,
+      durationMs: Number.isFinite(payload.durationMs) ? payload.durationMs : null,
+      notes: payload.notes ? String(payload.notes).slice(0, MAX_NOTES) : null,
+      source: payload.source || 'manual',
+    };
+
+    withFileLockSync(file, () => {
+      fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+    });
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read every outcome line for a role across active + rotated files.
+ * Returns oldest-first.
+ */
+export function listOutcomes(cwd, role) {
+  const dir = outcomesDir(cwd);
+  if (!fs.existsSync(dir)) return [];
+  const safe = safeRole(role);
+  const files = fs.readdirSync(dir).filter((f) => f.startsWith(`${safe}.`) && f.endsWith('.jsonl'));
+  const out = [];
+  for (const f of files.sort()) {
+    let raw = '';
+    try { raw = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+    }
+  }
+  return out;
+}

package/lib/parity.mjs

@@ -151,15 +151,12 @@ function checkCodex(registry, { homeDir = os.homedir() } = {}) {
 }
 
 function checkCopilot(registry, { homeDir = os.homedir() } = {}) {
-  const prefix = registry.prefix || 'cx';
-  const entries = [
-    ...(registry.personas || []).map((p) => ({ ...p, isPersona: true })),
-    ...(registry.agents || []).map((a) => ({ ...a, isPersona: false })),
-  ];
-  const expected = entries
-    .filter((entry) => !entry.internal)
-    .filter((entry) => !Array.isArray(entry.platforms) || entry.platforms.includes('copilot'))
-    .map((entry) => adapterName(entry, prefix));
+  // Use the same helper as Claude/OpenCode/Codex so all surfaces apply the
+  // platform-filter rules identically. The previous implementation dropped
+  // entries with internal:true, which produced false drift because the sync
+  // script writes every specialist to ~/.github/prompts regardless of the
+  // internal flag.
+  const expected = entriesForSurface(registry, 'copilot');
   return checkFileSurface({
     surface: 'copilot',
     kind: 'prompts',

package/lib/profiles/lifecycle.mjs

@@ -0,0 +1,388 @@
+/**
+ * lib/profiles/lifecycle.mjs — Profile lifecycle operations.
+ *
+ * A profile is a curated description of an org's work loop, intake taxonomy,
+ * role set, and rebrand language. Creating one is a research task, not a
+ * code task. This module enforces that by producing a draft + a requirements
+ * brief that names which existing Construct specialists are expected to
+ * complete each section. Operators dispatch those specialists, collect the
+ * answers, then promote the draft.
+ *
+ * Lifecycle stages:
+ *   draft     - in `.cx/profiles/draft-<id>/` with requirements.md + profile.json
+ *   active    - in `profiles/<id>.json` (curated) or `.cx/profile.json` (custom)
+ *   archived  - in `archive/profiles/<id>/` with the final state and an
+ *               archive-note.md explaining why it was retired
+ *
+ * Health: per-profile observation and outcome counts pulled from the existing
+ * stores, so profile health travels alongside the rest of the learning loops.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { listProfiles, loadProfile } from './loader.mjs';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
+
+function draftDir(cwd, id) {
+  return path.join(cwd, '.cx', 'profiles', `draft-${id}`);
+}
+
+function archiveDir(cwd, id) {
+  return path.join(cwd, 'archive', 'profiles', id);
+}
+
+const REQUIREMENTS_BRIEF = (id, displayName) => `# Profile requirements: ${displayName} (${id})
+
+This brief is a discovery and design contract for a new Construct profile. Methodology lives in \`docs/concepts/persona-research.md\` and lifecycle in \`docs/concepts/profile-lifecycle.md\`. Treat each section as a task to dispatch to the named specialist. A draft profile is not ready to promote until every section has evidence backing it. The aim is research-grounded, not opinion-grounded.
+
+Specialists used here are the existing Construct cx-* personas (already in the registry). They are dispatched the standard way; this doc just names which questions each one owns.
+
+This draft scaffolding produces:
+- \`profile.json\` — the structural definition (departments, roles, intake)
+- \`requirements.md\` — this brief
+- \`personas/<role>.md\` — one persona artifact per role (filled during the discover phase)
+- \`departments/<dept>.md\` — one charter doc per department (filled during the frame phase)
+
+The persona and department files start as templates. Filling them from evidence is the actual work; the JSON is just a manifest.
+
+## 1. Discovery (cx-ux-researcher)
+
+Goal: characterize the people, the work, and the outputs of this org type.
+
+- Who are the typical roles in this org? Name 4 to 8 with one-line responsibilities.
+- What is the dominant work loop? Describe in 5 to 8 stages.
+- What are the recurring signals that enter the loop (briefs, bug reports, customer messages, etc.)?
+- What are the canonical output artifacts (campaigns, runbooks, papers, etc.)?
+- Evidence: cite at least 2 primary sources (interviews, docs, postmortems, public job-spec language).
+
+## 2. Framing (cx-product-manager)
+
+Goal: turn discovery into an intake taxonomy and a stage sequence.
+
+- Propose intake types (max 24). Each must be: distinct, observable, and routable to a primary owner.
+- Propose stages (max 12). Order matters; each stage must answer "what changed?" not just "what happened next?".
+- For each intake type, name the primary owner role and the recommended chain (max 3 hops).
+- For each stage, name the dominant artifact produced.
+- Acceptance: a representative real signal classifies into a single intake type with confidence > 0.6.
+
+## 3. Architecture (cx-architect)
+
+Goal: define the role set and how it interlocks with the curated cx-* registry.
+
+- List role ids the profile will reference (max 80, grouped into max 12 departments with max 20 roles per department). For each, indicate one of:
+  reuse-existing (name the cx-* agent), create-new (specify scope), or compose-overlay (which base role + which flavor).
+- Identify cross-role handoffs. Where can ambiguity stall the loop? Name the orchestrator role.
+- Validate against the per-role cap (max 6 flavors per role per profile).
+- Acceptance: every declared role either exists in agents/registry.json or has a written scope statement.
+
+## 4. Validation (cx-evaluator)
+
+Goal: prove the draft works on real signals before promotion.
+
+- Run \`construct profile classify --draft=${id} --fixture=<path>\` against at least 5 representative signals.
+- Score: precision (right intake type), recall (no false unknowns), routing-confidence (median).
+- Acceptance: precision >= 0.7, recall >= 0.7, no \`unknown\` for the canonical signals.
+
+## 5. Promotion (operator decision)
+
+Goal: move the draft into the active catalog.
+
+- Curated path: hand-edit \`profiles/${id}.json\` from this draft, open a PR, run \`npm run lint:profiles\`.
+- Custom path: copy the draft profile.json to \`<project>/.cx/profile.json\` with \`"custom": true\`; \`construct profile set\` for switching between curated.
+- Either path requires the validation acceptance criteria above to be met.
+
+## 6. Health monitoring (cx-evaluator + cx-trace-reviewer)
+
+Goal: keep the profile honest after it ships.
+
+- \`construct profile health ${id}\` reports observation counts, per-role outcome rates, classification confidence over a window.
+- Any role with success-rate < 0.5 across 10+ runs triggers a review: is the role wrong, the prompt wrong, or the routing wrong?
+- Health data is the input for future profile revisions; never edit a profile without a health report first.
+
+## 7. Archive (cx-docs-keeper + operator)
+
+Goal: retire a profile cleanly without losing the learning.
+
+- \`construct profile archive ${id}\` moves the profile JSON and the intake table reference into \`archive/profiles/${id}/\`, including the final health report as evidence.
+- Observations and outcomes already recorded under this profile stay in place; they are durable.
+- An archive-note.md explains why it was retired (superseded by, deprecated for, merged into).
+`;
+
+const DRAFT_PROFILE_TEMPLATE = (id, displayName) => ({
+  $schema: '../schemas/profile.schema.json',
+  id,
+  displayName: displayName || id,
+  tagline: 'Draft. Fill in via the requirements brief.',
+  extends: null,
+  custom: true,
+  roles: [],
+  departments: [],
+  intake: {
+    types: [],
+    stages: [],
+    classificationTable: null,
+  },
+  docTemplates: [],
+  hooks: {
+    sessionReflect: 'on',
+    sessionOptimize: 'on',
+  },
+  defaultSkills: [],
+  rebrand: {
+    intakeQueueLabel: 'Intake',
+    signalNoun: 'signal',
+  },
+});
+
+function personaTemplate(displayName) {
+  return `# ${displayName}
+
+> Persona research artifact. Methodology: \`docs/concepts/persona-research.md\`. Fill from evidence; opinion is rejected at review.
+
+## Goals
+- <What does success look like for this role?>
+
+## Frustrations
+- <What slows them down?>
+
+## Decision rights
+- Decides: <list>
+- Escalates: <list>
+
+## Handoffs
+- Hands off to: <role> when <condition>
+- Receives from: <role> when <condition>
+
+## Output contract
+- Format: <markdown, diff, JSON>
+- Depth: <one-paragraph, two-page, etc.>
+- Citations: <required | encouraged | none>
+
+## Failure modes
+- <Common ways this persona goes wrong>
+
+## Evidence
+- <Primary source 1>
+- <Primary source 2>
+`;
+}
+
+function departmentTemplate(id, displayName) {
+  return `# ${displayName} (${id})
+
+> Department charter. One paragraph: what this department owns, what it does not own, who it hands off to. Frame from organizational-design research (\`docs/concepts/persona-research.md\` § departmental structure).
+
+## Charter
+
+<One paragraph mission statement. Be specific about boundaries.>
+
+## Roles in this department
+
+- <role-id> — see \`personas/<role>.md\`
+
+## Handoffs
+
+- To <department>: <condition>
+- From <department>: <condition>
+
+## Evidence
+
+- <Interview, doc, public job spec>
+`;
+}
+
+/**
+ * Scaffold a draft profile under .cx/profiles/draft-<id>/. Returns the paths
+ * to the requirements brief and the draft profile JSON.
+ */
+/**
+ * Scaffold a draft profile + its persona and department research artifacts.
+ *
+ * @param {object} args
+ * @param {string} args.cwd
+ * @param {string} args.id
+ * @param {string} [args.displayName]
+ * @param {string[]} [args.seedRoles] - role ids to scaffold persona files for
+ * @param {Array<{id:string,displayName:string}>} [args.seedDepartments] - departments to scaffold charters for
+ */
+export function createDraftProfile({ cwd, id, displayName, seedRoles = [], seedDepartments = [] }) {
+  if (!cwd || !id) throw new Error('createDraftProfile: cwd and id are required');
+  if (!/^[a-z][a-z0-9-]{1,30}$/.test(id)) {
+    throw new Error('createDraftProfile: id must match ^[a-z][a-z0-9-]{1,30}$');
+  }
+  if (listProfiles().includes(id)) {
+    throw new Error(`createDraftProfile: ${id} already exists in the curated catalog`);
+  }
+  const dir = draftDir(cwd, id);
+  if (fs.existsSync(dir)) {
+    throw new Error(`createDraftProfile: draft already exists at ${path.relative(cwd, dir)}; archive or delete it before recreating`);
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  fs.mkdirSync(path.join(dir, 'personas'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'departments'), { recursive: true });
+
+  const briefPath = path.join(dir, 'requirements.md');
+  const draftPath = path.join(dir, 'profile.json');
+  fs.writeFileSync(briefPath, REQUIREMENTS_BRIEF(id, displayName || id));
+
+  const draft = DRAFT_PROFILE_TEMPLATE(id, displayName);
+  if (Array.isArray(seedRoles) && seedRoles.length > 0) draft.roles = seedRoles.slice(0, 80);
+  if (Array.isArray(seedDepartments) && seedDepartments.length > 0) {
+    draft.departments = seedDepartments.slice(0, 12).map((d) => ({
+      id: d.id,
+      displayName: d.displayName || d.id,
+      charter: 'Draft. See departments/<id>.md for the canonical charter, derived from organizational-design research (Galbraith STAR).',
+      roles: [],
+    }));
+  }
+  fs.writeFileSync(draftPath, JSON.stringify(draft, null, 2) + '\n');
+
+  const personaPaths = [];
+  for (const roleId of seedRoles) {
+    if (!/^[a-z][a-z0-9-]{1,40}$/.test(roleId)) continue;
+    const p = path.join(dir, 'personas', `${roleId}.md`);
+    fs.writeFileSync(p, personaTemplate(roleId));
+    personaPaths.push(p);
+  }
+
+  const departmentPaths = [];
+  for (const dept of seedDepartments) {
+    if (!dept?.id || !/^[a-z][a-z0-9-]{1,40}$/.test(dept.id)) continue;
+    const p = path.join(dir, 'departments', `${dept.id}.md`);
+    fs.writeFileSync(p, departmentTemplate(dept.id, dept.displayName || dept.id));
+    departmentPaths.push(p);
+  }
+
+  return { dir, briefPath, draftPath, personaPaths, departmentPaths };
+}
+
+/**
+ * List drafts under .cx/profiles/. Returns [{ id, dir, hasProfile, hasBrief }].
+ */
+export function listDrafts(cwd) {
+  const root = path.join(cwd, '.cx', 'profiles');
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!entry.name.startsWith('draft-')) continue;
+    const id = entry.name.replace(/^draft-/, '');
+    const dir = path.join(root, entry.name);
+    out.push({
+      id,
+      dir,
+      hasProfile: fs.existsSync(path.join(dir, 'profile.json')),
+      hasBrief: fs.existsSync(path.join(dir, 'requirements.md')),
+    });
+  }
+  return out;
+}
+
+/**
+ * Archive a curated profile by moving it (and any artifacts it owns in the
+ * repo) into archive/profiles/<id>/. Observations and outcomes are not
+ * touched; they remain as historical record. Requires a non-empty `reason`.
+ */
+export function archiveProfile({ id, reason }) {
+  if (!id) throw new Error('archiveProfile: id is required');
+  if (!reason || reason.trim().length < 8) {
+    throw new Error('archiveProfile: a substantive reason (>= 8 chars) is required');
+  }
+  const srcProfile = path.join(REPO_ROOT, 'profiles', `${id}.json`);
+  if (!fs.existsSync(srcProfile)) {
+    throw new Error(`archiveProfile: ${id} not found in profiles/`);
+  }
+  const profileJson = JSON.parse(fs.readFileSync(srcProfile, 'utf8'));
+  const tablePath = typeof profileJson?.intake?.classificationTable === 'string'
+    ? path.join(REPO_ROOT, profileJson.intake.classificationTable)
+    : null;
+
+  const dstDir = archiveDir(REPO_ROOT, id);
+  fs.mkdirSync(dstDir, { recursive: true });
+  fs.renameSync(srcProfile, path.join(dstDir, `${id}.json`));
+  if (tablePath && fs.existsSync(tablePath)) {
+    fs.renameSync(tablePath, path.join(dstDir, path.basename(tablePath)));
+  }
+  fs.writeFileSync(path.join(dstDir, 'archive-note.md'), [
+    `# Archive: ${id}`,
+    '',
+    `Archived at ${new Date().toISOString()}.`,
+    '',
+    '## Reason',
+    '',
+    reason.trim(),
+    '',
+    '## What stayed',
+    '',
+    'Observations and outcomes recorded under this profile remain in `.cx/observations/` and `.cx/outcomes/` and continue to be searchable. The intake table and profile JSON were moved into this directory. To restore: move the files back to their original paths and re-run `npm run lint:profiles`.',
+    '',
+  ].join('\n'));
+  return { archived: dstDir };
+}
+
+/**
+ * Per-profile health rollup. Counts observations and outcomes tagged with
+ * the profile id, plus the median classification confidence over a window.
+ *
+ * @param {string} cwd - project root
+ * @param {string} profileId
+ * @param {object} [opts]
+ * @param {number} [opts.windowDays=30]
+ */
+export function profileHealth(cwd, profileId, { windowDays = 30 } = {}) {
+  const cutoff = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+  const obsDir = path.join(cwd, '.cx', 'observations');
+  let observationCount = 0;
+  if (fs.existsSync(obsDir)) {
+    const indexPath = path.join(obsDir, 'index.json');
+    if (fs.existsSync(indexPath)) {
+      try {
+        const idx = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+        for (const entry of idx) {
+          if (Date.parse(entry.createdAt) < cutoff) continue;
+          // Observations stamp project, not profile. Fall back to project ==
+          // profile id for the common case where the operator named them the
+          // same; otherwise count under "all" so we never silently report 0.
+          observationCount += entry.project === profileId ? 1 : 0;
+        }
+      } catch { /* unreadable index — health stays 0 */ }
+    }
+  }
+
+  const outcomesDir = path.join(cwd, '.cx', 'outcomes');
+  const roleHealth = {};
+  if (fs.existsSync(outcomesDir)) {
+    for (const f of fs.readdirSync(outcomesDir)) {
+      if (!f.endsWith('.jsonl')) continue;
+      const role = f.replace(/\.\d+\.jsonl$|\.jsonl$/, '');
+      const lines = fs.readFileSync(path.join(outcomesDir, f), 'utf8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        let entry;
+        try { entry = JSON.parse(line); } catch { continue; }
+        if (entry.profile !== profileId) continue;
+        if (Date.parse(entry.ts) < cutoff) continue;
+        const r = roleHealth[role] || (roleHealth[role] = { count: 0, success: 0 });
+        r.count += 1;
+        if (entry.success === true) r.success += 1;
+      }
+    }
+  }
+  const roleSummary = Object.fromEntries(
+    Object.entries(roleHealth).map(([r, s]) => [r, {
+      runs: s.count,
+      successRate: s.count > 0 ? Number((s.success / s.count).toFixed(3)) : 0,
+    }]),
+  );
+
+  return {
+    profile: profileId,
+    profileExists: !!loadProfile(profileId),
+    windowDays,
+    observationCount,
+    roles: roleSummary,
+    generatedAt: new Date().toISOString(),
+  };
+}

package/lib/profiles/loader.mjs

@@ -0,0 +1,123 @@
+/**
+ * lib/profiles/loader.mjs — Curated and custom org-type profile loader.
+ *
+ * Reads JSON profiles from `<repo>/profiles/<id>.json` for the curated set
+ * (rnd, marketing, game-studio, internal-tools), and from `<cwd>/.cx/profile.json`
+ * for user-defined profiles when `custom: true`.
+ *
+ * Resolution order for the active profile:
+ *   1. `construct.config.json` -> `profile`
+ *   2. `<cwd>/.cx/profile.json` -> `id` (custom)
+ *   3. Default: 'rnd'
+ *
+ * All errors fall back to 'rnd' so a malformed profile never breaks the CLI.
+ * Validation surfaces in `npm run lint:profiles` and in B3's pre-push gate.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(MODULE_DIR, '..', '..');
+const PROFILES_DIR = join(REPO_ROOT, 'profiles');
+
+export const DEFAULT_PROFILE_ID = 'rnd';
+
+/**
+ * Read a profile by id from the curated catalog. Returns null if not found.
+ */
+export function loadProfile(id) {
+  if (!id || typeof id !== 'string') return null;
+  const path = join(PROFILES_DIR, `${id}.json`);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List every curated profile id by scanning the profiles directory.
+ */
+export function listProfiles() {
+  if (!existsSync(PROFILES_DIR)) return [];
+  return readdirSync(PROFILES_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace(/\.json$/, ''))
+    .sort();
+}
+
+/**
+ * Load a user-defined profile from `<cwd>/.cx/profile.json`. Returns null if
+ * the file is missing, malformed, or does not have `custom: true`.
+ */
+export function loadCustomProfile(cwd) {
+  if (!cwd) return null;
+  const path = join(cwd, '.cx', 'profile.json');
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (raw && raw.custom === true) return raw;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the active profile for a project. Always returns a profile object.
+ *
+ * Precedence (highest first):
+ *   1. Explicit `configProfileId` argument
+ *   2. `<cwd>/.cx/profile.json` with `custom: true`
+ *   3. `profile` field in `<cwd>/construct.config.json`
+ *   4. Default `rnd`
+ *
+ * Falls back to a minimal RND object on any miss so the CLI never breaks.
+ *
+ * @param {string} cwd - project root
+ * @param {string} [configProfileId] - explicit override, bypasses file lookups
+ */
+export function resolveActiveProfile(cwd, configProfileId = null) {
+  if (configProfileId) {
+    const p = loadProfile(configProfileId);
+    if (p) return p;
+  }
+  const custom = loadCustomProfile(cwd);
+  if (custom) return custom;
+  const fromConfig = readProfileFromProjectConfig(cwd);
+  if (fromConfig) {
+    const p = loadProfile(fromConfig);
+    if (p) return p;
+  }
+  return loadProfile(DEFAULT_PROFILE_ID) ?? minimalRndFallback();
+}
+
+function readProfileFromProjectConfig(cwd) {
+  if (!cwd) return null;
+  const p = join(cwd, 'construct.config.json');
+  if (!existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    return typeof raw?.profile === 'string' ? raw.profile : null;
+  } catch {
+    return null;
+  }
+}
+
+// Last-resort fallback if the curated rnd profile file is missing or
+// unreadable. Lets callers always rely on a non-null shape.
+function minimalRndFallback() {
+  return {
+    id: 'rnd',
+    displayName: 'Software R&D',
+    roles: [],
+    intake: { types: [], stages: [] },
+    docTemplates: [],
+    hooks: { sessionReflect: 'on', sessionOptimize: 'on' },
+    rebrand: { intakeQueueLabel: 'R&D intake queue', signalNoun: 'signal' },
+  };
+}