@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/extractors/shared/drop-info.mjs

@@ -0,0 +1,22 @@
+/**
+ * lib/extractors/shared/drop-info.mjs — shared drop-info factory and envelope builder.
+ *
+ * Every extractor returns the same { text, structured, droppedInfo } envelope so
+ * callers can always read droppedInfo[] without format-specific branching. An empty
+ * droppedInfo array means nothing was silently dropped, not that nothing was structured.
+ *
+ * Valid `kind` values mirror the MIME world: 'attachment', 'inline-image', 'table',
+ * 'formula', 'comment', 'html-part', 'animation', 'speaker-notes', 'scanned-pdf'.
+ */
+
+export function makeDropInfo({ kind, count, reason, recoverable = false }) {
+  return { kind, count, reason, recoverable };
+}
+
+/**
+ * Wrap extraction results in the universal envelope.
+ * Callers that produce no structured data pass `structured: null` (the default).
+ */
+export function makeEnvelope({ text = '', structured = null, droppedInfo = [] } = {}) {
+  return { text, structured, droppedInfo };
+}

package/lib/gates-audit.mjs

@@ -47,11 +47,17 @@ const GATE_DEFINITIONS = [
 ];
 
 function parseCIJobs(rootDir) {
+  // Extracts both job-level names and step-level names. Consolidated jobs
+  // (e.g. the `lint suite` job carrying comment policy + docs drift + gates
+  // audit as steps) surface each step name as a gate signal. The audit's
+  // job-name comparison treats jobs and steps as a flat union so gate
+  // definitions stay decoupled from CI structure.
   const path = join(rootDir, '.github', 'workflows', 'ci.yml');
   if (!existsSync(path)) return [];
   const yml = readFileSync(path, 'utf8');
-  return [...yml.matchAll(/^    name:\s*(.+?)\s*$/gm)]
-    .map((m) => m[1].trim())
+  const jobNames = [...yml.matchAll(/^    name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
+  const stepNames = [...yml.matchAll(/^      - name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
+  return [...jobNames, ...stepNames]
     .map((n) => n.replace(/\$\{\{\s*matrix\.(\w+)\s*\}\}/g, (_, k) => `<${k}>`));
 }
 

package/lib/git-hooks/prepare-commit-msg

@@ -6,7 +6,7 @@
  * Follows the RFC 9562 / git-interpret-trailers convention.
  *
  * Trailers added (when env vars are present):
- *   AI-Generator: construct/sync-agents
+ *   AI-Generator: construct/sync-specialists
  *   AI-Model:     claude-sonnet-4-6
  *   AI-Session:   019dbb90-5885-...
  *

package/lib/headhunt.mjs

@@ -16,7 +16,7 @@ import { selectOption } from './tty-prompts.mjs';
 
 const OVERLAY_DIRNAME = 'domain-overlays';
 const PROMOTION_DIRNAME = 'promotion-requests';
-const TEAMS_FILE = 'agents/teams.json';
+const TEAMS_FILE = 'specialists/teams.json';
 
 function loadTeamTemplates(root) {
   try {
@@ -342,7 +342,7 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
     if (!templateName) { listTeamTemplates(cwd); return; }
     const root = findConstructRoot(cwd);
     const teams = loadTeamTemplates(root);
-    if (!teams) throw new Error('agents/teams.json not found. Run from the Construct root.');
+    if (!teams) throw new Error('specialists/teams.json not found. Run from the Construct root.');
     const tpl = teams.templates[templateName];
     if (!tpl) throw new Error(`Unknown template: ${templateName}. Run 'construct headhunt template' to list available templates.`);
     const objective = typeof flags.for === 'string' ? flags.for.trim() : rest.slice(1).join(' ').trim();

package/lib/hooks/agent-tracker.mjs

@@ -60,17 +60,12 @@ try {
   const cxDir = join(home, '.cx');
   mkdirSync(cxDir, { recursive: true });
   
-  // Update last-agent file for coordination
-  writeFileSync(
-    join(cxDir, 'last-agent.json'),
-    JSON.stringify({ 
-      agent: agentName, 
-      coordination: 'tracker-plus-plan', 
-      ts: new Date().toISOString(),
-      outcome,
-      description: description.slice(0, 200)
-    }),
-  );
+  // Update last-agent files for coordination (shared + per-agent)
+  const agentEntry = { agent: agentName, coordination: 'tracker-plus-plan', ts: new Date().toISOString(), outcome, description: description.slice(0, 200) };
+  writeFileSync(join(cxDir, 'last-agent.json'), JSON.stringify(agentEntry));
+  // Per-agent file prevents one agent dispatch from resetting another's fence window
+  const safeName = agentName.replace(/[^a-z0-9._-]/gi, '_');
+  writeFileSync(join(cxDir, `last-agent-${safeName}.json`), JSON.stringify(agentEntry));
   
   // Append to agent log for telemetry
   const agentLogFile = join(cxDir, 'agent-log.jsonl');

package/lib/hooks/comment-lint.mjs

@@ -40,8 +40,24 @@ const rootDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const result = lintFile(filePath, { rootDir });
 if (!result.errors.length && !result.warnings.length) process.exit(0);
 
+// Artifact-prose violations are advisory at write-time (no-fabrication policy
+// enforces them at CI/release-gate time via CONSTRUCT_ARTIFACT_LINT_MODE=block).
+// Surface them on stderr but do not block the edit.
+const artifactOnly = (
+  result.errors.length === 0 &&
+  result.warnings.every((w) => w.kind === 'artifact')
+);
+
 const { output } = formatResults([result]);
 process.stderr.write(output);
+
+if (artifactOnly) {
+  process.stderr.write(
+    '\nArtifact-lint advisory (no-fabrication). The edit is not blocked, but these will fail the release gate. Fix before push.\n',
+  );
+  process.exit(0);
+}
+
 process.stderr.write(
   '\nComment policy blocked this edit. Remove the violations or set CONSTRUCT_SKIP_COMMENT_LINT=1.\n',
 );

package/lib/hooks/guard-bash.mjs

@@ -95,41 +95,62 @@ for (const { pattern, reason } of WARN_PATTERNS) {
 
 if (process.env.CONSTRUCT_ROLES !== 'off') {
   try {
-    const lastAgentPath = join(homedir(), '.cx', 'last-agent.json');
-    if (existsSync(lastAgentPath)) {
-      const last = JSON.parse(readFileSync(lastAgentPath, 'utf8'));
-      const lastTs = last?.ts ? Date.parse(last.ts) : 0;
+    const cxDir = join(homedir(), '.cx');
+    const id = String(process.env.CONSTRUCT_AGENT_ID || '').replace(/^cx-/, '');
+    let agentData = null;
+
+    // Prefer per-agent timestamp file (prevents cross-agent fence window reset)
+    if (id) {
+      const perAgentPath = join(cxDir, `last-agent-${id.replace(/[^a-z0-9._-]/gi, '_')}.json`);
+      if (existsSync(perAgentPath)) {
+        agentData = JSON.parse(readFileSync(perAgentPath, 'utf8'));
+      }
+    }
+    // Fall back to shared last-agent.json
+    if (!agentData) {
+      const sharedPath = join(cxDir, 'last-agent.json');
+      if (existsSync(sharedPath)) {
+        agentData = JSON.parse(readFileSync(sharedPath, 'utf8'));
+      }
+    }
+
+    if (agentData) {
+      const lastTs = agentData?.ts ? Date.parse(agentData.ts) : 0;
       const fresh = lastTs && (Date.now() - lastTs) < 10 * 60 * 1000;
-      const id = String(last?.agent || '').replace(/^cx-/, '');
-      if (fresh && id) {
+      const personaId = id || String(agentData?.agent || '').replace(/^cx-/, '');
+      if (fresh && personaId) {
         const { isOnboarded } = await import('../roles/manifest.mjs');
-        if (isOnboarded(id)) {
+        if (isOnboarded(personaId)) {
           const { checkAction } = await import('../roles/fence.mjs');
           const trimmed = command.trim();
           let verdict;
           if (/^git\s+commit\b/.test(trimmed)) {
-            verdict = checkAction({ personaId: id, action: 'commit', target: '' });
+            verdict = checkAction({ personaId, action: 'commit', target: '' });
           } else if (/^git\s+push\b/.test(trimmed)) {
-            verdict = checkAction({ personaId: id, action: 'push', target: '' });
+            verdict = checkAction({ personaId, action: 'push', target: '' });
           } else {
-            verdict = checkAction({ personaId: id, action: 'bash', target: trimmed });
+            verdict = checkAction({ personaId, action: 'bash', target: trimmed });
           }
           if (!verdict.allowed && verdict.reason === 'outside-fence') {
+            const allowedList = (() => {
+              try { const { loadManifest } = await import('../roles/manifest.mjs'); const m = loadManifest(personaId); return m?.fence?.allowedCommands?.join(', ') || 'see role-manifests.json'; } catch { return 'see role-manifests.json'; }
+            })();
             process.stderr.write(
-              `[fence] cx-${id} cannot run this command — outside declared fence.\n` +
+              `[fence] cx-${personaId} cannot run this command — outside declared fence.\n` +
               `Command: ${trimmed.slice(0, 200)}\n` +
-              `Allowed commands prefix list: see agents/role-manifests.json → ${id} → fence.allowedCommands.\n`
+              `Allowed commands: ${allowedList}\n` +
+              `To bypass: CONSTRUCT_ROLES=off <command>\n`
             );
             process.exit(2);
           }
           if (!verdict.allowed && verdict.approval) {
             process.stderr.write(
-              `[fence] cx-${id} running this requires user approval (${verdict.reason}).\n` +
+              `[fence] cx-${personaId} running this requires user approval (${verdict.reason}).\n` +
               `Command: ${trimmed.slice(0, 200)}\n`
             );
             const { recordApprovalRequest } = await import('../roles/approval-surface.mjs');
             const actionLabel = /^git\s+commit\b/.test(trimmed) ? 'commit' : /^git\s+push\b/.test(trimmed) ? 'push' : 'bash';
-            await recordApprovalRequest({ personaId: id, action: actionLabel, target: trimmed, reason: verdict.reason || 'needs-approval' });
+            await recordApprovalRequest({ personaId, action: actionLabel, target: trimmed, reason: verdict.reason || 'needs-approval' });
           }
         }
       }

package/lib/hooks/mcp-audit.mjs

@@ -3,6 +3,7 @@
  * lib/hooks/mcp-audit.mjs — MCP audit hook — logs all MCP tool calls for observability and review.
  *
  * Runs as PostToolUse on MCP tool calls. Records tool name, input, and output summary to ~/.cx/mcp-audit.json for telemetry and security review.
+ * Also emits a gen_ai.client.tool.call span when OTel is configured (OTEL_EXPORTER_OTLP_ENDPOINT set).
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
@@ -10,6 +11,8 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { shouldCreateCx } from '../project-detection.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
+import { GenAiAttrs, withGenAiSpan } from '../telemetry/otel-tracer.mjs';
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
@@ -47,9 +50,19 @@ if (audit[mcpServer].length > 200) audit[mcpServer] = audit[mcpServer].slice(-20
 
 try {
   if (shouldCreateCxDir) {
-    mkdirSync(join(cwd, '.cx'), { recursive: true });
+    ensureCxDir(cwd);
     writeFileSync(auditPath, JSON.stringify(audit, null, 2));
   }
 } catch { /* best effort */ }
 
+// Fire-and-forget OTel span for the tool call — non-blocking.
+if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT && process.env.CONSTRUCT_OTEL !== 'off') {
+  withGenAiSpan('tool_call', {
+    [GenAiAttrs.TOOL_NAME]: mcpTool,
+    [GenAiAttrs.MCP_METHOD]: toolName,
+    [GenAiAttrs.MCP_TRANSPORT]: 'stdio',
+    'construct.mcp_server': mcpServer,
+  }, async (span) => span).catch(() => {});
+}
+
 process.exit(0);

package/lib/hooks/pre-compact.mjs

@@ -4,15 +4,87 @@
  *
  * Runs before context compaction. Writes a structured summary of context state and pending tasks to preserve continuity across the compaction boundary.
  *
+ * Manual sections in context.md (any heading not in AUTO_SECTION_NAMES) are
+ * detected, preserved verbatim, and re-appended after the auto-generated
+ * sections so that hand-written decisions, active-work notes, and architecture
+ * context survive every compaction cycle.
+ *
  * @p95ms 100
  * @maxBlockingScope PreCompact
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
-import { writeContextState } from '../context-state.mjs';
+import { writeContextState, contextMarkdownPath, contextJsonPath } from '../context-state.mjs';
 import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
 
+// Section headings that are auto-generated by this hook. Any other heading in
+// the existing context.md is treated as manually authored and preserved.
+const AUTO_SECTION_NAMES = new Set([
+  'what was in progress',
+  'files changed this session',
+  'decisions captured',
+  'pending todos',
+  'session efficiency snapshot',
+  'open issues',
+  'session context',
+]);
+
+/**
+ * Parse a markdown string into `[{heading, level, body}]` sections.
+ * Returns an empty array for empty/missing input.
+ */
+function parseSections(md) {
+  if (!md) return [];
+  const lines = md.split('\n');
+  const sections = [];
+  let current = null;
+  for (const line of lines) {
+    const hm = line.match(/^(#{1,6})\s+(.+)$/);
+    if (hm) {
+      if (current) sections.push(current);
+      current = { heading: line, level: hm[1].length, title: hm[2].trim(), body: [] };
+    } else if (current) {
+      current.body.push(line);
+    }
+  }
+  if (current) sections.push(current);
+  return sections;
+}
+
+/**
+ * Extract sections from an existing context.md that were NOT auto-generated.
+ * Returns a markdown string (may be empty) to append after the auto content.
+ */
+function extractManualSections(mdPath) {
+  if (!existsSync(mdPath)) return '';
+  let existing = '';
+  try { existing = readFileSync(mdPath, 'utf8'); } catch { return ''; }
+  const sections = parseSections(existing);
+  const manual = sections.filter((s) => !AUTO_SECTION_NAMES.has(s.title.toLowerCase()));
+  if (!manual.length) return '';
+  return manual
+    .map((s) => [s.heading, ...s.body].join('\n').trimEnd())
+    .join('\n\n') + '\n';
+}
+
+/**
+ * Merge non-empty arrays from existing context.json into the new state to
+ * prevent the hook from discarding decisions/filesChanged captured manually.
+ */
+function mergeExistingJson(jsonPath, newState) {
+  if (!existsSync(jsonPath)) return newState;
+  let existing = {};
+  try { existing = JSON.parse(readFileSync(jsonPath, 'utf8')); } catch { return newState; }
+  const merged = { ...newState };
+  for (const key of ['decisions', 'filesChanged', 'pendingTodos']) {
+    if ((!merged[key] || !merged[key].length) && Array.isArray(existing[key]) && existing[key].length) {
+      merged[key] = existing[key];
+    }
+  }
+  return merged;
+}
+
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
 
@@ -156,6 +228,15 @@ contextLines.push('## Open issues');
 contextLines.push(warnFlags || 'None');
 
 const content = contextLines.join('\n') + '\n';
+
+const projectCxDir = join(cwd, '.cx');
+try { mkdirSync(projectCxDir, { recursive: true }); } catch { /* exists */ }
+
+// Preserve manually-written sections from the existing context.md.
+const projectMdPath = contextMarkdownPath(cwd);
+const manualSections = extractManualSections(projectMdPath);
+const finalContent = content + (manualSections ? '\n' + manualSections : '');
+
 const contextJson = {
   source: 'pre-compact',
   projectName,
@@ -167,9 +248,11 @@ const contextJson = {
   warnFlags: warnFlags || 'None',
 };
 
-const projectCxDir = join(cwd, '.cx');
-try { mkdirSync(projectCxDir, { recursive: true }); } catch { /* exists */ }
-try { writeContextState(cwd, { ...contextJson, contextSummary: lastSummary }, { markdown: content }); } catch { /* best effort */ }
+// Merge non-empty arrays from the existing JSON so manually recorded state
+// is not silently dropped when the transcript scan finds nothing new.
+const mergedJson = mergeExistingJson(contextJsonPath(cwd), contextJson);
+
+try { writeContextState(cwd, { ...mergedJson, contextSummary: lastSummary }, { markdown: finalContent }); } catch { /* best effort */ }
 if (decisions.length) {
   const decisionsDir = join(projectCxDir, 'decisions');
   const slug = `${date.replace(/[^0-9]/g, '')}-session-decisions`;
@@ -190,6 +273,10 @@ if (decisions.length) {
 
 const globalCxDir = join(homedir(), '.cx');
 try { mkdirSync(globalCxDir, { recursive: true }); } catch { /* exists */ }
-try { writeContextState(homedir(), { ...contextJson, contextSummary: lastSummary }, { markdown: content }); } catch { /* best effort */ }
+const globalMdPath = contextMarkdownPath(homedir());
+const globalManualSections = extractManualSections(globalMdPath);
+const globalFinalContent = content + (globalManualSections ? '\n' + globalManualSections : '');
+const globalMergedJson = mergeExistingJson(contextJsonPath(homedir()), contextJson);
+try { writeContextState(homedir(), { ...globalMergedJson, contextSummary: lastSummary }, { markdown: globalFinalContent }); } catch { /* best effort */ }
 
 process.exit(0);

package/lib/hooks/pre-push-gate.mjs

@@ -198,8 +198,13 @@ function runNpmGate(projectDir) {
   jobs.push({                       label: 'audit', cmd: runner, args: auditArgs, timeout: 30_000 });
 
   if (existsSync(join(projectDir, 'bin/construct'))) {
-    jobs.push({ label: 'evals', cmd: 'node', args: ['bin/construct', 'evals', 'retrieval'], timeout: 60_000 });
-    jobs.push({ label: 'docs',  cmd: 'node', args: ['bin/construct', 'docs:verify'],        timeout: 15_000 });
+    jobs.push({ label: 'evals',             cmd: 'node', args: ['bin/construct', 'evals', 'retrieval'],          timeout: 60_000 });
+    jobs.push({ label: 'docs',              cmd: 'node', args: ['bin/construct', 'docs:verify'],                 timeout: 15_000 });
+    jobs.push({ label: 'docs drift',        cmd: 'node', args: ['bin/construct', 'docs:update', '--check'],      timeout: 15_000 });
+    jobs.push({ label: 'dashboard drift',   cmd: 'node', args: ['bin/construct', 'dashboard:sync', '--check'],   timeout: 15_000 });
+    jobs.push({ label: 'comment policy',    cmd: 'node', args: ['bin/construct', 'lint:comments'],               timeout: 30_000 });
+    jobs.push({ label: 'agents registry',   cmd: 'node', args: ['bin/construct', 'lint:agents'],                 timeout: 15_000 });
+    jobs.push({ label: 'contracts schema',  cmd: 'node', args: ['bin/construct', 'lint:contracts'],              timeout: 15_000 });
   }
 
   if (existsSync(join(projectDir, 'scripts/lint-prose.mjs'))) {
@@ -274,15 +279,43 @@ function runJob(job) {
 
 const results = await Promise.all(gate.jobs.map(runJob));
 const failures = [];
+
+// Auto-fix docs drift: if docs:update --check fails, run docs:update to regenerate
+const docsDriftResult = results.find((r) => r.label === 'docs drift');
+if (docsDriftResult && docsDriftResult.status !== 0) {
+  process.stderr.write('[pre-push-gate] Docs drift detected — auto-running docs:update...\n');
+  try {
+    const fix = spawnSync('node', ['bin/construct', 'docs:update'], {
+      cwd: gate.projectDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 30_000,
+    });
+    if (fix.status === 0) {
+      process.stderr.write('[pre-push-gate] docs:update succeeded — re-checking...\n');
+      const recheck = spawnSync('node', ['bin/construct', 'docs:update', '--check'], {
+        cwd: gate.projectDir,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 15_000,
+      });
+      if (recheck.status === 0) {
+        process.stderr.write('[pre-push-gate] Docs are now clean after auto-fix.\n');
+        results.splice(results.indexOf(docsDriftResult), 1); // remove from failure candidates
+      } else {
+        process.stderr.write(`[pre-push-gate] Auto-fix attempted but docs still drift — manual intervention needed.\n`);
+        docsDriftResult.stdout = (docsDriftResult.stdout || '') + '\n[auto-fix attempted but still dirty]';
+      }
+    } else {
+      process.stderr.write(`[pre-push-gate] docs:update auto-fix failed (exit ${fix.status}): ${fix.stderr.slice(0, 300)}\n`);
+    }
+  } catch (e) {
+    process.stderr.write(`[pre-push-gate] docs:update auto-fix threw: ${e.message}\n`);
+  }
+}
+
 for (const result of results) {
   if (result.status === 0) continue;
   const detail = (result.stderr || result.stdout || '').trim();
-  const firstError = detail.split('\n')
-    .map((l) => l.trim())
-    .filter((l) => l && !/^>/.test(l) && !/^\s*at /.test(l))
-    .slice(0, 3)
-    .join(' · ');
-  failures.push({ label: result.label, detail: firstError || `exited ${result.status}` });
+  failures.push({ label: result.label, detail: detail || `exited ${result.status}` });
 }
 
 if (failures.length === 0) { echo(); }

package/lib/hooks/proactive-activation.mjs

@@ -239,20 +239,6 @@ export function onScheduleCheck() {
   return events;
 }
 
-/**
- * Get all pending activations for a specialist.
- */
-export function getPendingActivations(specialist) {
-  // In a full implementation, this would query a pending queue
-  // For now, return recent activation history
-  const state = getActivationState(specialist);
-  return {
-    pending: 0,
-    recent: state.activations.length,
-    total: state.totalActivations,
-  };
-}
-
 /**
  * Clear activation state (for testing or manual reset).
  */

package/lib/hooks/registry-sync.mjs

@@ -13,11 +13,11 @@ import { logHookFailure } from './_lib/log.mjs';
 import { constructDir } from '../paths.mjs';
 
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
-if (!filePath.endsWith(path.join('agents', 'registry.json')) && !filePath.endsWith('/agents/registry.json')) process.exit(0);
+if (!filePath.endsWith(path.join('agents', 'registry.json')) && !filePath.endsWith('/specialists/registry.json')) process.exit(0);
 
 const toolkitDir = constructDir();
 try {
-  execSync('node scripts/sync-agents.mjs', {
+  execSync('node scripts/sync-specialists.mjs', {
     cwd: toolkitDir,
     stdio: 'pipe',
     env: { ...process.env, CX_TOOLKIT_DIR: toolkitDir },