@geraldmaron/construct 1.0.3 → 1.0.5

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' },
+  };
+}

package/lib/profiles/validate-custom.mjs

@@ -0,0 +1,114 @@
+/**
+ * lib/profiles/validate-custom.mjs — Schema validator for user-defined profiles.
+ *
+ * Custom profiles live at `<project>/.cx/profile.json` with `custom: true`.
+ * They are validated on `construct sync` and via the pre-push gate. Rejected
+ * profiles never get loaded; resolveActiveProfile falls back to the default
+ * so a malformed escape-hatch file never breaks a project.
+ *
+ * Hard limits the validator enforces (kept in sync with schemas/profile.schema.json
+ * and scripts/lint-profiles.mjs):
+ *   - max 12 stages
+ *   - max 24 intake types
+ *   - max 80 roles per profile
+ *   - max 12 departments per profile
+ *   - max 20 roles per department
+ *   - classificationTable path must stay inside .cx/ (no repo escapes)
+ *
+ * Rationale for each cap lives in docs/concepts/persona-research.md.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_STAGES = 12;
+const MAX_INTAKE_TYPES = 24;
+const MAX_ROLES = 80;
+const MAX_DEPARTMENTS = 12;
+const MAX_ROLES_PER_DEPARTMENT = 20;
+
+/**
+ * @returns {string[]} array of error strings; empty means valid.
+ */
+export function validateCustomProfile(profile, { cwd } = {}) {
+  const errors = [];
+  if (!profile || typeof profile !== 'object') return ['profile is not an object'];
+  if (profile.custom !== true) errors.push('custom profiles must set custom: true');
+
+  if (!profile.id || !/^[a-z][a-z0-9-]{1,30}$/.test(profile.id)) {
+    errors.push('id must match ^[a-z][a-z0-9-]{1,30}$');
+  }
+  if (!profile.displayName || typeof profile.displayName !== 'string') {
+    errors.push('displayName is required');
+  }
+  if (!Array.isArray(profile.roles) || profile.roles.length === 0) {
+    errors.push('roles must be a non-empty array');
+  } else if (profile.roles.length > MAX_ROLES) {
+    errors.push(`roles exceeds max of ${MAX_ROLES}`);
+  }
+  if (!profile.intake || typeof profile.intake !== 'object') {
+    errors.push('intake is required');
+  } else {
+    if (!Array.isArray(profile.intake.types) || profile.intake.types.length === 0) {
+      errors.push('intake.types must be a non-empty array');
+    } else if (profile.intake.types.length > MAX_INTAKE_TYPES) {
+      errors.push(`intake.types exceeds max of ${MAX_INTAKE_TYPES}`);
+    }
+    if (!Array.isArray(profile.intake.stages) || profile.intake.stages.length === 0) {
+      errors.push('intake.stages must be a non-empty array');
+    } else if (profile.intake.stages.length > MAX_STAGES) {
+      errors.push(`intake.stages exceeds max of ${MAX_STAGES}`);
+    }
+    if (typeof profile.intake.classificationTable === 'string') {
+      const t = profile.intake.classificationTable;
+      if (path.isAbsolute(t)) {
+        errors.push('intake.classificationTable must be a relative path');
+      } else if (cwd && !t.startsWith('.cx/')) {
+        errors.push('intake.classificationTable must live under .cx/ for custom profiles');
+      }
+    }
+  }
+  if (profile.departments !== undefined) {
+    if (!Array.isArray(profile.departments)) {
+      errors.push('departments must be an array');
+    } else {
+      if (profile.departments.length > MAX_DEPARTMENTS) {
+        errors.push(`departments exceeds max of ${MAX_DEPARTMENTS}`);
+      }
+      for (const [i, dept] of profile.departments.entries()) {
+        if (!dept || typeof dept !== 'object') {
+          errors.push(`departments[${i}] must be an object`);
+          continue;
+        }
+        if (!dept.id || !/^[a-z][a-z0-9-]{1,40}$/.test(dept.id)) {
+          errors.push(`departments[${i}].id is missing or malformed`);
+        }
+        if (!dept.charter || dept.charter.length < 20) {
+          errors.push(`departments[${i}].charter must be at least 20 chars (mission statement, not a label)`);
+        }
+        if (!Array.isArray(dept.roles) || dept.roles.length === 0) {
+          errors.push(`departments[${i}].roles must be a non-empty array`);
+        } else if (dept.roles.length > MAX_ROLES_PER_DEPARTMENT) {
+          errors.push(`departments[${i}].roles exceeds max of ${MAX_ROLES_PER_DEPARTMENT}`);
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Read and validate `<cwd>/.cx/profile.json`. Returns:
+ *   { status: 'absent' }                 if the file does not exist
+ *   { status: 'invalid', errors: [...] } if validation failed
+ *   { status: 'ok', profile }            if the file is a valid custom profile
+ */
+export function validateCustomProfileFile(cwd) {
+  const p = path.join(cwd, '.cx', 'profile.json');
+  if (!fs.existsSync(p)) return { status: 'absent' };
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (err) { return { status: 'invalid', errors: [`malformed JSON: ${err.message}`] }; }
+  const errors = validateCustomProfile(raw, { cwd });
+  if (errors.length > 0) return { status: 'invalid', errors };
+  return { status: 'ok', profile: raw };
+}