@geraldmaron/construct 1.0.12 → 1.0.14

package/README.md

@@ -93,6 +93,12 @@ Every code mutation runs through enforcement. No secrets committed, tests green,
 
 Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.mdx`](./docs/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
 
+## `.cx/` is local-only runtime state
+
+`construct init` writes a runtime state tree at `.cx/` inside the project root: observations, sessions, vector index, intake packets, task graphs, and traces. **It's local-only and must never be committed.** `construct init` adds `.cx/` to your project's `.gitignore` automatically (idempotent: it won't double-add if you already have it). Daily trace shards (`.cx/traces/<date>.jsonl`) cap at 100 MB and rotate to `<date>.<n>.jsonl` so a stray commit never crosses GitHub's single-file limit. Override the cap with `CONSTRUCT_TRACE_MAX_MB`.
+
+The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon.log`. That log rotates every minute at 50 MB and keeps 5 gzipped segments by default; override via `CONSTRUCT_EMBED_LOG_MAX_MB` and `CONSTRUCT_EMBED_LOG_MAX_SEGMENTS`.
+
 ## Core commands
 
 <!-- AUTO:commands -->
@@ -215,16 +221,16 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 <!-- AUTO:structure -->
 ```text
 construct/
-├── apps             User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)
+├── apps             User-facing apps shipped from this repo (e.g. apps/docs/, the Next.js docs site)
 ├── bin              CLI entrypoint (`construct`)
 ├── commands         Command prompt assets
 ├── config
-├── dashboard
 ├── db
 ├── deploy
 ├── docs             Architecture notes, runbooks, and documentation contract
 ├── examples
 ├── lib              Core runtime: CLI, hooks, MCP, status, sync, workflow
+├── packages
 ├── personas         Persona prompt definitions
 ├── platforms
 ├── profiles

package/bin/construct

@@ -416,11 +416,190 @@ async function cmdDoctor() {
     return;
   }
 
+  // --fix-* flags drive auto-remediation for legacy state left behind by
+  // pre-2.0 installs. Layer-2 update triggers (npm i -g postinstall, brew
+  // upgrade) normally handle this; --fix-* is the manual recovery path.
+  // --fix-all runs every available fix.
+
+  const wantsFixAll = args.includes('--fix-all') || args.includes('--fix');
+  const wantsFixGitignore = wantsFixAll || args.includes('--fix-gitignore');
+  const wantsFixLegacyAgents = wantsFixAll || args.includes('--fix-legacy-agents');
+  const wantsFixEmbedLog = wantsFixAll || args.includes('--fix-embed-log');
+  const wantsFixMigrateState = wantsFixAll || args.includes('--fix-migrate-state');
+
   const checks = [];
   const add = (label, pass, optional = false) => checks.push({ label, pass, optional });
   add('registry.json exists', fs.existsSync(path.join(ROOT_DIR, 'specialists', 'registry.json')));
   add('sync-specialists.mjs exists', fs.existsSync(path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs')));
 
+  // Dashboard static build output. The Next.js app under apps/dashboard
+  // emits a static export into lib/server/static/ via its postbuild script;
+  // an empty static dir means lib/server/index.mjs will serve 404s.
+
+  const dashboardIndex = path.join(ROOT_DIR, 'lib', 'server', 'static', 'index.html');
+  add('Dashboard built (lib/server/static/index.html)', fs.existsSync(dashboardIndex));
+
+  // Project .gitignore must cover .cx/. Auto-fix via --fix-gitignore.
+  // Only checks when cwd looks like a Construct project (has .cx/ or
+  // .construct/); non-project cwds get no warning.
+
+  const cwd = process.cwd();
+  const isProject = fs.existsSync(path.join(cwd, '.cx')) || fs.existsSync(path.join(cwd, '.construct'));
+  if (isProject) {
+    const giPath = path.join(cwd, '.gitignore');
+    const giContent = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+    const lines = giContent.split('\n').map((l) => l.trim());
+    const cxIgnored = lines.some((l) => l === '.cx' || l === '.cx/' || l === '.cx/**' || l === '*' || l === '**');
+    if (!cxIgnored && wantsFixGitignore) {
+      const prefix = giContent.length === 0 || giContent.endsWith('\n') ? '' : '\n';
+      fs.writeFileSync(giPath, giContent + `${prefix}\n# Construct runtime state — local-only, never source\n.cx/\n`, 'utf8');
+      println(`  fix: appended .cx/ to ${path.relative(cwd, giPath)}`);
+      add('Project .gitignore covers .cx/', true);
+    } else {
+      add('Project .gitignore covers .cx/' + (cxIgnored ? '' : ' (run `construct doctor --fix-gitignore` to add)'), cxIgnored);
+    }
+  }
+
+  // Legacy cx-* files at user scope. Layer-2 (npm postinstall, brew
+  // upgrade) sweeps these via `construct sync --global`; this check is
+  // the manual safety net. Counts files matching a registered specialist
+  // name across Claude / Codex / Copilot user-scope dirs.
+
+  const userHome = HOME;
+  const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'specialists', 'registry.json'), 'utf8'));
+  const specialistSet = new Set((registry.specialists ?? []).map((s) => `cx-${s.name}`));
+  const legacyTargets = [
+    { dir: path.join(userHome, '.claude', 'agents'), ext: '.md' },
+    { dir: path.join(userHome, '.codex', 'agents'), ext: '.toml' },
+    { dir: path.join(userHome, '.github', 'prompts'), ext: '.prompt.md' },
+  ];
+  let legacyCount = 0;
+  for (const t of legacyTargets) {
+    if (!fs.existsSync(t.dir)) continue;
+    for (const f of fs.readdirSync(t.dir)) {
+      if (!f.endsWith(t.ext)) continue;
+      const base = f.slice(0, -t.ext.length);
+      if (specialistSet.has(base)) legacyCount++;
+    }
+  }
+  if (legacyCount > 0 && wantsFixLegacyAgents) {
+    const syncScript = path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs');
+    const result = spawnSync(process.execPath, [syncScript, '--global'], { stdio: 'pipe', encoding: 'utf8' });
+    if (result.status === 0) {
+      println(`  fix: swept ${legacyCount} legacy cx-* file(s) from user scope via construct sync --global`);
+      add('No legacy cx-* files at user scope', true);
+    } else {
+      add(`Legacy cx-* sweep failed: ${result.stderr?.substring(0, 200)}`, false);
+    }
+  } else {
+    // Soft-warn instead of hard-fail: legacy v1.0.10 cx-* files are an
+    // expected upgrade-state, not real drift. The hint is what matters;
+    // the fix is one --fix-legacy-agents run away and CI never sees this.
+    // Mirrors the parity check's legacy-install reclassification.
+
+    add(
+      legacyCount === 0
+        ? 'No legacy cx-* files at user scope'
+        : `Legacy cx-* files at user scope: ${legacyCount} (run \`construct doctor --fix-legacy-agents\` to sweep)`,
+      true,
+      legacyCount !== 0,
+    );
+  }
+
+  // Pre-push bypass frequency. Every honored CONSTRUCT_SKIP_PREPUSH /
+  // CONSTRUCT_ALLOW_CLAUDE_PUSH / CONSTRUCT_SKIP_PR_LINT writes a JSONL
+  // entry to ~/.construct/audit/prepush-bypass.log. Surfacing frequent
+  // usage here is the early warning that the gate is the wrong shape —
+  // the alternative is letting the bypass quietly become the default.
+
+  const bypassLogPath = path.join(userHome, '.construct', 'audit', 'prepush-bypass.log');
+  if (fs.existsSync(bypassLogPath)) {
+    try {
+      const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
+      const recent = fs.readFileSync(bypassLogPath, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+        .filter((e) => e && Date.parse(e.ts) >= cutoff);
+      const BYPASS_WARN_THRESHOLD = Number(process.env.CONSTRUCT_DOCTOR_BYPASS_WARN) || 3;
+      if (recent.length >= BYPASS_WARN_THRESHOLD) {
+        add(
+          `Pre-push bypasses in last 7 days: ${recent.length} (gate may be wrong-sized — see ${bypassLogPath})`,
+          false,
+          true,
+        );
+      } else {
+        add(`Pre-push bypasses in last 7 days: ${recent.length}`, true);
+      }
+    } catch { /* audit log read is best-effort */ }
+  } else {
+    add('Pre-push bypass log not present (no bypasses honored yet)', true);
+  }
+
+  // Embed daemon log size. The daemon's own scheduler rotates every
+  // minute at 50MB, but a freshly-upgraded install with a 34GB legacy
+  // log shouldn't wait 60s. --fix-embed-log forces rotation now.
+
+  const embedLogPath = path.join(userHome, '.cx', 'runtime', 'embed-daemon.log');
+  if (fs.existsSync(embedLogPath)) {
+    const sizeMb = fs.statSync(embedLogPath).size / 1024 / 1024;
+    const FORCE_THRESHOLD_MB = Number(process.env.CONSTRUCT_DOCTOR_EMBED_LOG_FORCE_MB) || 500;
+    if (sizeMb > FORCE_THRESHOLD_MB && wantsFixEmbedLog) {
+      const { rotateIfOversized } = await import('../lib/logging/rotate.mjs');
+      println(`  fix: rotating ${sizeMb.toFixed(0)}MB embed-daemon.log (gzipping may take a moment)…`);
+      const start = Date.now();
+      const seg = await rotateIfOversized(embedLogPath, { maxBytes: 1, maxSegments: 5, gzip: true });
+      const elapsed = ((Date.now() - start) / 1000).toFixed(0);
+      println(`  fix: rotated to ${path.basename(seg)} in ${elapsed}s`);
+      add('Embed daemon log size sane', true);
+    } else {
+      const label = sizeMb > FORCE_THRESHOLD_MB
+        ? `Embed daemon log oversized: ${sizeMb.toFixed(0)}MB (run \`construct doctor --fix-embed-log\` to rotate now)`
+        : `Embed daemon log size: ${sizeMb.toFixed(1)}MB`;
+      add(label, sizeMb <= FORCE_THRESHOLD_MB);
+    }
+  }
+
+  // Legacy ~/.cx/<project-scoped>.jsonl files left over from before the
+  // cross-project state isolation refactor. Four files moved from user
+  // scope to <project>/.cx/: contract-violations, audit-reads, agent-log,
+  // intent-verifications. Pre-refactor data still sits at ~/.cx/ where it
+  // mixed every project together. --fix-migrate-state archives them to
+  // ~/.cx/legacy/<name>.<ts>.jsonl so the new writers start fresh; the
+  // legacy data stays readable for forensics.
+
+  const projectScopedNames = [
+    'contract-violations.jsonl',
+    'audit-reads.jsonl',
+    'agent-log.jsonl',
+    'intent-verifications.jsonl',
+  ];
+  const legacyState = projectScopedNames
+    .map((name) => ({ name, path: path.join(userHome, '.cx', name) }))
+    .filter((p) => fs.existsSync(p.path) && fs.statSync(p.path).size > 0);
+
+  if (legacyState.length > 0 && wantsFixMigrateState) {
+    const archiveDir = path.join(userHome, '.cx', 'legacy');
+    fs.mkdirSync(archiveDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const moved = [];
+    for (const { name, path: src } of legacyState) {
+      const dest = path.join(archiveDir, `${name.replace('.jsonl', '')}.${ts}.jsonl`);
+      fs.renameSync(src, dest);
+      moved.push(path.basename(dest));
+    }
+    println(`  fix: archived ${moved.length} legacy user-scope file(s) to ~/.cx/legacy/`);
+    for (const m of moved) println(`         → ${m}`);
+    add('No legacy user-scope project-state files', true);
+  } else {
+    add(
+      legacyState.length === 0
+        ? 'No legacy user-scope project-state files'
+        : `Legacy user-scope project-state files: ${legacyState.length} (run \`construct doctor --fix-migrate-state\` to archive)`,
+      legacyState.length === 0,
+    );
+  }
+
   // Tier model selection. Construct ships with no default — at least
   // one tier must be configured (registry.json primary OR CX_MODEL_*
   // env override) before any LLM-backed workflow can run.
@@ -704,7 +883,11 @@ async function cmdDoctor() {
     try {
       const { checkParity } = await import('../lib/parity.mjs');
       const parity = checkParity({ rootDir: ROOT_DIR, homeDir: HOME });
-      add(`Cross-surface adapter parity (${parity.summary.join(' · ')})`, parity.ok);
+      // Legacy-install rolls up to ok (so the gate doesn't hard-fail during
+      // a v1.0.10 → v1.0.13+ upgrade) but renders as a warning so the
+      // --fix-legacy-agents hint stays visible.
+      const hasLegacy = parity.surfaces.some((s) => s.status === 'legacy-install');
+      add(`Cross-surface adapter parity (${parity.summary.join(' · ')})`, parity.ok, hasLegacy);
     } catch {
       add('Cross-surface adapter parity', false);
     }
@@ -1643,6 +1826,10 @@ async function printIntakeHelp() {
   println('  construct intake done <id> [--notes=…] [--output=<path>] [--no-output=<rejected|deferred|merged>]');
   println('                                       Mark a pending packet processed. --output stamps intake_id + confidence into the artifact frontmatter (provenance).');
   println('  construct intake skip <id> [--reason=…]   Mark a pending packet skipped (preserves audit trail).');
+  println('  construct intake process [--dry-run] [--wait[=<sec>]]');
+  println('                                       One-shot inbox sweep — same logic the daemon runs, exits when the queue is empty.');
+  println('                                       Concurrency is controlled by a poll lock — fail-fast by default, --wait[=<sec>] blocks for up to N seconds.');
+  println('                                       --dry-run lists candidate inboxes without ingesting.');
   println('  construct intake reopen <id>         Move a processed or skipped packet back to pending.');
   println('  construct intake quarantine list             List packets held for human review (low confidence or close margin).');
   println('  construct intake quarantine show <id>        Show a quarantined packet with top-3 candidate types and margins.');
@@ -1910,6 +2097,10 @@ async function cmdIntake(args) {
     return await cmdIntakeIntegrate(id, args.slice(2), cwd);
   }
 
+  if (sub === 'process') {
+    return await cmdIntakeProcess(args.slice(1), cwd);
+  }
+
   if (sub === 'config') {
     return await cmdIntakeConfig(args.slice(1));
   }
@@ -1922,10 +2113,75 @@ async function cmdIntake(args) {
     return await cmdIntakeNeedsAsr(args.slice(1));
   }
 
-  errorln(`Unknown intake subcommand: ${sub}. Available: list, show, done, skip, reopen, quarantine, reroute, integrate, config, extraction-warnings, needs-asr`);
+  errorln(`Unknown intake subcommand: ${sub}. Available: list, show, done, skip, reopen, process, quarantine, reroute, integrate, config, extraction-warnings, needs-asr`);
   process.exit(1);
 }
 
+async function cmdIntakeProcess(args, cwd) {
+  const dryRun = args.includes('--dry-run');
+  const waitFlag = args.find((a) => a === '--wait' || a.startsWith('--wait='));
+  const { InboxWatcher, resolveInboxDirs } = await import('../lib/embed/inbox.mjs');
+
+  if (dryRun) {
+    const dirs = resolveInboxDirs(cwd, process.env);
+    if (dirs.length === 0) {
+      println('No inbox directories configured. Run `construct intake config` to add one.');
+      return;
+    }
+    println('Would scan:');
+    for (const d of dirs) println(`  ${d}`);
+    println('');
+    println('(dry-run — no files processed; re-run without --dry-run to actually ingest.)');
+    return;
+  }
+
+  // Concurrency is controlled by the intake poll lock inside
+  // InboxWatcher.poll. Default behavior is fail-fast: if the daemon (or
+  // another CLI invocation) is mid-poll, raise an actionable error rather
+  // than serializing silently. --wait[=<seconds>] opts into blocking for
+  // up to N seconds (default 30s when --wait is bare).
+
+  let waitMs = 0;
+  if (waitFlag) {
+    const m = /^--wait(?:=(\d+))?$/.exec(waitFlag);
+    const seconds = m && m[1] ? Number(m[1]) : 30;
+    waitMs = Math.max(0, seconds) * 1000;
+  }
+
+  const watcher = new InboxWatcher({ rootDir: cwd, env: process.env, cwd });
+  let result;
+  try {
+    result = await watcher.poll({ waitMs, actor: 'construct intake process' });
+  } catch (err) {
+    const { POLL_LOCK_BUSY } = await import('../lib/intake/poll-lock.mjs');
+    if (err && err.code === POLL_LOCK_BUSY) {
+      const holder = err.holder || {};
+      errorln('Another intake poll is in progress.');
+      errorln(`  holder: ${holder.actor || 'unknown'} (pid ${holder.pid})`);
+      errorln(`  started: ${holder.startedAt || 'unknown'}`);
+      errorln('');
+      errorln('Choose one:');
+      errorln('  construct intake process --wait        Block until the holder finishes (default 30s).');
+      errorln('  construct intake process --wait=<sec>  Block for a custom window.');
+      errorln('  construct down                          Stop background services, then retry.');
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  println(`Processed: ${result.processed.length}`);
+  println(`Skipped (unchanged): ${result.skipped}`);
+  if (result.errors.length) {
+    println(`Errors: ${result.errors.length}`);
+    for (const e of result.errors) println(`  ${e.path}: ${e.error}`);
+  }
+  for (const item of result.processed) {
+    const note = item.needsAsr ? ' (queued for ASR)' : '';
+    println(`  + ${item.path}${note}`);
+  }
+  if (result.errors.length) process.exitCode = 1;
+}
+
 async function cmdIntakeQuarantine(args, cwd) {
   const action = args[0];
   const { listQuarantine, readQuarantine } = await import('../lib/intake/quarantine.mjs');
@@ -4584,14 +4840,6 @@ const handlers = new Map([
       process.exit(1);
     }
   }],
-  ['policy:list', async (args) => {
-    const { listPolicies, formatPolicyList } = await import('../lib/policy/unified-gates.mjs');
-    if (args.includes('--json')) {
-      println(JSON.stringify(listPolicies(), null, 2));
-    } else {
-      process.stdout.write(formatPolicyList());
-    }
-  }],
   ['policy', async (args) => {
     const sub = args[0];
     if (!sub || sub === '--help' || sub === '-h') {
@@ -4602,7 +4850,7 @@ const handlers = new Map([
     if (sub === 'show') {
       const { readFileSync, existsSync } = await import('node:fs');
       const { join } = await import('node:path');
-      const inventoryPath = join(ROOT_DIR, 'agents', 'policy-inventory.json');
+      const inventoryPath = join(ROOT_DIR, 'specialists', 'policy-inventory.json');
       if (!existsSync(inventoryPath)) {
         errorln('specialists/policy-inventory.json not found');
         process.exit(1);

package/bin/construct-postinstall.mjs

@@ -58,8 +58,29 @@ try {
   }
 } catch { /* fall through */ }
 
-// Require a package.json at the install target so monorepo nested installs
-// don't accidentally trigger staging in the wrong directory.
+// `npm i -g @geraldmaron/construct` runs the postinstall with
+// npm_config_global=true. Wire the `construct` front-door agent into the
+// user's home directories so it's reachable from every host (Claude Code,
+// Codex, Copilot, OpenCode) immediately after a global install. Specialists
+// stay project-only and land when the user runs `construct init` in a repo.
+
+if (process.env.npm_config_global === 'true' || process.env.npm_config_global === true) {
+  const syncScript = path.join(PKG_ROOT, 'scripts', 'sync-specialists.mjs');
+  if (existsSync(syncScript)) {
+    log('global install detected; syncing front-door agent into ~/');
+    const result = spawnSync(process.execPath, [syncScript, '--global'], {
+      stdio: 'inherit',
+    });
+    if (result.status !== 0) {
+      log(`global sync failed (exit ${result.status}); run \`construct sync --global\` manually`);
+    }
+  }
+  process.exit(0);
+}
+
+// Project install path: require a package.json at the install target so
+// monorepo nested installs don't accidentally trigger staging in the wrong
+// directory.
 
 const consumerPkgPath = path.join(initCwd, 'package.json');
 if (!existsSync(consumerPkgPath)) {

package/lib/auto-docs.mjs

@@ -10,7 +10,8 @@
  * anything would change without writing files — the mode CI uses to detect drift.
  *
  * buildSite() is retained for compatibility; the public site now renders docs/
- * directly through Fumadocs and buildFumadocsReference() emits generated pages.
+ * directly through Next.js (apps/docs/) and buildFumadocsReference() emits
+ * generated reference Markdown into docs/reference/.
  */
 
 import fs from 'node:fs';
@@ -82,7 +83,7 @@ function buildCoreDocsContract() {
 
 const DIR_DESCRIPTIONS = {
   agents: 'Registry and generated platform adapter chains',
-  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)',
+  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Next.js docs site)',
   bin: 'CLI entrypoint (`construct`)',
   claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',
@@ -151,7 +152,7 @@ function buildHooksTable(rootDir) {
 }
 
 function buildAgentsTable(rootDir) {
-  const registryPath = path.join(rootDir, 'agents', 'registry.json');
+  const registryPath = path.join(rootDir, 'specialists', 'registry.json');
   let registry;
   try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return ''; }
 
@@ -303,7 +304,7 @@ export function checkDocsCoverage({ rootDir } = {}) {
   return { covered, uncovered, total: covered.length + uncovered.length };
 }
 
-// Categories surfaced in the Fumadocs reference. Internal commands (e.g.,
+// Categories surfaced in the generated CLI reference. Internal commands (e.g.,
 // `construct hook <name>`) are not user-facing reference material.
 const REFERENCE_CATEGORIES = [
   'Core',
@@ -407,9 +408,12 @@ function renderAgentsPage(rootDir) {
 }
 
 /**
- * Emit MDX reference pages into docs/reference/ for the Fumadocs site.
- * Mirrors the data sources behind AUTO regions and buildSite() but writes
- * Markdown files Fumadocs can render directly (no MkDocs intermediate).
+ * Emit MDX reference pages into docs/reference/ for the Next.js docs site
+ * in apps/docs/. Mirrors the data sources behind AUTO regions and buildSite()
+ * but writes Markdown files the docs app can pull in directly (no MkDocs
+ * intermediate). Name kept for backwards compatibility with callers that
+ * still import buildFumadocsReference; the rendering layer is now plain
+ * Next.js + @next/mdx.
  */
 export function buildFumadocsReference({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();

package/lib/dashboard-static.mjs

@@ -1,8 +1,11 @@
 /**
  * lib/dashboard-static.mjs — build and sync the dashboard static bundle.
  *
- * Keeps `dashboard/dist/` and `lib/server/static/` aligned so the HTTP server
- * serves the current dashboard build from repo-owned assets.
+ * Keeps the Next.js static export at `apps/dashboard/out/` and the served
+ * tree at `lib/server/static/` aligned so the HTTP server picks up the
+ * current dashboard build without code changes. Pre-2.0 the dashboard
+ * lived at `dashboard/dist/`; the rebuild to Next.js (commit 84cd721)
+ * moved the source of truth into `apps/dashboard/out/`.
  */
 
 import fs from 'node:fs';
@@ -78,8 +81,8 @@ function removeEmptyDirs(dirPath, stopAt) {
 export function getDashboardPaths({ rootDir = process.cwd() } = {}) {
   return {
     rootDir,
-    dashboardDir: path.join(rootDir, 'dashboard'),
-    sourceDir: path.join(rootDir, 'dashboard', 'dist'),
+    dashboardDir: path.join(rootDir, 'apps', 'dashboard'),
+    sourceDir: path.join(rootDir, 'apps', 'dashboard', 'out'),
     targetDir: path.join(rootDir, 'lib', 'server', 'static'),
   };
 }

package/lib/doc-stamp.mjs

@@ -102,12 +102,17 @@ function splitStamp(content) {
  *   sessionId   {string}  - Construct session ID if available
  *   model       {string}  - Model name/version if available
  *   preserve_id {boolean} - Keep existing cx_doc_id if present (default: true)
+ *   attribution {object}  - Optional { createdBy, createdByAgent } pair. When
+ *                           provided, written into the stamp and (on stamp
+ *                           refresh) carried forward via existing_fields so a
+ *                           later write does not erase the original author.
  */
 export function stampFrontmatter(content, {
   generator = 'construct',
   sessionId = null,
   model = null,
   preserve_id = true,
+  attribution = null,
 } = {}) {
   const existing = hasStamp(content) ? splitStamp(content) : null;
   const existingFields = existing ? parseStamp(content) : {};
@@ -116,6 +121,11 @@ export function stampFrontmatter(content, {
   const createdAt = existingFields.created_at || new Date().toISOString();
   const updatedAt = new Date().toISOString();
 
+  const createdBy = existingFields.created_by ?? attribution?.createdBy ?? null;
+  const createdByAgent = existingFields.created_by_agent ?? attribution?.createdByAgent ?? null;
+  const lastModifiedBy = attribution?.createdBy ?? existingFields.last_modified_by ?? null;
+  const lastModifiedByAgent = attribution?.createdByAgent ?? existingFields.last_modified_by_agent ?? null;
+
   // Body is everything after stamp (or all content if no prior stamp)
   const body = existing ? existing.body : content;
   const hash = bodyHash(body);
@@ -127,6 +137,12 @@ export function stampFrontmatter(content, {
     `updated_at: ${updatedAt}`,
     `generator: ${generator}`,
   ];
+  if (createdBy) lines.push(`created_by: ${createdBy}`);
+  if (createdByAgent) lines.push(`created_by_agent: ${createdByAgent}`);
+  if (lastModifiedBy && lastModifiedBy !== createdBy) lines.push(`last_modified_by: ${lastModifiedBy}`);
+  if (lastModifiedByAgent && lastModifiedByAgent !== createdByAgent) {
+    lines.push(`last_modified_by_agent: ${lastModifiedByAgent}`);
+  }
   if (model) lines.push(`model: ${model}`);
   if (sessionId) lines.push(`session_id: ${sessionId}`);
   lines.push(`body_hash: ${hash}`);

package/lib/docs-verify.mjs

@@ -52,18 +52,11 @@ if (stagedMode) {
   if (changedCode.length === 0) process.exit(0);
   if (changedDocs.length > 0) process.exit(0);
 
-  if (process.env.CONSTRUCT_SKIP_DOCS === "1") {
-    process.stderr.write(
-      `[docs:verify --staged] CONSTRUCT_SKIP_DOCS=1 — skipping doc-coupling check for ${changedCode.length} code file(s).\n`,
-    );
-    process.exit(0);
-  }
-
   const sample = changedCode.slice(0, 6).map((f) => `  - ${f}`).join("\n");
   process.stderr.write(
     `[docs:verify --staged] ${changedCode.length} code file(s) staged but no CHANGELOG.md / docs/* / .cx/context.* updates.\n` +
     `${sample}${changedCode.length > 6 ? `\n  ... (${changedCode.length - 6} more)` : ""}\n` +
-    `Update docs in this commit, or override with CONSTRUCT_SKIP_DOCS=1.\n`,
+    `Update docs in this commit before pushing.\n`,
   );
   process.exit(1);
 }

package/lib/doctor/watchers/bd-watch.mjs

@@ -12,8 +12,10 @@
  * as a label, regardless of how it got there (manual, ai, automated).
  */
 
-import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { appendBounded } from '../../logging/rotate.mjs';
+import { resolveProjectScope } from '../../project-root.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -86,6 +88,7 @@ export async function tick() {
       if (seen[key]) continue;
       seen[key] = { ts: Date.now(), id: issue.id };
       const manifest = loadManifest(personaId);
+      const scope = resolveProjectScope();
       const entry = {
         ts: Date.now(),
         personaId,
@@ -96,8 +99,9 @@ export async function tick() {
         summary: `bd ${issue.id} labeled next:cx-${personaId} — ${(issue.title || '').slice(0, 120)}`,
         killSwitchEnv: manifest?.killSwitchEnv || '',
         source: 'bd-watch',
+        ...(scope?.projectId ? { projectId: scope.projectId } : {}),
       };
-      appendFileSync(PENDING_PATH, JSON.stringify(entry) + '\n');
+      appendBounded('role-pending', PENDING_PATH, JSON.stringify(entry) + '\n');
       record({
         kind: 'action',
         watcher: name,

package/lib/embed/daemon.mjs

@@ -30,6 +30,7 @@ import { dirname, join } from 'node:path';
 
 import { loadEmbedConfig } from './config.mjs';
 import { Scheduler } from './scheduler.mjs';
+import { rotateIfOversized } from '../logging/rotate.mjs';
 import { SnapshotEngine, renderMarkdown } from './snapshot.mjs';
 import { ApprovalQueue } from './approval-queue.mjs';
 import { dispatchOutputs } from './output.mjs';
@@ -594,6 +595,25 @@ export class EmbedDaemon {
       },
     );
 
+    // ── Job 6: daemon-log-rotation ────────────────────────────────────────────
+    // OS supervisors (launchd/systemd/schtasks) redirect daemon stdout to
+    // ~/.cx/runtime/embed-daemon.log with no rotation. A stuck telemetry
+    // log line filled it to 34 GB on one local install; rotate proactively.
+    // CONSTRUCT_EMBED_LOG_MAX_MB overrides the default 50 MB cap.
+
+    this.#scheduler.register(
+      'daemon-log-rotation',
+      60_000,
+      async () => {
+        const logPath = join(homedir(), '.cx', 'runtime', 'embed-daemon.log');
+        const capMb = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_MB) || 50;
+        const maxBytes = Math.floor(capMb * 1024 * 1024);
+        const maxSegments = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_SEGMENTS) || 5;
+        await rotateIfOversized(logPath, { maxBytes, maxSegments, gzip: true });
+      },
+      { runImmediately: true },
+    );
+
     // ── Job 0: telemetry-setup ───────────────────────────────────────────────────
 // On startup — ensure annotation queues and eval configs exist (idempotent)
 this.#scheduler.register(

package/lib/embed/docs-lifecycle.mjs

@@ -3,6 +3,8 @@
  *
  * Responsibilities:
  *   - Detect stale, missing, or outdated docs across targets
+ *   - Emit document.stale lifecycle events for each stale gap surfaced
+ *     (consumed by cx-docs-keeper and any project-bound subscribers)
  *   - Generate/update docs as artifacts in the appropriate docs lane
  *   - Route writes through the authority guard (direct-write for low-risk, approval-queued for high-risk)
  *   - Treat ALL doc types uniformly: adrs, prds, memos, notes, intake, roadmaps
@@ -23,6 +25,7 @@ import { WORKSPACE_DOCS_LANES } from './config.mjs';
 import { recommendArtifacts } from './artifact.mjs';
 import { createRecommendation, autoSuppressStale, recommendationStats, isRecommendationActive } from './recommendation-store.mjs';
 import { detectConflicts } from './conflict-detection.mjs';
+import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
 
 /**
  * Risk classification for doc operations.
@@ -232,6 +235,22 @@ export async function runDocsLifecycle(opts) {
     const gaps = detectDocGaps(target, { snapshot, roleLens });
     allGaps.push(...gaps.map((g) => ({ ...g, target: targetLabel(target) })));
 
+    // Surface staleness as lifecycle events for any specialist subscribed
+    // to document.stale (cx-docs-keeper by default).
+
+    for (const gap of gaps) {
+      if (gap.type !== 'stale') continue;
+      emitRoleEvent('document.stale', {
+        summary: gap.summary,
+        context: {
+          lane: gap.lane,
+          file: gap.file,
+          ageMs: gap.age,
+          target: targetLabel(target),
+        },
+      });
+    }
+
     // Check intake patterns for artifact recommendations (uses recommendation store for dedup)
     const intakeGaps = detectIntakeDocGaps(target.path);
     for (const gap of intakeGaps) {