@geraldmaron/construct 1.0.11 → 1.0.14

package/lib/roles/event-bus.mjs

@@ -1,28 +1,34 @@
 /**
- * lib/roles/event-bus.mjs — append-only event log at ~/.cx/events.jsonl.
+ * lib/roles/event-bus.mjs — append-only event log per project.
  *
  * Hook processes emit failure/signal events here. The router + gateway read
  * recent events to decide escalation. Lines are rotated to keep the file
  * bounded. Fingerprint = sha1(type + project + first summary line) so the
  * same failure dedups across emits.
+ *
+ * Path resolution: events.jsonl lives at <project>/.cx/ when the cwd sits
+ * inside a Construct project, otherwise at ~/.cx/. Without per-project
+ * isolation, fingerprints from project A suppress real events in project B.
+ * Override the directory with CONSTRUCT_ROLES_ROOT for tests.
  */
 
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { resolveProjectScopedPath } from '../project-root.mjs';
 
 const MAX_LINES = 1000;
 
-function rootDir() {
-  return process.env.CONSTRUCT_ROLES_ROOT || join(homedir(), '.cx');
-}
 function eventsPath() {
-  return join(rootDir(), 'events.jsonl');
+  if (process.env.CONSTRUCT_ROLES_ROOT) {
+    return join(process.env.CONSTRUCT_ROLES_ROOT, 'events.jsonl');
+  }
+  return resolveProjectScopedPath('events.jsonl', { ensureDir: false });
 }
 function ensureDir() {
-  const r = rootDir();
-  if (!existsSync(r)) mkdirSync(r, { recursive: true });
+  const dir = dirname(eventsPath());
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
 export function fingerprintOf(type, project, summary) {
@@ -50,6 +56,20 @@ export function emit(eventType, payload = {}) {
   return line;
 }
 
+// Best-effort variant for writers that emit lifecycle events as a side
+// effect of their primary work (e.g. recommendation-store.createRecommendation,
+// docs-lifecycle.runDocsLifecycle). A bus write failure must not surface as
+// an error in the writer that just succeeded — the primary artifact already
+// landed. Returns the emitted line on success, null on failure.
+
+export function emitBestEffort(eventType, payload = {}) {
+  try {
+    return emit(eventType, payload);
+  } catch {
+    return null;
+  }
+}
+
 export function recent({ since = 0, type, fingerprint, limit = 200 } = {}) {
   const ep = eventsPath();
   if (!existsSync(ep)) return [];
@@ -76,4 +96,4 @@ function rotate() {
   } catch { /* rotate is best-effort */ }
 }
 
-export const _paths = { rootDir, eventsPath };
+export const _paths = { eventsPath };

package/lib/roles/router.mjs

@@ -1,19 +1,20 @@
 /**
  * lib/roles/router.mjs — pure event → persona resolver.
  *
- * Uses EVENT_OWNERSHIP from orchestration-policy and validates against
- * the loaded role manifest. Returns null (no owner) silently if the
- * event has no declared owner or the persona is not yet onboarded —
- * letting us declare ownership ahead of full wiring.
+ * Reads ownership from the declarative routing tables built off of
+ * specialists/registry.json, then validates against the loaded role
+ * manifest. Returns null silently when the event has no declared owner
+ * or the persona is not yet onboarded — letting ownership be declared
+ * ahead of full wiring.
  */
 
-import { EVENT_OWNERSHIP } from '../orchestration-policy.mjs';
+import { ownerForEvent } from '../orchestration/routing-tables.mjs';
 import { loadManifest, isOnboarded } from './manifest.mjs';
 
 export function route(event) {
   const type = event?.type;
   if (!type) return null;
-  const ownerCxId = EVENT_OWNERSHIP[type];
+  const ownerCxId = ownerForEvent(type);
   if (!ownerCxId) return null;
   const personaId = ownerCxId.replace(/^cx-/, '');
   if (!isOnboarded(personaId)) return null;
@@ -23,5 +24,5 @@ export function route(event) {
 }
 
 export function ownerOf(eventType) {
-  return EVENT_OWNERSHIP[eventType] || null;
+  return ownerForEvent(eventType);
 }

package/lib/server/index.mjs

@@ -36,7 +36,7 @@ const PORT = parseInt(process.env.PORT ?? '4242', 10);
 const BIND_HOST = process.env.BIND_HOST ?? (process.env.NODE_ENV === 'production' ? '0.0.0.0' : '127.0.0.1');
 
 const STATIC_DIR = join(__dirname, 'static');
-const REGISTRY_FILE = join(ROOT_DIR, 'agents', 'registry.json');
+const REGISTRY_FILE = join(ROOT_DIR, 'specialists', 'registry.json');
 const FEATURES_FILE = join(HOME, '.construct', 'features.json');
 const WORKFLOW_FILE = join(ROOT_DIR, 'plan.md');
 const SKILLS_DIR = join(ROOT_DIR, 'skills');
@@ -775,9 +775,9 @@ const server = createServer(async (req, res) => {
         try {
           const dir =
             category === 'contracts' || category === 'role-manifests'
-              ? join(root, 'agents')
+              ? join(root, 'specialists')
               : category === 'agents'
-                ? join(root, 'agents', 'prompts')
+                ? join(root, 'specialists', 'prompts')
                 : join(root, category);
           if (existsSync(dir)) {
             const walk = (rel = '') => {
@@ -1406,15 +1406,32 @@ const server = createServer(async (req, res) => {
         env: { ...process.env, NO_COLOR: '1' },
         timeout: 5000,
       });
+      // bd can return non-zero for legitimate reasons that don't warrant a
+      // server 500: bd not installed, dolt lock held by a concurrent bd, no
+      // .beads/ in cwd. Degrade gracefully — return an empty issue list with
+      // `degraded: true` so the dashboard UI shows "no beads" instead of
+      // breaking, and the dashboard-endpoints test (which sweeps every read
+      // endpoint for 5xx) stays green when bd's runtime is wobbly.
+
       if (result.status !== 0) {
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: `bd list failed: ${(result.stderr || result.stdout || '').slice(0, 300)}` }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          issues: [],
+          counts: { total: 0, byStatus: {}, byPriority: {} },
+          degraded: true,
+          reason: (result.stderr || result.stdout || 'bd list failed').slice(0, 300).trim(),
+        }));
         return;
       }
       let raw = [];
       try { raw = JSON.parse(result.stdout); } catch (parseErr) {
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: `bd list JSON parse failed: ${parseErr.message}` }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          issues: [],
+          counts: { total: 0, byStatus: {}, byPriority: {} },
+          degraded: true,
+          reason: `bd list JSON parse failed: ${parseErr.message}`,
+        }));
         return;
       }
       const issues = raw.map(obj => ({
@@ -1441,8 +1458,13 @@ const server = createServer(async (req, res) => {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ issues, counts: { total: issues.length, byStatus, byPriority } }));
     } catch (err) {
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: err.message }));
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        issues: [],
+        counts: { total: 0, byStatus: {}, byPriority: {} },
+        degraded: true,
+        reason: err.message,
+      }));
     }
     return;
   }

