@geraldmaron/construct 1.0.11 → 1.0.14

package/lib/orchestration/routing-tables.mjs

@@ -0,0 +1,176 @@
+/**
+ * lib/orchestration/routing-tables.mjs — declarative routing resolver.
+ *
+ * Reads specialist subscriptions, doc-artifact ownership, and watch-condition
+ * references from specialists/registry.json (with optional .cx/specialists/
+ * overlays) and exposes the forward lookups the orchestration layer needs.
+ *
+ * The resolver is the single source of truth for event/doc/watch routing.
+ * Projects override routing without patching library code by dropping JSON
+ * files into .cx/specialists/ — each overlay's fields apply over the
+ * canonical registry entry for the same specialist.
+ *
+ * Watch conditions are referenced by name. The implementations live in
+ * WATCHERS below — small predicates over the requestSignals shape. The
+ * registry decides WHICH specialist a named watcher routes to; this file
+ * decides WHAT condition triggers it. Project overlays can re-bind a
+ * watcher's specialist; adding a brand-new watcher requires code.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findProjectRoot } from '../project-root.mjs';
+
+const REGISTRY_PATH = fileURLToPath(new URL('../../specialists/registry.json', import.meta.url));
+
+// Watch-condition predicates. Each is a pure function from requestSignals
+// (see orchestration-policy.requestSignals) to boolean. Registry entries
+// reference these by key. Keep predicates small and side-effect free.
+
+const WATCHERS = {
+  'high-ambiguity-deep-work': (s) =>
+    s.ambiguityScore > 0.5 && s.workCategory === 'deep',
+  'visual-or-ui-risk': (s) =>
+    Boolean(s.visualDeliverable) || Boolean(s.riskFlags?.ui),
+  'auth-payments-non-narrow': (s) =>
+    Boolean(s.authOrPayments) && s.blastRadius !== 'narrow',
+  'architecture-without-metric': (s) =>
+    Boolean(s.riskFlags?.architecture) && !s.hasSuccessMetric,
+  'wide-blast-radius': (s) => s.blastRadius === 'wide',
+};
+
+let cache = null;
+
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function loadOverlays() {
+  const root = findProjectRoot();
+  if (!root) return [];
+  const overlayDir = join(root, '.cx', 'specialists');
+  if (!existsSync(overlayDir)) return [];
+  const out = [];
+  for (const name of readdirSync(overlayDir)) {
+    if (!name.endsWith('.json')) continue;
+    const data = readJsonSafe(join(overlayDir, name));
+    if (data && typeof data === 'object') out.push(data);
+  }
+  return out;
+}
+
+function buildTables() {
+  const registry = readJsonSafe(REGISTRY_PATH);
+  if (!registry || !Array.isArray(registry.specialists)) {
+    throw new Error('routing-tables: registry.json missing or malformed');
+  }
+
+  // Forward maps. Last writer wins for overlays; the resolver validates
+  // duplicate ownership inside the canonical registry, so a project overlay
+  // is the only way to re-bind a single event/doc/watcher.
+
+  const eventToOwner = new Map();
+  const docToOwner = new Map();
+  const watcherToOwner = new Map();
+  const watcherToReason = new Map();
+
+  const errors = [];
+
+  function apply(entry, source) {
+    const cxId = entry.name?.startsWith('cx-') ? entry.name : `cx-${entry.name}`;
+    if (Array.isArray(entry.subscriptions)) {
+      for (const event of entry.subscriptions) {
+        if (eventToOwner.has(event) && eventToOwner.get(event) !== cxId && source === 'registry') {
+          errors.push(`duplicate event ownership: ${event} → ${eventToOwner.get(event)} vs ${cxId}`);
+        }
+        eventToOwner.set(event, cxId);
+      }
+    }
+    if (Array.isArray(entry.docArtifacts)) {
+      for (const docType of entry.docArtifacts) {
+        if (docToOwner.has(docType) && docToOwner.get(docType) !== cxId && source === 'registry') {
+          errors.push(`duplicate doc ownership: ${docType} → ${docToOwner.get(docType)} vs ${cxId}`);
+        }
+        docToOwner.set(docType, cxId);
+      }
+    }
+    if (Array.isArray(entry.watchConditions)) {
+      for (const watch of entry.watchConditions) {
+        const name = typeof watch === 'string' ? watch : watch.watcher;
+        const reason = typeof watch === 'string' ? null : watch.reason;
+        if (!WATCHERS[name]) {
+          errors.push(`unknown watchCondition: ${name} (referenced by ${cxId})`);
+          continue;
+        }
+        watcherToOwner.set(name, cxId);
+        if (reason) watcherToReason.set(name, reason);
+      }
+    }
+  }
+
+  for (const entry of registry.specialists) apply(entry, 'registry');
+  for (const overlay of loadOverlays()) apply(overlay, 'overlay');
+
+  if (errors.length > 0) {
+    throw new Error(`routing-tables: ${errors.join('; ')}`);
+  }
+
+  return {
+    eventToOwner,
+    docToOwner,
+    watcherToOwner,
+    watcherToReason,
+  };
+}
+
+function tables() {
+  if (!cache) cache = buildTables();
+  return cache;
+}
+
+export function ownerForEvent(eventType) {
+  if (!eventType) return null;
+  return tables().eventToOwner.get(eventType) ?? null;
+}
+
+export function ownerForDoc(docType) {
+  if (!docType) return null;
+  return tables().docToOwner.get(docType) ?? null;
+}
+
+export function evaluateWatchConditions(signals) {
+  const triggers = [];
+  const t = tables();
+  for (const [name, predicate] of Object.entries(WATCHERS)) {
+    const owner = t.watcherToOwner.get(name);
+    if (!owner) continue;
+    if (!predicate(signals)) continue;
+    triggers.push({
+      specialist: owner,
+      reason: t.watcherToReason.get(name) ?? name,
+      watcher: name,
+    });
+  }
+  return triggers;
+}
+
+export function knownEventTypes() {
+  return Array.from(tables().eventToOwner.keys());
+}
+
+export function knownDocTypes() {
+  return Array.from(tables().docToOwner.keys());
+}
+
+export function knownWatchers() {
+  return Object.keys(WATCHERS);
+}
+
+export function _resetCache() {
+  cache = null;
+}

package/lib/orchestration-policy.mjs

@@ -7,14 +7,17 @@
  *   3. contract chain (resolveContractChain)  (what the typed handoffs are)
  *
  * Agent-to-agent contracts are defined in specialists/contracts.json and loaded via
- * lib/specialist-contracts.mjs. That file is the single source of truth for
- * producer→consumer expectations, replacing the scattered DOC_OWNERSHIP map,
- * SPECIALIST_MAP, and informal "collaborators" lists for anything contract-
- * shaped. The older maps remain for quick lookups but defer to contracts.json
- * for authoritative semantics.
+ * lib/specialist-contracts.mjs. That file is the source of truth for
+ * producer→consumer typed handoffs.
+ *
+ * Event ownership, doc-artifact ownership, and watch-condition routing live
+ * declaratively on specialist entries in specialists/registry.json and are
+ * resolved by lib/orchestration/routing-tables.mjs. Hardcoded maps here
+ * would create a second source of truth.
  */
 import { resolveContractChain } from './specialist-contracts.mjs';
 import { verifyRoute } from './intent-classifier.mjs';
