@geraldmaron/construct 1.3.0 → 1.3.1

package/lib/doctor/cli.mjs

@@ -101,16 +101,26 @@ export async function runCli(args) {
   }
 
   if (sub === 'consistency') {
+    const strict = args.some((a) => a === '--strict' || a === '--all' || a === '--debug');
     const { runAllChecks } = await import('./watchers/consistency.mjs');
     const result = await runAllChecks();
     const blocking = result.findings.filter((f) => f.severity === 'blocking');
     const warnings = result.findings.filter((f) => f.severity === 'warning');
 
+    // Default output carries only user-actionable signal; package/maintainer drift
+    // (tier 'internal') is gated behind --strict so a clean install reads clean.
+
+    const visibleWarnings = strict ? warnings : warnings.filter((f) => f.tier !== 'internal');
+    const internalWarnings = warnings.filter((f) => f.tier === 'internal');
+
     for (const p of result.passed) console.log(`  ✓  ${p.category.padEnd(18)} ${p.summary}`);
-    for (const w of warnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
+    for (const w of visibleWarnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
     for (const b of blocking) console.log(`  ✗  ${b.category.padEnd(18)} ${b.summary}`);
 
-    console.log(`\n${result.passed.length} category(s) clean, ${warnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    console.log(`\n${result.passed.length} category(s) clean, ${visibleWarnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    if (!strict && internalWarnings.length > 0) {
+      console.log(`  (+${internalWarnings.length} package-internal diagnostic(s) — run \`construct doctor consistency --strict\` to view)`);
+    }
     return blocking.length > 0 ? 1 : 0;
   }
 

package/lib/doctor/watchers/consistency.mjs

@@ -19,7 +19,7 @@
  * directory listings, no network.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { loadRegistry } from '../../registry/loader.mjs';
 import { join, dirname, resolve } from 'node:path';
 import os from 'node:os';
@@ -97,15 +97,32 @@ export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
   return { findings, passed };
 }
 
+// Drift categories split into two operator tiers. `actionable` findings are
+// project state a user can fix and surface by default. `internal` findings are
+// package/maintainer diagnostics about Construct's own registry and MCP wiring —
+// never user-actionable in a consumer project (this watcher resolves REPO_ROOT to
+// the installed package), so they stay behind `doctor consistency --strict`.
+
+const CATEGORY_TIERS = {
+  'mcp-drift': 'internal',
+  'roles-drift': 'internal',
+};
+
+function tierFor(category) {
+  return CATEGORY_TIERS[category] || 'actionable';
+}
+
 function collect(result, findings, passed, defaultCategory) {
   if (result.violations.length === 0) {
-    passed.push({ category: defaultCategory, summary: result.summary });
+    passed.push({ category: defaultCategory, summary: result.summary, tier: tierFor(defaultCategory) });
     return;
   }
   for (const v of result.violations) {
+    const category = v.category || defaultCategory;
     findings.push({
-      category: v.category || defaultCategory,
+      category,
       severity: v.severity || 'warning',
+      tier: v.tier || tierFor(category),
       summary: v.summary,
       target: v.target || null,
       details: v.details || null,
@@ -184,38 +201,51 @@ function checkMcpDrift({ repoRoot }) {
   }
 
   const serverSource = readFileSync(serverPath, 'utf8');
-  const dispatchedTools = new Set();
-  for (const m of serverSource.matchAll(/name === ['"]([a-z][a-z0-9_]*)['"]/g)) {
-    dispatchedTools.add(m[1]);
-  }
 
-  const exportedTools = new Set();
-  const entries = readdirSync(toolsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.endsWith('.mjs')) continue;
-    const src = readFileSync(join(toolsDir, entry.name), 'utf8');
-    for (const m of src.matchAll(/export (?:async )?function (\w+)/g)) {
-      exportedTools.add(camelToSnake(m[1]));
+  // Candidate tool handlers are exactly the identifiers server.mjs imports from
+  // ./tools/*.mjs. Tool modules also export private helpers (exec, readJson) that
+  // are never MCP tools; scanning every `export function` swept those into the
+  // signal. Scoping to the server's own imports is the real contract surface.
+
+  const importedHandlers = new Set();
+  for (const m of serverSource.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]\.\/tools\/[^'"]+['"]/g)) {
+    for (const ident of m[1].split(',')) {
+      const local = ident.trim().split(/\s+as\s+/).pop().trim();
+      if (local) importedHandlers.add(local);
     }
   }
 
-  for (const tool of exportedTools) {
-    if (KNOWN_NON_DISPATCH_TOOLS.has(tool)) continue;
-    if (!dispatchedTools.has(tool)) {
+  // A handler is wired when the dispatcher invokes it, regardless of the
+  // registered tool name. Handlers follow xxxTool→'xxx' and construct_xxx naming
+  // conventions, so matching exported names against `name === '<tool>'` strings is
+  // unreliable; matching the invoked identifier is convention-agnostic.
+
+  const invoked = new Set();
+  for (const m of serverSource.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g)) {
+    invoked.add(m[1]);
+  }
+
+  for (const handler of importedHandlers) {
+    const snake = camelToSnake(handler);
+    if (KNOWN_NON_DISPATCH_TOOLS.has(handler) || KNOWN_NON_DISPATCH_TOOLS.has(snake)) continue;
+    if (!invoked.has(handler)) {
       violations.push({
         category: 'mcp-drift',
         severity: 'warning',
-        target: tool,
-        summary: `MCP tool exported but not dispatched: ${tool}`,
+        tier: 'internal',
+        target: snake,
+        summary: `MCP tool handler imported but never dispatched: ${handler}`,
       });
     }
   }
 
-  return { summary: `mcp: ${dispatchedTools.size} dispatched, ${exportedTools.size} exported, ${violations.length} drift`, violations };
+  return { summary: `mcp: ${importedHandlers.size} handlers, ${violations.length} drift`, violations };
 }
 
+// Handlers the server may import for re-export or test surface but intentionally
+// never dispatches. Matched by camelCase identifier or snake_case form.
+
 const KNOWN_NON_DISPATCH_TOOLS = new Set([
-  // Internal helpers exported for tests but never wired through MCP.
   'workflow_status_bound',
   'create_needs_main_input_packet',
 ]);
@@ -263,21 +293,28 @@ function personaOwnersFromRegistry(registry) {
     owners.get(personaId).add(owner);
   }
 
+  // One registry entity owns a persona once. A specialist's id and its own name
+  // normalize to the same persona by design (cx-architect / architect), so they
+  // must share a single owner token keyed on the entity — otherwise every
+  // specialist self-collides and reports a spurious "ambiguous" drift. Genuine
+  // ambiguity (two distinct specialists, or a specialist and the orchestrator,
+  // normalizing to the same persona) still yields owners.size > 1.
+
   for (const [specId, spec] of Object.entries(registry?.specialists || {})) {
     addOwner(specId, `specialist:${specId}`);
-    addOwner(spec?.name, `specialist:${specId}:name`);
+    addOwner(spec?.name, `specialist:${specId}`);
   }
 
   if (Array.isArray(registry?.specialists)) {
     for (const spec of registry.specialists) {
       const owner = `specialist:${spec?.id || spec?.name || 'unknown'}`;
       addOwner(spec?.id, owner);
-      addOwner(spec?.name, `${owner}:name`);
+      addOwner(spec?.name, owner);
     }
   }
 
-  addOwner(registry?.orchestrator?.id, 'orchestrator:id');
-  addOwner(registry?.orchestrator?.name, 'orchestrator:name');
+  addOwner(registry?.orchestrator?.id, 'orchestrator');
+  addOwner(registry?.orchestrator?.name, 'orchestrator');
   return owners;
 }
 

package/lib/mcp/server.mjs

@@ -38,7 +38,7 @@ import {
 } from './tools/storage.mjs';
 import {
   listSkills, getSkill, searchSkills, getTemplate, listTemplates,
-  agentContract, brokerCheck, orchestrationPolicy, workerRun, listTeams, getTeam, suggestSkillsTool,
+  agentContract, brokerCheck, orchestrationPolicy, workerRun, listTeams, suggestSkillsTool,
 } from './tools/skills.mjs';
 import {
   workflowInit, workflowAddTask, workflowUpdateTask,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",

package/scripts/sync-specialists.mjs

@@ -1002,13 +1002,20 @@ ${buildPrompt(entry, allEntries, "claude")}
  * Rewrite the home-mode hook command pattern
  *   node "$HOME/.config/construct/lib/hooks/<name>.mjs"
  * into the project-portable form
- *   node .construct/run.mjs hook <name>
+ *   node "${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook <name>
  * so the resulting settings.json works on any clone where the project ships
  * the .construct/ launcher (committed by `npm install`'s postinstall or by
  * `construct init`). The launcher resolves Construct via node_modules → npx
  * → globally-installed CLI → cached binary → docker, in that order, so it
  * works for non-Node ecosystems too. Other commands (inline node -e
  * snippets, npx block-no-verify@…) are left untouched.
+ *
+ * The `${CLAUDE_PROJECT_DIR:-.}` anchor matters: Claude Code invokes hooks with
+ * a working directory that is not guaranteed to be the project root (observed:
+ * $HOME), and a bare relative `.construct/run.mjs` then fails with MODULE_NOT_FOUND
+ * at node:internal/modules/cjs/loader. CLAUDE_PROJECT_DIR is the project root Claude
+ * Code exports to every hook (same var lib/hooks/*.mjs already read); the `:-.`
+ * fallback preserves the prior relative behavior wherever the var is unset.
  */
 function makeHooksPortable(hooksJson) {
   // Operate on the in-memory object so we don't fight JSON string escaping.
@@ -1017,7 +1024,7 @@ function makeHooksPortable(hooksJson) {
     const m = cmd.match(/^node\s+"?\$HOME\/\.config\/construct\/lib\/hooks\/([a-z0-9-]+)\.mjs"?\s*(.*)$/);
     if (!m) return cmd;
     const [, name, rest] = m;
-    return `node .construct/run.mjs hook ${name}${rest ? ' ' + rest.trim() : ''}`;
+    return `node "\${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook ${name}${rest ? ' ' + rest.trim() : ''}`;
   };
 
   const walk = (node) => {