@geraldmaron/construct 1.0.7 → 1.0.9

package/lib/extractors/calendar.mjs

@@ -0,0 +1,173 @@
+/**
+ * lib/extractors/calendar.mjs — RFC 5545 iCalendar (.ics) structured extraction.
+ *
+ * Parses VCALENDAR / VEVENT blocks without external dependencies. Handles
+ * multi-line property continuation (lines starting with whitespace), extracts
+ * SUMMARY, DTSTART, DTEND, ORGANIZER, ATTENDEE, DESCRIPTION, LOCATION, and
+ * preserves RRULE as a raw string for recurring events.
+ *
+ * Returns the universal { text, structured, droppedInfo } envelope where
+ * structured = { events: [{ summary, dtstart, dtend, organizer,
+ *                           attendees: [], description, location, rrule }] }.
+ */
+import { readFileSync } from 'node:fs';
+import { makeEnvelope, makeDropInfo } from './shared/drop-info.mjs';
+
+// ─── RFC 5545 helpers ─────────────────────────────────────────────────────────
+
+// Unfold continuation lines (RFC 5545 §3.1 — a line beginning with SPACE or TAB
+// is a continuation of the previous property line).
+function unfoldLines(raw) {
+  return raw.replace(/\r\n/g, '\n').replace(/\n[ \t]/g, '');
+}
+
+// Split a property line into its name, params object, and value.
+// e.g. "DTSTART;TZID=America/New_York:20240101T090000" → name=DTSTART, params={TZID:...}, value=...
+function parseProperty(line) {
+  const colonIdx = line.indexOf(':');
+  if (colonIdx === -1) return { name: line.toUpperCase(), params: {}, value: '' };
+  const nameAndParams = line.slice(0, colonIdx);
+  const value = line.slice(colonIdx + 1).trim();
+  const parts = nameAndParams.split(';');
+  const name = (parts[0] || '').toUpperCase().trim();
+  const params = {};
+  for (const part of parts.slice(1)) {
+    const eqIdx = part.indexOf('=');
+    if (eqIdx === -1) continue;
+    params[part.slice(0, eqIdx).toUpperCase()] = part.slice(eqIdx + 1);
+  }
+  return { name, params, value };
+}
+
+// Extract a human-readable name from an ORGANIZER or ATTENDEE value.
+// Tries the CN param first, then strips mailto: prefix.
+function extractName(value, params) {
+  if (params.CN) return params.CN.replace(/^["']|["']$/g, '');
+  return value.replace(/^mailto:/i, '');
+}
+
+// Parse an iCal date/datetime string into an ISO string. Tolerant of both
+// date-only (YYYYMMDD) and datetime (YYYYMMDDTHHMMSS[Z]) forms.
+function parseIcalDate(value) {
+  if (!value) return null;
+  const v = value.replace('Z', '').trim();
+  if (v.length === 8) {
+    // Date-only: YYYYMMDD
+    return `${v.slice(0, 4)}-${v.slice(4, 6)}-${v.slice(6, 8)}`;
+  }
+  if (v.length >= 15 && v[8] === 'T') {
+    // Datetime: YYYYMMDDTHHMMSS
+    return `${v.slice(0, 4)}-${v.slice(4, 6)}-${v.slice(6, 8)}T${v.slice(9, 11)}:${v.slice(11, 13)}:${v.slice(13, 15)}${value.endsWith('Z') ? 'Z' : ''}`;
+  }
+  return value;
+}
+
+// ─── VEVENT block parser ──────────────────────────────────────────────────────
+
+function parseVEvent(lines) {
+  const event = {
+    summary: null,
+    dtstart: null,
+    dtend: null,
+    organizer: null,
+    attendees: [],
+    description: null,
+    location: null,
+    rrule: null,
+  };
+
+  for (const line of lines) {
+    if (!line.includes(':')) continue;
+    const { name, params, value } = parseProperty(line);
+    switch (name) {
+      case 'SUMMARY':     event.summary = value; break;
+      case 'DTSTART':     event.dtstart = parseIcalDate(value); break;
+      case 'DTEND':       event.dtend   = parseIcalDate(value); break;
+      case 'DTDUE':       event.dtend   = event.dtend ?? parseIcalDate(value); break;
+      case 'ORGANIZER':   event.organizer = extractName(value, params); break;
+      case 'ATTENDEE':    event.attendees.push(extractName(value, params)); break;
+      case 'DESCRIPTION': event.description = value.replace(/\\n/g, '\n').replace(/\\,/g, ','); break;
+      case 'LOCATION':    event.location = value; break;
+      case 'RRULE':       event.rrule = value; break;
+    }
+  }
+  return event;
+}
+
+// ─── VCALENDAR parser ─────────────────────────────────────────────────────────
+
+function parseIcs(raw) {
+  const unfolded = unfoldLines(raw);
+  const lines = unfolded.split('\n').map((l) => l.trim()).filter(Boolean);
+
+  if (!lines.some((l) => l === 'BEGIN:VCALENDAR')) {
+    return makeEnvelope({
+      text: raw.replace(/\r\n/g, '\n').trim(),
+      structured: null,
+      droppedInfo: [makeDropInfo({ kind: 'attachment', count: 1, reason: 'No BEGIN:VCALENDAR found; treating as plain text', recoverable: false })],
+    });
+  }
+
+  const events = [];
+  let inEvent = false;
+  let eventLines = [];
+  let droppedTodosVjournals = 0;
+  let inOther = false;
+
+  for (const line of lines) {
+    if (line === 'BEGIN:VEVENT') {
+      inEvent = true;
+      eventLines = [];
+    } else if (line === 'END:VEVENT') {
+      events.push(parseVEvent(eventLines));
+      inEvent = false;
+    } else if (line === 'BEGIN:VTODO' || line === 'BEGIN:VJOURNAL') {
+      inOther = true;
+      droppedTodosVjournals++;
+    } else if (line === 'END:VTODO' || line === 'END:VJOURNAL') {
+      inOther = false;
+    } else if (inEvent) {
+      eventLines.push(line);
+    }
+  }
+
+  const droppedInfo = [];
+  if (droppedTodosVjournals > 0) {
+    droppedInfo.push(makeDropInfo({
+      kind: 'attachment',
+      count: droppedTodosVjournals,
+      reason: 'VTODO and VJOURNAL components omitted (only VEVENT extracted)',
+      recoverable: false,
+    }));
+  }
+
+  // Build text representation
+  const textParts = events.map((e) => {
+    const parts = [];
+    if (e.summary) parts.push(`Event: ${e.summary}`);
+    if (e.dtstart) parts.push(`Start: ${e.dtstart}`);
+    if (e.dtend)   parts.push(`End: ${e.dtend}`);
+    if (e.organizer) parts.push(`Organizer: ${e.organizer}`);
+    if (e.attendees.length) parts.push(`Attendees: ${e.attendees.join(', ')}`);
+    if (e.location) parts.push(`Location: ${e.location}`);
+    if (e.description) parts.push(`\n${e.description}`);
+    return parts.join('\n');
+  });
+
+  return makeEnvelope({
+    text: textParts.join('\n\n').trim(),
+    structured: { events },
+    droppedInfo,
+  });
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Extract structured calendar data from a .ics file path.
+ * Returns the universal { text, structured, droppedInfo } envelope.
+ */
+export function extractCalendar(filePath) {
+  const raw = readFileSync(filePath, 'utf8');
+  return parseIcs(raw);
+}

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/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)
@@ -11,6 +12,7 @@ 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); }
@@ -53,4 +55,14 @@ try {
   }
 } 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/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 },

