@geraldmaron/construct 1.2.0 → 1.2.2

package/lib/config/project-config.mjs

@@ -8,15 +8,23 @@
  * corresponding env-var value at load time. Pointers keep API keys in
  * `.env` where they belong; the JSON config never sees a secret literal.
  *
- * Precedence rule for consumers: env var if set > config.json > default.
- * `resolveSetting(config, jsonPath, env, envKey, default)` encodes it
- * once so call sites stay consistent.
+ * Two project tiers, most-specific wins: a gitignored
+ * `construct.config.local.json` sibling merges OVER the committed
+ * `construct.config.json`. List settings (sources.targets, intake
+ * additionalDirs, permission allowlists) merge + dedupe; scalars and objects
+ * override key-by-key.
+ *
+ * Precedence rule for consumers: env var if set > config (local ▷ committed)
+ * > default. `resolveSetting(config, jsonPath, env, envKey, default)` encodes
+ * the rule once so call sites stay consistent.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { CONFIG_SCHEMA_VERSION, DEFAULT_PROJECT_CONFIG, validateProjectConfig, FIELD_RULES } from './schema.mjs';
+import { validateSourceTargets } from './source-targets.mjs';
 
 export const PROJECT_CONFIG_FILENAME = 'construct.config.json';
+export const PROJECT_LOCAL_CONFIG_FILENAME = 'construct.config.local.json';
 
 export function findProjectConfigPath(cwd = process.cwd()) {
   let dir = path.resolve(cwd);
@@ -61,6 +69,64 @@ function deepMerge(base, override) {
   return out;
 }
 
+// Identity for list-tier dedupe: object entries collapse on their `id`
+// (source targets, typed selectors) so a local override that re-declares an id
+// replaces the committed entry rather than duplicating it; everything else
+// dedupes on structural equality.
+
+function listKey(item) {
+  if (item !== null && typeof item === 'object' && !Array.isArray(item) && typeof item.id === 'string') {
+    return `id:${item.id}`;
+  }
+  return `json:${JSON.stringify(item)}`;
+}
+
+function mergeList(base, override) {
+  const out = [];
+  const seen = new Map();
+  for (const item of [...(base || []), ...(override || [])]) {
+    const key = listKey(item);
+    if (seen.has(key)) {
+      out[seen.get(key)] = item;
+    } else {
+      seen.set(key, out.length);
+      out.push(item);
+    }
+  }
+  return out;
+}
+
+// Project-local tier merge (most-specific wins): lists merge + dedupe so a local
+// override adds to committed lists (extra source targets, intake dirs, allowlist
+// entries) instead of clobbering them; scalars and objects override key-by-key.
+
+function mergeConfigTier(base, override) {
+  if (override === undefined) return base;
+  if (Array.isArray(base) && Array.isArray(override)) return mergeList(base, override);
+  if (override === null || typeof override !== 'object' || Array.isArray(override)) return override;
+  const out = Array.isArray(base) ? [...(base || [])] : { ...(base || {}) };
+  for (const [k, v] of Object.entries(override)) {
+    out[k] = mergeConfigTier(base?.[k], v);
+  }
+  return out;
+}
+
+function loadLocalConfigOverlay(configPath) {
+  const localPath = path.join(path.dirname(configPath), PROJECT_LOCAL_CONFIG_FILENAME);
+  if (!fs.existsSync(localPath)) return { raw: null, path: null, errors: [] };
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(localPath, 'utf8'));
+  } catch (err) {
+    return { raw: null, path: localPath, errors: [`failed to parse ${localPath}: ${err.message}`] };
+  }
+  const validation = validateProjectConfig(raw, { partial: true });
+  if (!validation.valid) {
+    return { raw: null, path: localPath, errors: (validation.errors ?? []).map((e) => `${localPath}: ${e}`) };
+  }
+  return { raw, path: localPath, errors: [] };
+}
+
 export function loadProjectConfig(cwd = process.cwd(), env = process.env) {
   const configPath = findProjectConfigPath(cwd);
   if (!configPath) {
@@ -85,22 +151,51 @@ export function loadProjectConfig(cwd = process.cwd(), env = process.env) {
     };
   }
   const validation = validateProjectConfig(raw);
-  if (!validation.valid) {
+  const targetErrors = raw?.sources?.targets !== undefined
+    ? validateSourceTargets(raw.sources.targets)
+    : [];
+  const allErrors = [...(validation.errors ?? []), ...targetErrors];
+  if (!validation.valid || targetErrors.length) {
     return {
       path: configPath,
       raw,
       config: structuredClone(DEFAULT_PROJECT_CONFIG),
       source: 'invalid',
-      errors: validation.errors,
+      errors: allErrors,
     };
   }
+  const overlay = loadLocalConfigOverlay(configPath);
+  if (overlay.errors.length) {
+    return {
+      path: configPath,
+      raw,
+      config: structuredClone(DEFAULT_PROJECT_CONFIG),
+      source: 'invalid',
+      errors: overlay.errors,
+    };
+  }
+  if (overlay.raw?.sources?.targets !== undefined) {
+    const overlayTargetErrors = validateSourceTargets(overlay.raw.sources.targets);
+    if (overlayTargetErrors.length) {
+      return {
+        path: configPath,
+        raw,
+        config: structuredClone(DEFAULT_PROJECT_CONFIG),
+        source: 'invalid',
+        errors: overlayTargetErrors.map((e) => `${overlay.path}: ${e}`),
+      };
+    }
+  }
+
   const merged = deepMerge(structuredClone(DEFAULT_PROJECT_CONFIG), raw);
-  const resolved = interpolateSecrets(merged, env);
+  const withLocal = overlay.raw ? mergeConfigTier(merged, overlay.raw) : merged;
+  const resolved = interpolateSecrets(withLocal, env);
   return {
     path: configPath,
     raw,
+    localPath: overlay.path,
     config: resolved,
-    source: 'file',
+    source: overlay.raw ? 'file+local' : 'file',
     errors: [],
   };
 }
@@ -161,6 +256,10 @@ export function writeProjectConfig(filePath, config, options = {}) {
   let validation = { valid: true, errors: [] };
   if (validate) {
     validation = validateProjectConfig(config);
+    if (config?.sources?.targets !== undefined) {
+      validation.errors = [...(validation.errors ?? []), ...validateSourceTargets(config.sources.targets)];
+      validation.valid = validation.errors.length === 0;
+    }
   }
   
   // Combine all errors (handle case where validation.errors is undefined)

package/lib/config/schema.mjs

@@ -5,7 +5,8 @@
  * AJV/zod to keep Construct dependency-free at startup — the loader runs
  * before npm install completes in some bootstrap paths.
  *
- * Schema v1 covers: alias, deployment, providers, autoEmbed, ingest, telemetry.
+ * Schema v1 covers: alias, deployment, providers, sources, intakePolicy,
+ * autoEmbed, ingest, telemetry.
  * Tier model selection lives in `specialists/registry.json` only — this config
  * file is intentionally not a second edit surface for model assignments.
  * Later phases (6, 7b) extend it with `resources` and `costs` blocks
@@ -47,6 +48,17 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
     tenantId: null,
   }),
   providers: Object.freeze({}),