package/lib/server/static/index.html

@@ -1,15 +1 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Construct Dashboard</title>
-    <script type="module" crossorigin src="/assets/index-ab25c707.js"></script>
-    <link rel="stylesheet" href="/assets/index-f0c80a2b.css">
-  </head>
-  <body>
-    <div id="root"></div>
-    
-  </body>
-</html>
+<!DOCTYPE html><!--02hC8wDNvTNKwi4iN6D_t--><html lang="en" data-theme="dark" data-density="comfortable" data-motion="normal" class="__variable_629dad __variable_246ccd __variable_3c557b"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" href="/_next/static/media/22a5144ee8d83bca-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/bb3ef058b751a6ad-s.p.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="stylesheet" href="/_next/static/css/47a506ef57811fb9.css" data-precedence="next"/><link rel="preload" as="script" fetchPriority="low" href="/_next/static/chunks/webpack-8e0503f8a36190b3.js"/><script src="/_next/static/chunks/87c73c54-24122e7b92478d00.js" async=""></script><script src="/_next/static/chunks/18-1e25b5692ec1d26d.js" async=""></script><script src="/_next/static/chunks/main-app-07d82ec6c92d7402.js" async=""></script><script src="/_next/static/chunks/9664-af80478aa73ba424.js" async=""></script><script src="/_next/static/chunks/8144-da56a4a291c0b21a.js" async=""></script><script src="/_next/static/chunks/app/layout-1a2d2674aa220229.js" async=""></script><script src="/_next/static/chunks/app/page-2568fbdd2b0e1eca.js" async=""></script><meta name="next-size-adjust" content=""/><title>Construct — Dashboard</title><meta name="description" content="Local operations dashboard for Construct — approvals, health, knowledge, models, providers."/><script src="/_next/static/chunks/polyfills-42372ed130431b0a.js" noModule=""></script></head><body><div hidden=""><!--$--><!--/$--></div><div class="shell"><header class="topbar"><a class="brand" href="/"><div class="mark"></div><div class="name">Construct<em>dashboard</em></div></a><div class="search-wrap"><label class="search"><svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><line x1="21" y1="21" x2="16.5" y2="16.5"></line></svg><input readOnly="" placeholder="Search dashboard…"/><span class="kbd">⌘K</span></label></div><div class="top-actions"><button class="icon-btn" title="Toggle theme" type="button"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="4"></circle><line x1="12" y1="2" x2="12" y2="5"></line><line x1="12" y1="19" x2="12" y2="22"></line><line x1="2" y1="12" x2="5" y2="12"></line><line x1="19" y1="12" x2="22" y2="12"></line><line x1="4.5" y1="4.5" x2="6.5" y2="6.5"></line><line x1="17.5" y1="17.5" x2="19.5" y2="19.5"></line><line x1="4.5" y1="19.5" x2="6.5" y2="17.5"></line><line x1="17.5" y1="6.5" x2="19.5" y2="4.5"></line></svg></button><button class="icon-btn" title="Toggle density" type="button"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="3" y1="7" x2="21" y2="7"></line><line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="17" x2="21" y2="17"></line></svg></button><a class="icon-btn outlined" href="https://github.com/geraldmaron/construct" target="_blank" rel="noreferrer"><svg viewBox="0 0 24 24" width="14" height="14" fill="currentColor"><path d="M12 .5C5.65.5.5 5.66.5 12.02c0 5.09 3.29 9.4 7.86 10.92.58.1.79-.25.79-.55v-2.13c-3.2.7-3.87-1.37-3.87-1.37-.52-1.32-1.27-1.67-1.27-1.67-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.02 1.76 2.69 1.25 3.35.96.1-.74.4-1.25.73-1.54-2.55-.29-5.24-1.28-5.24-5.7 0-1.26.45-2.29 1.18-3.1-.12-.29-.51-1.46.11-3.04 0 0 .96-.31 3.16 1.18a10.9 10.9 0 0 1 5.74 0c2.2-1.49 3.16-1.18 3.16-1.18.62 1.58.23 2.75.12 3.04.74.81 1.18 1.84 1.18 3.1 0 4.43-2.69 5.41-5.25 5.69.41.36.78 1.05.78 2.13v3.16c0 .31.21.66.79.55A11.52 11.52 0 0 0 23.5 12.02C23.5 5.66 18.35.5 12 .5Z"></path></svg> <span style="font-size:11px">repo</span></a></div><div class="progress"></div></header><div class="body-grid"><aside class="sidebar"><div class="side-group"><div class="side-label">Overview</div><a class="side-link active" href="/"><span class="num">01</span><span>Home</span></a><a class="side-link" href="/doctor/"><span class="num">02</span><span>Doctor</span></a><a class="side-link" href="/resources/"><span class="num">03</span><span>Services</span></a></div><div class="side-group"><div class="side-label">Activity</div><a class="side-link" href="/audit/"><span class="num">01</span><span>Audit trail</span></a><a class="side-link" href="/snapshots/"><span class="num">02</span><span>Snapshots</span></a><a class="side-link" href="/performance/"><span class="num">03</span><span>Performance</span></a></div><div class="side-group"><div class="side-label">Work</div><a class="side-link" href="/approvals/"><span class="num">01</span><span>Approvals</span></a><a class="side-link" href="/workflow/"><span class="num">02</span><span>Workflow</span></a><a class="side-link" href="/beads/"><span class="num">03</span><span>Beads</span></a><a class="side-link" href="/artifacts/"><span class="num">04</span><span>Artifacts</span></a><a class="side-link" href="/intake/"><span class="num">05</span><span>Intake</span></a></div><div class="side-group"><div class="side-label">Specialists</div><a class="side-link" href="/agents/"><span class="num">01</span><span>Specialists</span></a><a class="side-link" href="/skills/"><span class="num">02</span><span>Skills</span></a><a class="side-link" href="/commands/"><span class="num">03</span><span>Slash commands</span></a><a class="side-link" href="/hooks/"><span class="num">04</span><span>Hooks</span></a><a class="side-link" href="/plugins/"><span class="num">05</span><span>Plugins</span></a></div><div class="side-group"><div class="side-label">Models &amp; Providers</div><a class="side-link" href="/models/"><span class="num">01</span><span>Models</span></a><a class="side-link" href="/providers/"><span class="num">02</span><span>Providers</span></a><a class="side-link" href="/mcp/"><span class="num">03</span><span>MCP servers</span></a></div><div class="side-group"><div class="side-label">Knowledge</div><a class="side-link" href="/knowledge/"><span class="num">01</span><span>Knowledge</span></a><a class="side-link" href="/editor/"><span class="num">02</span><span>Editor</span></a></div><div class="side-group"><div class="side-label">System</div><a class="side-link" href="/config/"><span class="num">01</span><span>Config</span></a><a class="side-link" href="/infrastructure/"><span class="num">02</span><span>Infrastructure</span></a></div><div class="side-foot">Local dashboard for Construct. Theme + density preferences persist.</div></aside><main class="main"><div class="page"><div class="eyebrow"><span class="dot"></span><span>overview · construct dashboard</span></div><h1 class="page-title">System state</h1><p class="page-lede">The runtime in one place. Approvals, services, model providers, knowledge corpus, and intake — each section deep-links to its dedicated surface.</p><div class="meta-strip"><span class="pill">mode: <!-- -->…</span><span>instance: <!-- -->…</span><span class="sep">·</span><span>embed: <!-- -->stopped</span></div><div class="body"><div class="hero-stats" style="margin-top:0;margin-bottom:24px"><div class="hero-stat"><span class="k">Services</span><span class="v">…</span><span style="display:block;font-size:11.5px;color:var(--muted);margin-top:4px">running</span></div><div class="hero-stat"><span class="k">Approvals</span><span class="v">…</span><span style="display:block;font-size:11.5px;color:var(--muted);margin-top:4px">pending</span></div><div class="hero-stat"><span class="k">Skills</span><span class="v">0</span><span style="display:block;font-size:11.5px;color:var(--muted);margin-top:4px">registered</span></div><div class="hero-stat"><span class="k">Commands</span><span class="v">0</span><span style="display:block;font-size:11.5px;color:var(--muted);margin-top:4px">slash</span></div></div><section class="section open"><button class="section-head" aria-expanded="true" type="button"><span class="chev"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><polyline points="9 6 15 12 9 18"></polyline></svg></span><span style="display:flex;flex-direction:column;gap:6px"><span class="section-num">01</span><span class="section-title">Pending approvals</span></span><span class="section-aside"><span>empty</span></span></button><div class="tldr-row"><div class="tldr"><b>TL;DR</b>Items waiting on a human gate. High-risk mutations (work item creation, merge, doc publish, config changes) land here.</div></div><div class="section-body-wrap"><div class="section-body"><div class="section-body-inner"><div class="body"><div style="padding:24px;text-align:center;color:var(--muted);font-family:var(--mono);font-size:12px">Loading…</div></div></div></div></div></section><section class="section"><button class="section-head" aria-expanded="false" type="button"><span class="chev"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><polyline points="9 6 15 12 9 18"></polyline></svg></span><span style="display:flex;flex-direction:column;gap:6px"><span class="section-num">02</span><span class="section-title">Services</span></span><span class="section-aside"><span>0/0 running</span></span></button><div class="tldr-row"><div class="tldr"><b>TL;DR</b>Local processes that back the runtime: Postgres, memory bridge, OpenCode bridge, dashboard, embed daemon.</div></div><div class="section-body-wrap"><div class="section-body"><div class="section-body-inner"><div class="body"><div style="padding:24px;text-align:center;color:var(--muted);font-family:var(--mono);font-size:12px">Loading…</div><p style="margin-top:12px"><a class="link" href="/resources/">Open services dashboard →</a></p></div></div></div></div></section><section class="section"><button class="section-head" aria-expanded="false" type="button"><span class="chev"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><polyline points="9 6 15 12 9 18"></polyline></svg></span><span style="display:flex;flex-direction:column;gap:6px"><span class="section-num">03</span><span class="section-title">Credentials</span></span><span class="section-aside"><span>0 tracked</span></span></button><div class="tldr-row"><div class="tldr"><b>TL;DR</b>Provider API keys, billing posture, and 1Password references. Set them in /providers.</div></div><div class="section-body-wrap"><div class="section-body"><div class="section-body-inner"><div class="body"><p style="margin-top:12px"><a class="link" href="/providers/">Manage providers →</a></p></div></div></div></div></section><section class="section"><button class="section-head" aria-expanded="false" type="button"><span class="chev"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><polyline points="9 6 15 12 9 18"></polyline></svg></span><span style="display:flex;flex-direction:column;gap:6px"><span class="section-num">04</span><span class="section-title">Quick links</span></span><span class="section-aside"></span></button><div class="tldr-row"><div class="tldr"><b>TL;DR</b>Deep links into every dashboard surface.</div></div><div class="section-body-wrap"><div class="section-body"><div class="section-body-inner"><div class="body"><div class="callout"><span class="clt-label">Where to next</span><div><p><a class="link" href="/doctor/">Doctor</a>,<!-- --> <a class="link" href="/knowledge/">Knowledge</a>,<!-- --> <a class="link" href="/intake/">Intake</a>,<!-- --> <a class="link" href="/workflow/">Workflow</a>,<!-- --> <a class="link" href="/agents/">Specialists</a>,<!-- --> <a class="link" href="/models/">Models</a>,<!-- --> <a class="link" href="/audit/">Audit</a>.</p></div></div></div></div></div></div></section></div></div><!--$--><!--/$--></main></div></div><script src="/_next/static/chunks/webpack-8e0503f8a36190b3.js" id="_R_" async=""></script><script>(self.__next_f=self.__next_f||[]).push([0])</script><script>self.__next_f.push([1,"1:\"$Sreact.fragment\"\n2:I[105,[\"9664\",\"static/chunks/9664-af80478aa73ba424.js\",\"8144\",\"static/chunks/8144-da56a4a291c0b21a.js\",\"7177\",\"static/chunks/app/layout-1a2d2674aa220229.js\"],\"AppShellClient\"]\n3:I[5341,[],\"\"]\n4:I[25,[],\"\"]\n5:I[1012,[],\"ClientPageRoot\"]\n6:I[9008,[\"9664\",\"static/chunks/9664-af80478aa73ba424.js\",\"8144\",\"static/chunks/8144-da56a4a291c0b21a.js\",\"8974\",\"static/chunks/app/page-2568fbdd2b0e1eca.js\"],\"default\"]\n9:I[5104,[],\"OutletBoundary\"]\nb:I[7158,[],\"AsyncMetadataOutlet\"]\nd:I[5104,[],\"ViewportBoundary\"]\nf:I[5104,[],\"MetadataBoundary\"]\n10:\"$Sreact.suspense\"\n12:I[4431,[],\"\"]\n:HL[\"/_next/static/media/22a5144ee8d83bca-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/bb3ef058b751a6ad-s.p.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/css/47a506ef57811fb9.css\",\"style\"]\n"])</script><script>self.__next_f.push([1,"0:{\"P\":null,\"b\":\"02hC8wDNvTNKwi4iN6D_t\",\"p\":\"\",\"c\":[\"\",\"\"],\"i\":false,\"f\":[[[\"\",{\"children\":[\"__PAGE__\",{}]},\"$undefined\",\"$undefined\",true],[\"\",[\"$\",\"$1\",\"c\",{\"children\":[[[\"$\",\"link\",\"0\",{\"rel\":\"stylesheet\",\"href\":\"/_next/static/css/47a506ef57811fb9.css\",\"precedence\":\"next\",\"crossOrigin\":\"$undefined\",\"nonce\":\"$undefined\"}]],[\"$\",\"html\",null,{\"lang\":\"en\",\"data-theme\":\"dark\",\"data-density\":\"comfortable\",\"data-motion\":\"normal\",\"suppressHydrationWarning\":true,\"className\":\"__variable_629dad __variable_246ccd __variable_3c557b\",\"children\":[\"$\",\"body\",null,{\"children\":[\"$\",\"$L2\",null,{\"nav\":[{\"label\":\"Overview\",\"items\":[{\"id\":\"home\",\"title\":\"Home\",\"href\":\"/\"},{\"id\":\"doctor\",\"title\":\"Doctor\",\"href\":\"/doctor\"},{\"id\":\"resources\",\"title\":\"Services\",\"href\":\"/resources\"}]},{\"label\":\"Activity\",\"items\":[{\"id\":\"audit\",\"title\":\"Audit trail\",\"href\":\"/audit\"},{\"id\":\"snapshots\",\"title\":\"Snapshots\",\"href\":\"/snapshots\"},{\"id\":\"performance\",\"title\":\"Performance\",\"href\":\"/performance\"}]},{\"label\":\"Work\",\"items\":[{\"id\":\"approvals\",\"title\":\"Approvals\",\"href\":\"/approvals\"},{\"id\":\"workflow\",\"title\":\"Workflow\",\"href\":\"/workflow\"},{\"id\":\"beads\",\"title\":\"Beads\",\"href\":\"/beads\"},{\"id\":\"artifacts\",\"title\":\"Artifacts\",\"href\":\"/artifacts\"},{\"id\":\"intake\",\"title\":\"Intake\",\"href\":\"/intake\"}]},{\"label\":\"Specialists\",\"items\":[{\"id\":\"agents\",\"title\":\"Specialists\",\"href\":\"/agents\"},{\"id\":\"skills\",\"title\":\"Skills\",\"href\":\"/skills\"},{\"id\":\"commands\",\"title\":\"Slash commands\",\"href\":\"/commands\"},{\"id\":\"hooks\",\"title\":\"Hooks\",\"href\":\"/hooks\"},{\"id\":\"plugins\",\"title\":\"Plugins\",\"href\":\"/plugins\"}]},{\"label\":\"Models \u0026 Providers\",\"items\":[{\"id\":\"models\",\"title\":\"Models\",\"href\":\"/models\"},{\"id\":\"providers\",\"title\":\"Providers\",\"href\":\"/providers\"},{\"id\":\"mcp\",\"title\":\"MCP servers\",\"href\":\"/mcp\"}]},{\"label\":\"Knowledge\",\"items\":[{\"id\":\"knowledge\",\"title\":\"Knowledge\",\"href\":\"/knowledge\"},{\"id\":\"editor\",\"title\":\"Editor\",\"href\":\"/editor\"}]},{\"label\":\"System\",\"items\":[{\"id\":\"config\",\"title\":\"Config\",\"href\":\"/config\"},{\"id\":\"infrastructure\",\"title\":\"Infrastructure\",\"href\":\"/infrastructure\"}]}],\"children\":[\"$\",\"$L3\",null,{\"parallelRouterKey\":\"children\",\"error\":\"$undefined\",\"errorStyles\":\"$undefined\",\"errorScripts\":\"$undefined\",\"template\":[\"$\",\"$L4\",null,{}],\"templateStyles\":\"$undefined\",\"templateScripts\":\"$undefined\",\"notFound\":[[[\"$\",\"title\",null,{\"children\":\"404: This page could not be found.\"}],[\"$\",\"div\",null,{\"style\":{\"fontFamily\":\"system-ui,\\\"Segoe UI\\\",Roboto,Helvetica,Arial,sans-serif,\\\"Apple Color Emoji\\\",\\\"Segoe UI Emoji\\\"\",\"height\":\"100vh\",\"textAlign\":\"center\",\"display\":\"flex\",\"flexDirection\":\"column\",\"alignItems\":\"center\",\"justifyContent\":\"center\"},\"children\":[\"$\",\"div\",null,{\"children\":[[\"$\",\"style\",null,{\"dangerouslySetInnerHTML\":{\"__html\":\"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}\"}}],[\"$\",\"h1\",null,{\"className\":\"next-error-h1\",\"style\":{\"display\":\"inline-block\",\"margin\":\"0 20px 0 0\",\"padding\":\"0 23px 0 0\",\"fontSize\":24,\"fontWeight\":500,\"verticalAlign\":\"top\",\"lineHeight\":\"49px\"},\"children\":404}],[\"$\",\"div\",null,{\"style\":{\"display\":\"inline-block\"},\"children\":[\"$\",\"h2\",null,{\"style\":{\"fontSize\":14,\"fontWeight\":400,\"lineHeight\":\"49px\",\"margin\":0},\"children\":\"This page could not be found.\"}]}]]}]}]],[]],\"forbidden\":\"$undefined\",\"unauthorized\":\"$undefined\"}]}]}]}]]}],{\"children\":[\"__PAGE__\",[\"$\",\"$1\",\"c\",{\"children\":[[\"$\",\"$L5\",null,{\"Component\":\"$6\",\"searchParams\":{},\"params\":{},\"promises\":[\"$@7\",\"$@8\"]}],null,[\"$\",\"$L9\",null,{\"children\":[\"$La\",[\"$\",\"$Lb\",null,{\"promise\":\"$@c\"}]]}]]}],{},null,false]},null,false],[\"$\",\"$1\",\"h\",{\"children\":[null,[[\"$\",\"$Ld\",null,{\"children\":\"$Le\"}],[\"$\",\"meta\",null,{\"name\":\"next-size-adjust\",\"content\":\"\"}]],[\"$\",\"$Lf\",null,{\"children\":[\"$\",\"div\",null,{\"hidden\":true,\"children\":[\"$\",\"$10\",null,{\"fallback\":null,\"children\":\"$L11\"}]}]}]]}],false]],\"m\":\"$undefined\",\"G\":[\"$12\",[]],\"s\":false,\"S\":true}\n"])</script><script>self.__next_f.push([1,"7:{}\n8:\"$0:f:0:1:2:children:1:props:children:0:props:params\"\n"])</script><script>self.__next_f.push([1,"e:[[\"$\",\"meta\",\"0\",{\"charSet\":\"utf-8\"}],[\"$\",\"meta\",\"1\",{\"name\":\"viewport\",\"content\":\"width=device-width, initial-scale=1\"}]]\na:null\n"])</script><script>self.__next_f.push([1,"c:{\"metadata\":[[\"$\",\"title\",\"0\",{\"children\":\"Construct — Dashboard\"}],[\"$\",\"meta\",\"1\",{\"name\":\"description\",\"content\":\"Local operations dashboard for Construct — approvals, health, knowledge, models, providers.\"}]],\"error\":null,\"digest\":\"$undefined\"}\n"])</script><script>self.__next_f.push([1,"11:\"$c:metadata\"\n"])</script></body></html>