+import { ownerForEvent, ownerForDoc, evaluateWatchConditions, knownDocTypes } from './orchestration/routing-tables.mjs';
 
 export const EXECUTION_TRACKS = {
   immediate: 'immediate',
@@ -40,86 +43,11 @@ export const WORK_CATEGORIES = {
 
 export const TERMINAL_STATES = ['DONE', 'BLOCKED', 'NEEDS_MAIN_INPUT'];
 
-/**
- * Maps document types to the specialist that owns authoring them.
- * Construct (or any general persona) must route to the owner rather than
- * authoring these directly — authoring is how the owner's domain checks
- * (framing, research, trade-off analysis) actually fire.
- *
- * Keep in sync with rules/common/doc-ownership.md.
- */
-export const DOC_OWNERSHIP = {
-  prd: 'cx-product-manager',
-  'meta-prd': 'cx-product-manager',
-  'prd-platform': 'cx-product-manager',
-  'prd-business': 'cx-product-manager',
-  prfaq: 'cx-product-manager',
-  'one-pager': 'cx-product-manager',
-  'backlog-proposal': 'cx-product-manager',
-  'customer-profile': 'cx-product-manager',
-  adr: 'cx-architect',
-  rfc: 'cx-architect',
-  'rfc-platform': 'cx-architect',
-  'architecture-overview': 'cx-architect',
-  'system-design': 'cx-architect',
-  'research-brief': 'cx-researcher',
-  'evidence-brief': 'cx-researcher',
-  'signal-brief': 'cx-researcher',
-  'product-intelligence-report': 'cx-researcher',
-  runbook: 'cx-sre',
-  'incident-report': 'cx-sre',
-  postmortem: 'cx-sre',
-  'test-plan': 'cx-qa',
-  'qa-strategy': 'cx-qa',
-  'security-review': 'cx-security',
-  'threat-model': 'cx-security',
-  memo: 'cx-docs-keeper',
-  changelog: 'cx-docs-keeper',
-};
+// Event and doc-artifact ownership are resolved from specialists/registry.json
+// via routing-tables.mjs. Re-exported here so callers that historically
+// imported from this module keep working.
 
-// Event ownership for the role framework (lib/roles/**). When a hook emits
-// an event of one of these types, the gateway routes the invocation to the
-// listed persona. Empty owners mean the event is recorded but no persona
-// fires until onboarded. Keep in sync with specialists/role-manifests.json.
-
-export const EVENT_OWNERSHIP = {
-  'push_gate.fail': 'cx-sre',
-  'service.down': 'cx-sre',
-  'mcp.unhealthy.persistent': 'cx-sre',
-  'edit_loop.stuck': 'cx-sre',
-  'test.fail': 'cx-qa',
-  'test.flake': 'cx-qa',
-  'coverage.drop': 'cx-qa',
-  'dep.cve': 'cx-security',
-  'secrets.detected': 'cx-security',
-  'config.protection.violation': 'cx-security',
-  'pr.merged.no-docs': 'cx-docs-keeper',
-  'changelog.missing': 'cx-docs-keeper',
-  'readme.stale': 'cx-docs-keeper',
-  'adr.requested': 'cx-architect',
-  'arch.boundary.violated': 'cx-architect',
-  'regression.detected': 'cx-debugger',
-  'hang.detected': 'cx-debugger',
-  'release.candidate': 'cx-release-manager',
-  'version.bump.needed': 'cx-release-manager',
-  'backlog.stale': 'cx-product-manager',
-  'prd.requested': 'cx-product-manager',
-  'pr.opened': 'cx-reviewer',
-  'pr.ready-for-review': 'cx-reviewer',
-  'infra.change.requested': 'cx-platform-engineer',
-  'service.scale.event': 'cx-platform-engineer',
-  'design.requested': 'cx-designer',
-  'a11y.violation': 'cx-accessibility',
-  'research.requested': 'cx-researcher',
-  'evidence.requested': 'cx-researcher',
-  'eval.regression': 'cx-evaluator',
-  'trace.anomaly': 'cx-trace-reviewer',
-  'dep.license': 'cx-legal-compliance',
-  'privacy-policy.review': 'cx-legal-compliance',
-  'strategy.required': 'cx-business-strategist',
-  'plan.requested': 'cx-operations',
-  'research.gate.required': 'cx-rd-lead',
-};
+export { ownerForEvent, ownerForDoc } from './orchestration/routing-tables.mjs';
 
 const DOC_AUTHORING_PATTERNS = [
   { pattern: /\b(adr|architecture decision record)s?\b/i, docType: 'adr' },
@@ -160,7 +88,7 @@ export function detectDocAuthoringIntent(request = '') {
   if (!AUTHORING_VERBS.test(text)) return null;
   for (const { pattern, docType } of DOC_AUTHORING_PATTERNS) {
     if (pattern.test(text)) {
-      return { docType, owner: DOC_OWNERSHIP[docType] ?? null };
+      return { docType, owner: ownerForDoc(docType) };
     }
   }
   return null;
@@ -617,29 +545,13 @@ export function requestSignals(request = '', context = {}) {
 
 // Signal-driven proactive triggers. Returns a list of { specialist, reason }
 // pairs for specialists that should engage PRE-DISPATCH based on signals —
-// separate from the keyword-only paths in selectSpecialists. Empty when no
-// signal trips.
+// separate from the keyword-only paths in selectSpecialists. The watch
+// predicates and their specialist owners are declared in
+// specialists/registry.json (watchConditions) and evaluated by
+// orchestration/routing-tables.mjs.
 
 export function proactiveTriggers(signals) {
-  const triggers = [];
-  const { ambiguityScore, workCategory, authOrPayments, riskFlags, blastRadius, hasSuccessMetric, visualDeliverable } = signals;
-
-  if (ambiguityScore > 0.5 && workCategory === WORK_CATEGORIES.deep) {
-    triggers.push({ specialist: 'cx-product-manager', reason: 'clarify acceptance criteria (high ambiguity)' });
-  }
-  if (visualDeliverable || riskFlags.ui) {
-    triggers.push({ specialist: 'cx-designer', reason: 'visual deliverable / UI risk surface' });
-  }
-  if (authOrPayments && blastRadius !== 'narrow') {
-    triggers.push({ specialist: 'cx-security', reason: 'pre-dispatch threat model (auth/payments/PII + non-narrow blast radius)' });
-  }
-  if (riskFlags.architecture && !hasSuccessMetric) {
-    triggers.push({ specialist: 'cx-devil-advocate', reason: 'architecture change without stated success metric' });
-  }
-  if (blastRadius === 'wide') {
-    triggers.push({ specialist: 'cx-sre', reason: 'wide blast radius — operational readiness review' });
-  }
-  return triggers;
+  return evaluateWatchConditions(signals).map(({ specialist, reason }) => ({ specialist, reason }));
 }
 
 // User-visible dispatch summary: one line per specialist with the reason it

package/lib/parity.mjs

@@ -39,12 +39,22 @@ function adapterName(entry, prefix) {
   return entry.isPersona ? entry.name : `${prefix}-${entry.name}`;
 }
 
-function entriesForSurface(registry, surface) {
+function entriesForSurface(registry, surface, { scope = 'global' } = {}) {
   const prefix = registry.prefix || 'cx';
-  const entries = [
-    ...(registry.orchestrator ? [{ ...registry.orchestrator, isPersona: true }] : []),
-    ...(registry.specialists || []).map((s) => ({ ...s, isPersona: false })),
-  ];
+
+  // User-scope expects only the `construct` front-door agent. Specialists
+  // live with each Construct-managed project (apps/dashboard, apps/docs,
+  // and every other repo that runs `construct init`) — see the two-tier
+  // sync contract in scripts/sync-specialists.mjs.
+
+  const entries = scope === 'project'
+    ? [
+        ...(registry.orchestrator ? [{ ...registry.orchestrator, isPersona: true }] : []),
+        ...(registry.specialists || []).map((s) => ({ ...s, isPersona: false })),
+      ]
+    : registry.orchestrator
+      ? [{ ...registry.orchestrator, isPersona: true }]
+      : [];
 
   return entries
     .filter((e) => {
@@ -217,12 +227,31 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
   };
 }
 
+// Names a v1.0.10 install would have populated at user scope (claude, codex,
+// copilot) before the two-tier sync contract moved specialists to project
+// scope. Pulled from the live registry so the roster auto-updates as new
+// specialists land — anything in this set is "expected legacy state during
+// an upgrade," not real drift.
+function legacyUserScopeRoster(registry) {
+  const prefix = registry.prefix || 'cx';
+  const specialists = (registry.specialists || []).map((s) => `${prefix}-${s.name}`);
+  return new Set(specialists);
+}
+
 /**
  * Run parity checks across every supported surface. Never throws — returns a
  * structured report so callers can render it however they like.
+ *
+ * A surface that reports `drift` is reclassified to `legacy-install` when the
+ * only divergence is extras that all match the v1.0.10 user-scope roster — a
+ * dev box mid-upgrade from v1.0.10 (which populated cx-* specialists at user
+ * scope) to v1.0.13+ (project scope only). `legacy-install` rolls up to the
+ * same overall-ok bucket as `absent` so it doesn't hard-fail the gate; the
+ * summary still surfaces the `--fix-legacy-agents` hint.
  */
 export function checkParity({ rootDir = ROOT_DIR, homeDir = os.homedir() } = {}) {
   const registry = loadRegistry(rootDir);
+  const legacyRoster = legacyUserScopeRoster(registry);
   const surfaces = [
     checkClaude(registry, { homeDir }),
     checkOpenCode(registry, { homeDir }),
@@ -230,13 +259,16 @@ export function checkParity({ rootDir = ROOT_DIR, homeDir = os.homedir() } = {})
     checkCopilot(registry, { homeDir }),
     checkVSCode(registry, { homeDir }),
     checkCursor(registry, { homeDir }),
-  ];
+  ].map((s) => reclassifyLegacy(s, legacyRoster));
 
-  const ok = surfaces.every((s) => s.status === 'ok' || s.status === 'absent');
+  const ok = surfaces.every((s) => s.status === 'ok' || s.status === 'absent' || s.status === 'legacy-install');
   const summary = surfaces.map((s) => {
     if (s.status === 'absent') return `${s.surface}: not installed`;
     if (s.status === 'unreadable') return `${s.surface}: unreadable (${s.error})`;
     if (s.status === 'ok') return `${s.surface}: ok (${s.actualCount}/${s.expectedCount} ${s.kind})`;
+    if (s.status === 'legacy-install') {
+      return `${s.surface}: legacy v1.0.10 install — ${s.extra.length} stale ${s.kind} (run \`construct doctor --fix-legacy-agents\`)`;
+    }
     const parts = [];
     if (s.missing.length) parts.push(`missing: ${s.missing.join(', ')}`);
     if (s.extra.length) parts.push(`extra: ${s.extra.join(', ')}`);
@@ -245,3 +277,12 @@ export function checkParity({ rootDir = ROOT_DIR, homeDir = os.homedir() } = {})
 
   return { ok, surfaces, summary };
 }
+
+function reclassifyLegacy(surface, legacyRoster) {
+  if (surface.status !== 'drift') return surface;
+  if ((surface.missing?.length ?? 0) !== 0) return surface;
+  if (!surface.extra?.length) return surface;
+  const allLegacy = surface.extra.every((name) => legacyRoster.has(name));
+  if (!allLegacy) return surface;
+  return { ...surface, status: 'legacy-install' };
+}

package/lib/profiles/lifecycle.mjs

@@ -3,7 +3,7 @@
  *
  * 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
+ * code task. The 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.
@@ -16,12 +16,17 @@
  *
  * Health: per-profile observation and outcome counts pulled from the existing
  * stores, so profile health travels alongside the rest of the learning loops.
+ *
+ * Lifecycle events: createDraftProfile and archiveProfile each fire a
+ * profile.updated role event so subscribers can react to taxonomy changes
+ * without polling the filesystem.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { listProfiles, loadProfile } from './loader.mjs';
+import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
@@ -256,9 +261,21 @@ export function createDraftProfile({ cwd, id, displayName, seedRoles = [], seedD
     departmentPaths.push(p);
   }
 
+  emitProfileUpdated({ id, stage: 'draft', dir });
   return { dir, briefPath, draftPath, personaPaths, departmentPaths };
 }
 
+// Lifecycle bridge: emits profile.updated whenever the curated catalog gains
+// or loses an entry, so subscribers (none by default; project overlays can
+// bind) can react to taxonomy changes.
+
+function emitProfileUpdated(context) {
+  emitRoleEvent('profile.updated', {
+    summary: `profile ${context.stage}: ${context.id}`,
+    context,
+  });
+}
+
 /**
  * List drafts under .cx/profiles/. Returns [{ id, dir, hasProfile, hasBrief }].
  */
@@ -320,6 +337,7 @@ export function archiveProfile({ id, reason }) {
     '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'));
+  emitProfileUpdated({ id, stage: 'archived', dir: dstDir, reason: reason.trim() });
   return { archived: dstDir };
 }
 

package/lib/project-init-shared.mjs

@@ -11,14 +11,14 @@ import path from "node:path";
 
 import { stampFrontmatter } from "./doc-stamp.mjs";
 
-export function writeStampedIfMissing({ targetRoot, created, skipped, filePath, content, generator }) {
+export function writeStampedIfMissing({ targetRoot, created, skipped, filePath, content, generator, attribution = null }) {
   if (fs.existsSync(filePath)) {
     skipped.push(path.relative(targetRoot, filePath));
     return false;
   }
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const stamped = filePath.endsWith(".md")
-    ? stampFrontmatter(content, { generator })
+    ? stampFrontmatter(content, { generator, attribution })
     : content;
   fs.writeFileSync(filePath, stamped, "utf8");
   created.push(path.relative(targetRoot, filePath));
@@ -270,8 +270,8 @@ instead of letting it turn into a historical log. Durable task status belongs in
 `;
 }
 
-export function buildContextJson(projectName) {
-  return `${JSON.stringify({
+export function buildContextJson(projectName, { attribution = null } = {}) {
+  const base = {
     format: "json",
     savedAt: new Date().toISOString(),
     source: "construct-init",
@@ -280,5 +280,11 @@ export function buildContextJson(projectName) {
     recentDecisions: [],
     architectureNotes: [],
     openQuestions: [],
-  }, null, 2)}\n`;
+  };
+  if (attribution) {
+    base.createdBy = attribution.createdBy;
+    base.createdByAgent = attribution.createdByAgent;
+    base.createdAt = attribution.createdAt;
+  }
+  return `${JSON.stringify(base, null, 2)}\n`;
 }

package/lib/project-root.mjs

@@ -0,0 +1,104 @@
+/**
+ * lib/project-root.mjs — resolve "what Construct project am I in?" from any cwd.
+ *
+ * Writers that own per-project state (contract violations, audit reads, agent
+ * dispatches, intent verifications) call `resolveProjectScope()` to decide
+ * which `<project>/.cx/<file>.jsonl` to write to. When no project is
+ * detected, the call returns `null` and writers fall back to the legacy
+ * user-scope path (`~/.cx/<file>.jsonl`) so existing standalone hook
+ * invocations don't lose data.
+ *
+ * Writers that own cross-project telemetry (skill calls, role-pending,
+ * session cost) keep using `~/.cx/` but tag each entry with the
+ * `projectId` from `resolveProjectId()` so a reader can attribute the
+ * entry to a specific project later.
+ *
+ * The project marker is `.cx/` or `.construct/` at the project root. The
+ * lookup walks upward from cwd; the first ancestor matching either marker
+ * wins. Result is memoized per cwd so the hot path doesn't restat the
+ * filesystem on every append.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+
+const HOME = os.homedir();
+const MARKERS = ['.cx', '.construct'];
+const cache = new Map();   // cwd → { projectRoot, projectId, scope } | null
+
+/**
+ * Walk upward from `start` until a directory containing `.cx/` or
+ * `.construct/` is found. Returns the absolute project-root path or null.
+ * Stops at the filesystem root and at $HOME (so `~/.cx/` doesn't make
+ * the user's entire home directory look like a project).
+ */
+export function findProjectRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  const stop = path.resolve(HOME);
+  while (true) {
+    if (MARKERS.some((m) => fs.existsSync(path.join(dir, m)))) return dir;
+    if (dir === stop) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Deterministic short identifier for a project. Stable across sessions on
+ * the same machine, derived from the absolute project-root path. Useful for
+ * tagging cross-project telemetry entries (`projectId: "a7c4f2"`) without
+ * leaking the absolute filesystem path.
+ */
+export function projectIdFor(projectRoot) {
+  if (!projectRoot) return null;
+  return createHash('sha256').update(path.resolve(projectRoot)).digest('hex').slice(0, 12);
+}
+
+/**
+ * Resolve the project scope for a writer call site. Returns:
+ *   { projectRoot, projectId, cxDir }
+ *     when the cwd (or a parent) is a Construct project. `cxDir` is the
+ *     absolute path to `<projectRoot>/.cx/` (created on demand by callers).
+ *   null
+ *     when no project is detected; the caller should fall back to the
+ *     legacy user-scope path.
+ */
+export function resolveProjectScope(cwd = process.cwd()) {
+  if (cache.has(cwd)) return cache.get(cwd);
+  const projectRoot = findProjectRoot(cwd);
+  if (!projectRoot) {
+    cache.set(cwd, null);
+    return null;
+  }
+  const result = {
+    projectRoot,
+    projectId: projectIdFor(projectRoot),
+    cxDir: path.join(projectRoot, '.cx'),
+  };
+  cache.set(cwd, result);
+  return result;
+}
+
+/**
+ * For project-scoped writers: returns the `<project>/.cx/<basename>` path
+ * when cwd is inside a Construct project, otherwise the legacy
+ * `~/.cx/<basename>` path. Callers pass just the file basename; this helper
+ * resolves the directory side. ensureDir=true creates the parent dir.
+ */
+export function resolveProjectScopedPath(basename, { cwd, ensureDir = true } = {}) {
+  const scope = resolveProjectScope(cwd ?? process.cwd());
+  const dir = scope ? scope.cxDir : path.join(HOME, '.cx');
+  if (ensureDir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, basename);
+}
+
+/**
+ * Clear the memoization cache. Test-only — every other caller benefits
+ * from the cache surviving across calls in the same process.
+ */
+export function _resetCache() {
+  cache.clear();
+}

package/lib/roles/catalog.mjs

@@ -11,7 +11,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const REGISTRY_PATH = join(__dirname, '..', '..', 'agents', 'registry.json');
+const REGISTRY_PATH = join(__dirname, '..', '..', 'specialists', 'registry.json');
 
 let cached = null;