+  sources: Object.freeze({
+    targets: [],
+  }),
+  intakePolicy: Object.freeze({
+    maxDepth: 4,
+    additionalDirs: [],
+  }),
+  artifactWorkflow: Object.freeze({
+    defaults: Object.freeze({}),
+    types: Object.freeze({}),
+  }),
   profile: DEFAULT_PROFILE_ID,
   autoEmbed: false,
   ingest: Object.freeze({
@@ -121,6 +133,29 @@ export const FIELD_RULES = {
     },
   },
   providers: { type: 'object', required: false },
+  sources: {
+    type: 'object',
+    required: false,
+    fields: {
+      targets: { type: 'array' },
+    },
+  },
+  intakePolicy: {
+    type: 'object',
+    required: false,
+    fields: {
+      maxDepth: { type: 'number' },
+      additionalDirs: { type: 'array' },
+    },
+  },
+  artifactWorkflow: {
+    type: 'object',
+    required: false,
+    fields: {
+      defaults: { type: 'object', required: false },
+      types: { type: 'object', required: false },
+    },
+  },
   profile: { type: 'string', required: false, maxLength: 40 },
   autoEmbed: { type: 'boolean', required: false },
   ingest: {
@@ -220,10 +255,10 @@ function checkType(value, expected) {
   return typeof value === expected;
 }
 
-function validateField(value, rule, path) {
+function validateField(value, rule, path, partial = false) {
   const errors = [];
   if (value === undefined) {
-    if (rule.required) errors.push(`${path}: required field missing`);
+    if (rule.required && !partial) errors.push(`${path}: required field missing`);
     return errors;
   }
   if (!checkType(value, rule.type)) {
@@ -238,19 +273,23 @@ function validateField(value, rule, path) {
   }
   if (rule.fields && checkType(value, 'object')) {
     for (const [key, subRule] of Object.entries(rule.fields)) {
-      errors.push(...validateField(value[key], subRule, `${path}.${key}`));
+      errors.push(...validateField(value[key], subRule, `${path}.${key}`, partial));
     }
   }
   return errors;
 }
 
-export function validateProjectConfig(raw) {
+// `partial` validation skips the required-field check so a sparse override file
+// (construct.config.local.json) validates, while still type- and enum-checking
+// every key that is present.
+
+export function validateProjectConfig(raw, { partial = false } = {}) {
   const errors = [];
   if (!checkType(raw, 'object')) {
     return { valid: false, errors: ['root: must be an object'] };
   }
   for (const [key, rule] of Object.entries(FIELD_RULES)) {
-    errors.push(...validateField(raw[key], rule, key));
+    errors.push(...validateField(raw[key], rule, key, partial));
   }
   if (raw.version !== undefined && raw.version !== CONFIG_SCHEMA_VERSION) {
     errors.push(`version: expected ${CONFIG_SCHEMA_VERSION}, got ${raw.version}`);

package/lib/config/source-targets.mjs

@@ -0,0 +1,311 @@
+/**
+ * lib/config/source-targets.mjs — typed integration source targets in construct.config.json.
+ *
+ * Validates GitHub, Jira, Linear, and Slack selector records, merges legacy env
+ * target lists additively, deduplicates by provider+selector signature, and
+ * converts resolved targets into embed provider source records for auto-discovery.
+ */
+
+export const SOURCE_PROVIDERS = Object.freeze(['github', 'jira', 'linear', 'slack']);
+
+export const SLACK_INTENTS = Object.freeze(['internal', 'risk', 'decision', 'external', 'how-to']);
+
+const ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+const GITHUB_REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const JIRA_PROJECT_RE = /^[A-Z][A-Z0-9]{1,9}$/;
+
+export function validateSourceTarget(target, index = 0) {
+  const errors = [];
+  const at = `sources.targets[${index}]`;
+
+  if (!target || typeof target !== 'object' || Array.isArray(target)) {
+    return [`${at}: must be an object`];
+  }
+
+  if (typeof target.id !== 'string' || !ID_RE.test(target.id)) {
+    errors.push(`${at}.id: required stable id (letters, numbers, hyphens, underscores; max 64 chars)`);
+  }
+
+  if (!SOURCE_PROVIDERS.includes(target.provider)) {
+    errors.push(`${at}.provider: must be one of ${SOURCE_PROVIDERS.join(', ')}`);
+  }
+
+  if (!target.selector || typeof target.selector !== 'object' || Array.isArray(target.selector)) {
+    errors.push(`${at}.selector: required object`);
+    return errors;
+  }
+
+  const sel = target.selector;
+  switch (target.provider) {
+    case 'github':
+      if (typeof sel.repo !== 'string' || !GITHUB_REPO_RE.test(sel.repo.trim())) {
+        errors.push(`${at}.selector.repo: required owner/repo slug`);
+      }
+      break;
+    case 'jira':
+      if (typeof sel.project !== 'string' || !JIRA_PROJECT_RE.test(sel.project.trim().toUpperCase())) {
+        errors.push(`${at}.selector.project: required Jira project key (2–10 uppercase letters/digits)`);
+      }
+      break;
+    case 'linear':
+      if (typeof sel.team !== 'string' || !sel.team.trim()) {
+        errors.push(`${at}.selector.team: required Linear team key or name`);
+      }
+      break;
+    case 'slack': {
+      if (typeof sel.channel !== 'string' || !sel.channel.trim()) {
+        errors.push(`${at}.selector.channel: required Slack channel name or ID`);
+      }
+      if (sel.intent !== undefined && !SLACK_INTENTS.includes(sel.intent)) {
+        errors.push(`${at}.selector.intent: must be one of ${SLACK_INTENTS.join(', ')}`);
+      }
+      break;
+    }
+    default:
+      break;
+  }
+
+  return errors;
+}
+
+export function validateSourceTargets(targets) {
+  const errors = [];
+  if (targets === undefined) return errors;
+  if (!Array.isArray(targets)) {
+    return ['sources.targets: must be an array'];
+  }
+
+  const seenIds = new Set();
+  for (let i = 0; i < targets.length; i++) {
+    errors.push(...validateSourceTarget(targets[i], i));
+    const id = targets[i]?.id;
+    if (typeof id === 'string') {
+      const key = id.toLowerCase();
+      if (seenIds.has(key)) {
+        errors.push(`sources.targets[${i}].id: duplicate id "${id}"`);
+      }
+      seenIds.add(key);
+    }
+  }
+  return errors;
+}
+
+function parseCsv(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function slugId(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function parseSlackChannelEntry(raw) {
+  const trimmed = String(raw).trim().replace(/^#/, '');
+  const colon = trimmed.indexOf(':');
+  if (colon === -1) {
+    return { channel: trimmed, intent: 'internal' };
+  }
+  return { channel: trimmed.slice(0, colon), intent: trimmed.slice(colon + 1) || 'internal' };
+}
+
+export function legacyEnvSourceTargets(env = process.env) {
+  const targets = [];
+
+  for (const repo of parseCsv(env.GITHUB_REPOS ?? env.GITHUB_REPO)) {
+    targets.push({
+      id: `env-github-${slugId(repo)}`,
+      provider: 'github',
+      selector: { repo },
+      provenance: 'env:GITHUB_REPOS',
+    });
+  }
+
+  for (const project of parseCsv(env.JIRA_PROJECTS)) {
+    const key = project.toUpperCase();
+    targets.push({
+      id: `env-jira-${slugId(key)}`,
+      provider: 'jira',
+      selector: { project: key },
+      provenance: 'env:JIRA_PROJECTS',
+    });
+  }
+
+  for (const team of parseCsv(env.LINEAR_TEAMS)) {
+    targets.push({
+      id: `env-linear-${slugId(team)}`,
+      provider: 'linear',
+      selector: { team },
+      provenance: 'env:LINEAR_TEAMS',
+    });
+  }
+
+  for (const entry of parseCsv(env.SLACK_CHANNELS ?? env.SLACK_CHANNEL)) {
+    const { channel, intent } = parseSlackChannelEntry(entry);
+    targets.push({
+      id: `env-slack-${slugId(channel)}`,
+      provider: 'slack',
+      selector: { channel, intent: SLACK_INTENTS.includes(intent) ? intent : 'internal' },
+      provenance: 'env:SLACK_CHANNELS',
+    });
+  }
+
+  return targets;
+}
+
+export function targetSignature(target) {
+  const sel = target.selector ?? {};
+  switch (target.provider) {
+    case 'github':
+      return `github:repo:${sel.repo?.trim().toLowerCase()}`;
+    case 'jira':
+      return `jira:project:${String(sel.project ?? '').trim().toUpperCase()}`;
+    case 'linear':
+      return `linear:team:${String(sel.team ?? '').trim().toLowerCase()}`;
+    case 'slack':
+      return `slack:channel:${String(sel.channel ?? '').trim().toLowerCase()}:intent:${sel.intent ?? 'internal'}`;
+    default:
+      return `${target.provider}:${JSON.stringify(sel)}`;
+  }
+}
+
+export function mergeSourceTargets(configTargets = [], envTargets = []) {
+  const merged = [];
+  const seen = new Set();
+
+  for (const target of [...configTargets, ...envTargets]) {
+    const sig = targetSignature(target);
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    merged.push(target);
+  }
+  return merged;
+}
+
+export function normalizeConfigTarget(raw) {
+  const out = {
+    id: String(raw.id).trim(),
+    provider: raw.provider,
+    selector: { ...raw.selector },
+    provenance: raw.provenance ?? 'config',
+  };
+
+  if (out.provider === 'jira' && out.selector.project) {
+    out.selector.project = String(out.selector.project).trim().toUpperCase();
+  }
+  if (out.provider === 'github' && out.selector.repo) {
+    out.selector.repo = String(out.selector.repo).trim();
+  }
+  if (out.provider === 'linear' && out.selector.team) {
+    out.selector.team = String(out.selector.team).trim();
+  }
+  if (out.provider === 'slack' && out.selector.channel) {
+    out.selector.channel = String(out.selector.channel).trim().replace(/^#/, '');
+    if (!out.selector.intent) out.selector.intent = 'internal';
+  }
+  return out;
+}
+
+export function resolveEffectiveSourceTargetsFromConfig(config, env = process.env) {
+  const configTargets = (config?.sources?.targets ?? []).map(normalizeConfigTarget);
+  const envTargets = legacyEnvSourceTargets(env);
+  return mergeSourceTargets(configTargets, envTargets);
+}
+
+export function targetsToEmbedSources(targets) {
+  const sources = [];
+  const githubRepos = targets.filter((t) => t.provider === 'github').map((t) => t.selector.repo);
+  if (githubRepos.length) {
+    sources.push({
+      provider: 'github',
+      repos: githubRepos,
+      refs: ['prs', 'issues', 'commits'],
+      limit: 25,
+    });
+    sources.push({
+      provider: 'github',
+      repos: githubRepos,
+      refs: ['meta', 'readme', 'docs'],
+      limit: 25,
+    });
+  }
+
+  for (const target of targets.filter((t) => t.provider === 'jira')) {
+    sources.push({
+      provider: 'jira',
+      project: target.selector.project,
+      refs: ['issues'],
+      limit: 50,
+    });
+  }
+
+  for (const target of targets.filter((t) => t.provider === 'linear')) {
+    sources.push({
+      provider: 'linear',
+      team: target.selector.team,
+      refs: ['issues'],
+      limit: 50,
+    });
+  }
+
+  const slackByIntent = new Map();
+  for (const target of targets.filter((t) => t.provider === 'slack')) {
+    const intent = target.selector.intent ?? 'internal';
+    if (!slackByIntent.has(intent)) slackByIntent.set(intent, []);
+    slackByIntent.get(intent).push(target.selector.channel);
+  }
+  for (const [intent, channels] of slackByIntent) {
+    sources.push({
+      provider: 'slack',
+      channels,
+      intent,
+      refs: ['messages'],
+      oldest: 86400,
+      limit: 50,
+    });
+  }
+
+  return sources;
+}
+
+export function resolveKnownSourcesFromTargets(targets) {
+  const sources = [];
+
+  for (const target of targets) {
+    const sel = target.selector ?? {};
+    if (target.provider === 'github' && sel.repo) {
+      const repo = sel.repo;
+      const short = repo.split('/').pop();
+      sources.push({ id: repo.toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      sources.push({ id: short.toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      sources.push({ id: short.replace(/-/g, '').toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      const words = short.split('-');
+      if (words.length > 1) {
+        sources.push({ id: words[words.length - 1].toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      }
+    }
+    if (target.provider === 'jira' && sel.project) {
+      const key = sel.project;
+      sources.push({ id: key.toLowerCase(), provider: 'jira', ref: key, display: `Jira/${key}`, targetId: target.id });
+    }
+    if (target.provider === 'linear' && sel.team) {
+      const team = sel.team;
+      sources.push({ id: team.toLowerCase(), provider: 'linear', ref: team, display: `Linear/${team}`, targetId: target.id });
+    }
+    if (target.provider === 'slack' && sel.channel) {
+      const ch = sel.channel;
+      sources.push({ id: ch.toLowerCase(), provider: 'slack', ref: ch, display: `Slack/${ch}`, targetId: target.id });
+    }
+  }
+
+  const providers = new Set(targets.map((t) => t.provider));
+  if (providers.has('jira')) {
+    sources.push({ id: 'jira', provider: 'jira', ref: null, display: 'Jira' });
+  }
+  if (providers.has('linear')) {
+    sources.push({ id: 'linear', provider: 'linear', ref: null, display: 'Linear' });
+  }
+
+  return sources;
+}

package/lib/config/xdg.mjs

@@ -0,0 +1,63 @@
+/**
+ * lib/config/xdg.mjs — single source of truth for Construct's user-scope base
+ * directories, following the XDG Base Directory specification.
+ *
+ * Keeps config (versionable settings), state (durable runtime data), and cache
+ * (regenerable transients) on separate roots so each can be backed up, synced,
+ * and pruned independently:
+ *
+ *   configDir() → $XDG_CONFIG_HOME/construct  (default ~/.config/construct)
+ *   stateDir()  → $XDG_STATE_HOME/construct   (default ~/.local/state/construct)
+ *   cacheDir()  → $XDG_CACHE_HOME/construct   (default ~/.cache/construct)
+ *
+ * Per the XDG spec, an env var is honored only when it is set AND absolute;
+ * a relative or empty value is ignored and the default applies. Every helper
+ * takes an optional homeDir for testability, mirroring the existing homeDir
+ * params across the codebase.
+ *
+ * Clean break: there is no legacy `~/.construct/*` read here. Existing installs
+ * re-run `construct install --scope=user` to repopulate at the XDG paths.
+ */
+import os from 'node:os';
+import path from 'node:path';
+
+// Leaf segment appended under each resolved base.
+
+const APP = 'construct';
+
+// XDG honors an env override only when it names an absolute path; anything
+// relative or empty falls through to the spec default so a stray cwd-relative
+// value can never relocate user state under the process working directory.
+
+function resolveBase(envValue, fallbackSegments, homeDir) {
+  if (typeof envValue === 'string' && path.isAbsolute(envValue)) {
+    return envValue;
+  }
+  return path.join(homeDir, ...fallbackSegments);
+}
+
+export function configDir(homeDir = os.homedir(), env = process.env) {
+  const base = resolveBase(env.XDG_CONFIG_HOME, ['.config'], homeDir);
+  return path.join(base, APP);
+}
+
+export function stateDir(homeDir = os.homedir(), env = process.env) {
+  const base = resolveBase(env.XDG_STATE_HOME, ['.local', 'state'], homeDir);
+  return path.join(base, APP);
+}
+
+// The global doctor/telemetry/runtime axis (formerly rooted at ~/.cx) now
+// resolves to the XDG state dir. CONSTRUCT_DOCTOR_ROOT, shared by the
+// telemetry/doctor/oracle ecosystem for test isolation, still wins when set to
+// a non-empty value; otherwise stateDir() supplies the durable default.
+
+export function doctorRoot(homeDir = os.homedir(), env = process.env) {
+  const override = env.CONSTRUCT_DOCTOR_ROOT;
+  if (typeof override === 'string' && override.trim()) return override;
+  return stateDir(homeDir, env);
+}
+
+export function cacheDir(homeDir = os.homedir(), env = process.env) {
+  const base = resolveBase(env.XDG_CACHE_HOME, ['.cache'], homeDir);
+  return path.join(base, APP);
+}

package/lib/contracts/violation-log.mjs

@@ -25,12 +25,12 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const CX_DIR = join(homedir(), '.cx');
+const CX_DIR = doctorRoot();
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 
 // contract-violations are PROJECT-SCOPED: resolves to

package/lib/cost-ledger.mjs

@@ -5,7 +5,7 @@
  * before they blow the daily budget. Separate from lib/roles/ because both
  * the gateway and the cost watcher consume it.
  *
- * Storage: ~/.cx/cost-ledger.json — small JSON object keyed by `<dayKey>:<personaId>`.
+ * Storage: <doctorRoot>/cost-ledger.json — small JSON object keyed by `<dayKey>:<personaId>`.
  * Rotates: entries older than 30 days are pruned on each write.
  *
  * Budgets are env-driven defaults; explicit `CONSTRUCT_BUDGET_<PERSONA>` wins.
@@ -15,16 +15,17 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { cwd as procCwd } from 'node:process';
 
+import { doctorRoot } from './config/xdg.mjs';
+
 const PRUNE_DAYS = 30;
 const DEFAULT_PER_PERSONA = 10.0;
 const DEFAULT_TOTAL = 50.0;
 
 function rootDir() {
-  return process.env.CONSTRUCT_DOCTOR_ROOT || join(homedir(), '.cx');
+  return doctorRoot();
 }
 function ledgerPath() {
   return join(rootDir(), 'cost-ledger.json');