@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/observation-store.mjs

@@ -112,10 +112,12 @@ function logCapDrop(rootDir, kind, dropped, total) {
 function writeIndex(rootDir, entries) {
   ensureDir(obsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX);
-  if (entries.length > MAX_INDEX) {
-    logCapDrop(rootDir, 'observation-index', entries.length - MAX_INDEX, entries.length);
+  const dropped = Math.max(0, entries.length - MAX_INDEX);
+  if (dropped > 0) {
+    logCapDrop(rootDir, 'observation-index', dropped, entries.length);
   }
   fs.writeFileSync(indexPath(rootDir), JSON.stringify(trimmed, null, 2) + '\n');
+  return { dropped };
 }
 
 function readVectors(rootDir) {
@@ -130,10 +132,12 @@ function readVectors(rootDir) {
 
 function writeVectors(rootDir, records) {
   ensureDir(obsDir(rootDir), rootDir);
-  if (records.length > MAX_INDEX) {
-    logCapDrop(rootDir, 'observation-vectors', records.length - MAX_INDEX, records.length);
+  const dropped = Math.max(0, records.length - MAX_INDEX);
+  if (dropped > 0) {
+    logCapDrop(rootDir, 'observation-vectors', dropped, records.length);
   }
   fs.writeFileSync(vectorsPath(rootDir), JSON.stringify(records, null, 2) + '\n');
+  return { dropped };
 }
 
 /**
@@ -188,6 +192,7 @@ export async function addObservation(rootDir, {
     JSON.stringify(record, null, 2) + '\n',
   );
 
+  let indexDropped = 0;
   withFileLockSync(indexPath(rootDir), () => {
     const index = readIndex(rootDir);
     index.unshift({
@@ -198,8 +203,12 @@ export async function addObservation(rootDir, {
       project: record.project,
       createdAt: now,
     });
-    writeIndex(rootDir, index);
+    indexDropped = writeIndex(rootDir, index).dropped;
   });
+  if (indexDropped > 0) {
+    record.capDropped = indexDropped;
+    process.stderr.write(`[observation-store] observation cap reached: ${indexDropped} oldest entries evicted (cap=${MAX_INDEX})\n`);
+  }
 
   // Try SQL storage with neural embeddings
   try {

package/lib/ollama-manager.mjs

@@ -6,10 +6,26 @@
  * pulling new models, and configuring Ollama as a provider.
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
+// argv-array form for every shell-out: no shell interpolation, model names and
+// JSON bodies are passed as discrete arguments / stdin so user-supplied values
+// cannot break out of the command.
+
+function curlGet(url, { timeout } = {}) {
+  return execFileSync('curl', ['-s', url], { encoding: 'utf8', timeout });
+}
+
+function curlPost(url, body, { timeout } = {}) {
+  return execFileSync('curl', ['-s', url, '--data-binary', '@-'], {
+    encoding: 'utf8',
+    timeout,
+    input: typeof body === 'string' ? body : JSON.stringify(body),
+  });
+}
+
 const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST || 'http://localhost:11434';
 
 /**
@@ -17,14 +33,11 @@ const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST |
  */
 export function checkOllamaStatus() {
   try {
-    execSync('which ollama', { stdio: 'pipe' });
+    execFileSync('which', ['ollama'], { stdio: 'pipe' });
     const installed = true;
-    
+
     try {
-      const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/tags`, { 
-        encoding: 'utf8',
-        timeout: 3000
-      });
+      const response = curlGet(`${OLLAMA_BASE_URL}/api/tags`, { timeout: 3000 });
       const data = JSON.parse(response);
       return {
         installed,
@@ -54,10 +67,7 @@ export function checkOllamaStatus() {
  */
 export function listModels() {
   try {
-    const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/tags`, { 
-      encoding: 'utf8',
-      timeout: 5000
-    });
+    const response = curlGet(`${OLLAMA_BASE_URL}/api/tags`, { timeout: 5000 });
     const data = JSON.parse(response);
     return data.models || [];
   } catch (e) {
@@ -71,7 +81,7 @@ export function listModels() {
 export function pullModel(modelName, { verbose = false } = {}) {
   console.log(`Pulling ${modelName}...`);
   try {
-    const output = execSync(`ollama pull ${modelName}`, {
+    const output = execFileSync('ollama', ['pull', modelName], {
       encoding: 'utf8',
       stdio: verbose ? 'inherit' : 'pipe'
     });
@@ -86,7 +96,7 @@ export function pullModel(modelName, { verbose = false } = {}) {
  */
 export function removeModel(modelName) {
   try {
-    execSync(`ollama rm ${modelName}`, { encoding: 'utf8' });
+    execFileSync('ollama', ['rm', modelName], { encoding: 'utf8' });
     return { success: true };
   } catch (e) {
     return { success: false, error: e.message };
@@ -98,10 +108,7 @@ export function removeModel(modelName) {
  */
 export function showModel(modelName) {
   try {
-    const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/show -d '{"name":"${modelName}"}'`, {
-      encoding: 'utf8',
-      timeout: 5000
-    });
+    const response = curlPost(`${OLLAMA_BASE_URL}/api/show`, { name: modelName }, { timeout: 5000 });
     return JSON.parse(response);
   } catch (e) {
     throw new Error(`Failed to fetch model details: ${e.message}`);
@@ -113,14 +120,11 @@ export function showModel(modelName) {
  */
 export function testModel(modelName, prompt = 'Say hello in one sentence.') {
   try {
-    const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/generate -d '${JSON.stringify({
-      model: modelName,
-      prompt: prompt,
-      stream: false
-    })}'`, {
-      encoding: 'utf8',
-      timeout: 30000
-    });
+    const response = curlPost(
+      `${OLLAMA_BASE_URL}/api/generate`,
+      { model: modelName, prompt, stream: false },
+      { timeout: 30000 },
+    );
     const data = JSON.parse(response);
     return {
       success: true,
@@ -371,7 +375,7 @@ async function cmdOllamaSetup(args) {
     if (autoYes || process.platform === 'darwin') {
       console.log('Installing via Homebrew...');
       try {
-        execSync('brew install ollama', { stdio: 'inherit' });
+        execFileSync('brew', ['install', 'ollama'], { stdio: 'inherit' });
         console.log('✅ Ollama installed');
       } catch (e) {
         console.error('❌ Installation failed. Please install manually: https://ollama.com');
@@ -390,11 +394,11 @@ async function cmdOllamaSetup(args) {
     console.log('⚠️  Ollama is not running');
     console.log('Starting Ollama service...');
     try {
-      execSync('brew services start ollama', { stdio: 'pipe' });
+      execFileSync('brew', ['services', 'start', 'ollama'], { stdio: 'pipe' });
       console.log('✅ Ollama service started');
       // Wait for it to be ready
       console.log('Waiting for Ollama to be ready...');
-      execSync('sleep 3');
+      execFileSync('sleep', ['3']);
     } catch (e) {
       console.log('You can start it manually with: ollama serve');
     }

package/lib/opencode-config.mjs

@@ -47,8 +47,15 @@ export function sanitizeOpenCodeConfig(config) {
 }
 
 export function writeOpenCodeConfig(config, file = findOpenCodeConfigPath()) {
+  // Treat the canonical home config as the default target; any explicit path
+  // outside the canonical home dir (e.g. project-scoped .opencode/config.json)
+  // is honored as-is so per-project sync writes to the right tree.
+
   const canonical = getCanonicalOpenCodeConfigPath();
-  fs.mkdirSync(path.dirname(canonical), { recursive: true });
-  fs.writeFileSync(canonical, `${JSON.stringify(sanitizeOpenCodeConfig(config), null, 2)}\n`, "utf8");
-  return canonical;
+  const target = file && path.resolve(file) !== path.resolve(findOpenCodeConfigPath())
+    ? file
+    : canonical;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(sanitizeOpenCodeConfig(config), null, 2)}\n`, "utf8");
+  return target;
 }

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