package/lib/hooks/stop-notify.mjs

@@ -161,7 +161,11 @@ try {
   }
 } catch { /* non-critical */ }
 
-let costNote = '';
+// Pricing readout is intentionally suppressed in user-facing notifications.
+// The session-cost ledger is still written (lines below) so OTel + dashboard
+// consumers can pick the data up when the observability surfaces are wired.
+// Do not reintroduce a costNote variable here without a deliberate decision
+// about whether to surface pricing to the user.
 let totalCostUsd = 0;
 let turnsLogged = 0;
 try {
@@ -232,17 +236,14 @@ try {
 
   saveTranscriptCheckpoints(checkpointPath, checkpoints);
 
-  if (totalCostUsd > 0) {
-    const label = turnsLogged > 1 ? `${turnsLogged} turns` : 'this response';
-    costNote = `~$${totalCostUsd.toFixed(2)} ${label}`;
-  }
+  // totalCostUsd and turnsLogged stay as ledger-write accumulators only.
+  // Downstream telemetry consumers read the session-cost.jsonl ledger.
 } catch { /* non-critical */ }
 
 const parts = [];
 if (fileCount > 0) parts.push(`${fileCount} file${fileCount !== 1 ? 's' : ''} updated`);
 if (tsResult === 'pass') parts.push('TS OK');
 else if (tsResult !== 'unchecked') parts.push(`TS: ${tsResult}`);
-if (costNote) parts.push(costNote);
 
 const hasWarnings = warnings.length > 0;
 const title = hasWarnings ? 'Construct — Review needed' : 'Construct';

package/lib/host-capabilities.mjs

@@ -215,6 +215,10 @@ export function detectHostCapabilities() {
   ];
 }
 
+export function formatHostCapabilitiesJson(hosts = detectHostCapabilities()) {
+  return JSON.stringify(hosts, null, 2) + '\n';
+}
+
 export function printHostCapabilities(hosts = detectHostCapabilities()) {
   console.log("Construct orchestration host capabilities:");
   for (const host of hosts) {
@@ -229,5 +233,10 @@ export function printHostCapabilities(hosts = detectHostCapabilities()) {
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  printHostCapabilities();
+  const args = new Set(process.argv.slice(2));
+  if (args.has('--json')) {
+    process.stdout.write(formatHostCapabilitiesJson());
+  } else {
+    printHostCapabilities();
+  }
 }