package/lib/specialist-contracts-enforce.mjs

@@ -23,15 +23,26 @@
  * identify which producer or consumer is at fault.
  */
 
-import { existsSync, mkdirSync, statSync, readFileSync, appendFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, statSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { getContractById, validatePacket } from './specialist-contracts.mjs';
+import { appendBounded } from './logging/rotate.mjs';
+import { resolveProjectScopedPath } from './project-root.mjs';
 import { validatePostconditions } from './specialists/postconditions.mjs';
 
 const CX_DIR = join(homedir(), '.cx');
-const LOG_FILE = join(CX_DIR, 'contract-violations.jsonl');
+// contract-violations are PROJECT-SCOPED — a violation belongs to a
+// specific contract chain in a specific project. Resolves to
+// <project>/.cx/contract-violations.jsonl when inside a project, falling
+// back to the legacy ~/.cx path for standalone invocations. Resolved on
+// every call so cwd/HOME changes inside the same process (tests, harness
+// reuse) route correctly.
+
+function logFile() {
+  return resolveProjectScopedPath('contract-violations.jsonl', { ensureDir: false });
+}
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 
 export class ContractViolationError extends Error {
@@ -58,10 +69,11 @@ function readLastAgent() {
 
 function readPrevLineHash() {
   try {
-    if (!existsSync(LOG_FILE)) return null;
-    const size = statSync(LOG_FILE).size;
+    const file = logFile();
+    if (!existsSync(file)) return null;
+    const size = statSync(file).size;
     if (size === 0) return null;
-    const tail = readFileSync(LOG_FILE, 'utf8').slice(Math.max(0, size - 2048));
+    const tail = readFileSync(file, 'utf8').slice(Math.max(0, size - 2048));
     const lines = tail.split('\n').filter(Boolean);
     return lines.length === 0 ? null : sha256(lines[lines.length - 1]);
   } catch { return null; }
@@ -69,7 +81,8 @@ function readPrevLineHash() {
 
 function logViolation(contractId, direction, missing, packet, extra = {}) {
   try {
-    mkdirSync(CX_DIR, { recursive: true });
+    const file = logFile();
+    mkdirSync(dirname(file), { recursive: true });
     const record = {
       ts: new Date().toISOString(),
       agent: readLastAgent(),
@@ -80,7 +93,7 @@ function logViolation(contractId, direction, missing, packet, extra = {}) {
       prev_line_hash: readPrevLineHash(),
       ...extra,
     };
-    appendFileSync(LOG_FILE, JSON.stringify(record) + '\n', 'utf8');
+    appendBounded('contract-violations', file, JSON.stringify(record) + '\n');
   } catch { /* logging is best-effort */ }
 }
 
@@ -145,10 +158,11 @@ export function enforcePacket(contractId, packet, direction = 'input') {
  * Read recent violations from the chain log. Returns oldest-first.
  */
 export function recentViolations({ windowMs = 24 * 60 * 60 * 1000 } = {}) {
-  if (!existsSync(LOG_FILE)) return [];
+  const file = logFile();
+  if (!existsSync(file)) return [];
   try {
     const cutoff = Date.now() - windowMs;
-    return readFileSync(LOG_FILE, 'utf8')
+    return readFileSync(file, 'utf8')
       .trim()
       .split('\n')
       .filter(Boolean)

package/lib/status.mjs

@@ -664,7 +664,7 @@ export async function buildStatus({
   const resolvedDashboardPort = parsePort(dashboardPort ?? mergedEnv.DASHBOARD_PORT, 4242);
 
   const pkg = readJSON(join(rootDir, 'package.json')) ?? {};
-  const registry = readJSON(join(rootDir, 'agents', 'registry.json')) ?? {};
+  const registry = readJSON(join(rootDir, 'specialists', 'registry.json')) ?? {};
   const settings = readJSON(join(homeDir, '.claude', 'settings.json')) ?? {};
   const features = await checkAllFeatures({ homeDir, cwd, env: mergedEnv });
   const pluginRegistry = loadPluginRegistry({ cwd, homeDir, rootDir, env: mergedEnv });

package/lib/storage/backup.mjs

@@ -125,7 +125,7 @@ export async function createBackup({ includeSecrets = false, registryPath, destD
     }
 
     // ── Registry snapshot ─────────────────────────────────────────────────
-    const regPath = registryPath || path.join(process.cwd(), 'agents', 'registry.json');
+    const regPath = registryPath || path.join(process.cwd(), 'specialists', 'registry.json');
     if (fs.existsSync(regPath)) {
       const dst = path.join(stageDir, 'registry.json');
       fs.copyFileSync(regPath, dst);
@@ -274,7 +274,7 @@ export async function restoreBackup(archivePath, { yes = false } = {}) {
     // Restore registry.json
     const stagReg = path.join(extractDir, 'registry.json');
     if (fs.existsSync(stagReg)) {
-      const dest = path.join(process.cwd(), 'agents', 'registry.json');
+      const dest = path.join(process.cwd(), 'specialists', 'registry.json');
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       fs.copyFileSync(stagReg, dest);
       restored.push('registry.json');

package/lib/sync/skill-frontmatter.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/sync/skill-frontmatter.mjs — Build Anthropic Agent Skills frontmatter
+ * for SKILL.md files emitted by sync-specialists.
+ *
+ * Anthropic Skills require YAML frontmatter with at minimum `name` and
+ * `description`. The description gates skill selection — without it, the
+ * loader silently skips the file (the user-reported bug: 141 files dropped).
+ * Source Construct skills carry an HTML comment header with the description;
+ * extractSkillDescription pulls it out.
+ *
+ * Also exports a conservative stripLeadingFrontmatter helper so we never
+ * emit double-frontmatter when the source body already has its own block.
+ */
+
+const HTML_COMMENT_RE = /^<!--([\s\S]*?)-->/;
+// Matches the source skill comment header shape: `skills/path/foo.md (Title)
+// Use when X.\n...rest of comment...`. Group 1 captures the optional title,
+// group 2 captures all subsequent prose inside the comment. No /m flag — `$`
+// matches end of input, not end of line, so multi-line "Use when..." prose
+// is captured in full and firstSentence() picks the first terminator.
+
+const SOURCE_HEADER_RE = /^skills\/[\w./-]+\s*(?:\(([^)]+)\))?\s*([\s\S]*?)$/;
+
+// Anthropic Skills cap descriptions at 1024 chars; this cap is tighter so
+// the YAML stays readable in `construct skills list` output too.
+const DESCRIPTION_MAX = 240;
+
+export function buildSkillFrontmatter(name, sourceContent) {
+  const skillName = String(name).replace(/\//g, '.');
+  const description = extractSkillDescription(sourceContent) || `Construct skill: ${skillName}`;
+  const safeDescription = description.replace(/\n+/g, ' ').slice(0, DESCRIPTION_MAX).replace(/"/g, "'");
+  return `---\nname: ${skillName}\ndescription: "${safeDescription}"\n---\n`;
+}
+
+export function extractSkillDescription(content) {
+  if (!content) return null;
+  const commentMatch = content.match(HTML_COMMENT_RE);
+  if (commentMatch) {
+    const inner = commentMatch[1].trim();
+    const headerMatch = inner.match(SOURCE_HEADER_RE);
+    if (headerMatch) {
+      const prose = (headerMatch[2] || '').trim();
+      if (prose) return firstSentence(prose);
+    }
+    const lines = inner.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length >= 2) return firstSentence(lines.slice(1).join(' '));
+  }
+  const body = content.replace(HTML_COMMENT_RE, '').trim();
+  const paragraphs = body.split(/\n\s*\n/);
+  for (const p of paragraphs) {
+    const trimmed = p.trim();
+    if (trimmed.startsWith('#')) continue;
+    if (trimmed) return firstSentence(trimmed);
+  }
+  return null;
+}
+
+function firstSentence(text) {
+  const match = text.match(/^[\s\S]*?[.!?](?:\s|$)/);
+  return (match ? match[0] : text).trim();
+}
+
+export function stripLeadingFrontmatter(content) {
+  if (!content) return content;
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content;
+  const closeIdx = content.indexOf('\n---', 4);
+  if (closeIdx === -1) return content;
+  const afterClose = content.indexOf('\n', closeIdx + 1);
+  if (afterClose === -1) return '';
+  return content.slice(afterClose + 1);
+}

package/lib/telemetry/intent-verifications.mjs

@@ -15,6 +15,14 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+
+// intent-verifications are PROJECT-SCOPED — a verification belongs to a
+// specific routing decision in a specific project. DEFAULT_LOG_PATH stays
+// at the legacy user-scope location for back-compat with readers that
+// imported the constant; the writer below resolves per-call so each
+// invocation lands in the project's .cx/ when one is detected.
 
 export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'intent-verifications.jsonl');
 
@@ -38,7 +46,12 @@ export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'intent-verificat
  */
 export function logIntentVerification(event, opts = {}) {
   if (!event) return;
-  const logPath = opts.logPath || DEFAULT_LOG_PATH;
+  // Resolve per-call: callers that explicitly pass opts.logPath win;
+  // otherwise prefer the project-scoped path when cwd is inside a
+  // Construct project, falling back to DEFAULT_LOG_PATH (~/.cx) outside.
+
+  const logPath = opts.logPath
+    || resolveProjectScopedPath('intent-verifications.jsonl', { ensureDir: false });
   const entry = {
     ts: new Date().toISOString(),
     requestExcerpt: String(event.request || '').slice(0, 200),
@@ -57,9 +70,9 @@ export function logIntentVerification(event, opts = {}) {
 
   try {
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
-    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+    appendBounded('intent-verifications', logPath, JSON.stringify(entry) + '\n');
   } catch {
-    // Telemetry must never throw — the routing path doesn't await us anyway.
+    // Telemetry must never throw — the routing path doesn't await anyway.
   }
 }
 

package/lib/telemetry/skill-calls.mjs

@@ -17,6 +17,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScope } from '../project-root.mjs';
+
+// Skill calls are CROSS-PROJECT telemetry — a single log lets you see which
+// skills load hot across every project the user has run Construct in. Stays
+// at user scope; each entry is tagged with `projectId` so a reader can
+// attribute usage to a specific project without losing the global view.
 
 export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'skill-calls.jsonl');
 
@@ -37,10 +44,12 @@ export function logSkillCall(event, opts = {}) {
   if (!event || !event.skillId || !event.source) return;
 
   const logPath = opts.logPath || DEFAULT_LOG_PATH;
+  const scope = resolveProjectScope();
   const entry = {
     ts: new Date().toISOString(),
     skillId: event.skillId,
     source: event.source,
+    ...(scope?.projectId ? { projectId: scope.projectId } : {}),
     ...(event.callerContext ? { callerContext: event.callerContext } : {}),
     ...(event.latencyMs != null ? { latencyMs: event.latencyMs } : {}),
     ...(event.agentId ? { agentId: event.agentId } : {}),
@@ -50,10 +59,10 @@ export function logSkillCall(event, opts = {}) {
 
   try {
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
-    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+    appendBounded('skill-calls', logPath, JSON.stringify(entry) + '\n');
   } catch {
-    // Append-only telemetry; if the user's home dir is unwritable we silently
-    // skip rather than break the skill load that triggered us.
+    // Append-only telemetry; an unwritable home dir is a silent skip
+    // rather than a break on the skill load that triggered the call.
   }
 }