@geraldmaron/construct 1.0.0

package/lib/hooks/registry-sync.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/registry-sync.mjs — Registry sync hook — reminds to run construct sync after registry changes.
+ *
+ * Runs as PostToolUse after edits to agents/registry.json. Checks if the file was modified and emits a reminder to run construct sync to regenerate platform adapters.
+ */
+import { execSync } from 'child_process';
+
+const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
+if (!filePath.endsWith('/agents/registry.json')) process.exit(0);
+
+const toolkitDir = process.env.CX_TOOLKIT_DIR || `${process.env.HOME}/.construct`;
+try {
+  execSync('node sync-agents.mjs', {
+    cwd: toolkitDir,
+    stdio: 'pipe',
+    env: { ...process.env, CX_TOOLKIT_DIR: toolkitDir },
+    timeout: 12_000,
+  });
+} catch (e) {
+  process.stderr.write(`[registry-sync] Sync failed: ${e.message}\n`);
+}
+process.exit(0);

package/lib/hooks/scan-secrets.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/scan-secrets.mjs — Scan secrets hook — detects potential secrets in files before they are committed.
+ *
+ * Runs as PostToolUse after Edit/Write. Scans the modified file content against known secret patterns (API keys, tokens, passwords) and blocks (exit 2) on matches.
+ */
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+
+const SCAN_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.go', '.rs', '.rb', '.php', '.java', '.kt', '.swift',
+  '.sh', '.bash', '.zsh',
+  '.env', '.yaml', '.yml', '.toml', '.json', '.tf', '.tfvars', '.config',
+]);
+
+const PLACEHOLDER_PATTERNS = [
+  /\.\.\./,
+  /YOUR_KEY/i,
+  /<[^>]+>/,
+  /^sk-\.\.\./,
+  /^pk-lf-\.\.\./,
+  /__[A-Z_]+__/,
+];
+
+const SECRET_PATTERNS = [
+  { name: 'Anthropic API key', pattern: /ANTHROPIC_API_KEY\s*=\s*(sk-ant-[a-zA-Z0-9\-_]{20,})/i },
+  { name: 'OpenAI API key', pattern: /OPENAI_API_KEY\s*=\s*(sk-[a-zA-Z0-9]{40,})/i },
+  { name: 'OpenRouter key', pattern: /(sk-or-v1-[a-zA-Z0-9]{40,})/ },
+  { name: 'AWS access key', pattern: /(AKIA[0-9A-Z]{16})/ },
+  { name: 'Private key (PEM)', pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/ },
+  { name: 'GitHub personal access token', pattern: /(ghp_[a-zA-Z0-9]{36})/ },
+  { name: 'GitHub Actions token', pattern: /(ghs_[a-zA-Z0-9]{36})/ },
+  { name: 'Database URL with credentials', pattern: /DATABASE_URL\s*=\s*(postgresql:\/\/[^@]+:[^@]+@)/i },
+];
+
+function isPlaceholder(value) {
+  return PLACEHOLDER_PATTERNS.some((p) => p.test(value));
+}
+
+const filePath = process.env.TOOL_INPUT_FILE_PATH;
+
+if (!filePath) process.exit(0);
+
+const ext = extname(filePath).toLowerCase();
+if (!SCAN_EXTENSIONS.has(ext)) process.exit(0);
+
+let content;
+try {
+  content = readFileSync(filePath, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+const lines = content.split('\n');
+const findings = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  for (const { name, pattern } of SECRET_PATTERNS) {
+    const match = pattern.exec(line);
+    if (!match) continue;
+    const captured = match[1] ?? match[0];
+    if (isPlaceholder(captured)) continue;
+    findings.push({ name, line: i + 1, value: captured.slice(0, 20) + '...' });
+  }
+}
+
+if (findings.length === 0) process.exit(0);
+
+process.stderr.write('[scan-secrets] BLOCKED: Secret(s) detected in ' + filePath + '\n');
+for (const { name, line, value } of findings) {
+  process.stderr.write(`  Line ${line}: ${name} — matched value starts with: ${value}\n`);
+}
+process.stderr.write('Remove or rotate the secret before writing this file.\n');
+process.exit(2);

package/lib/hooks/session-start.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/session-start.mjs — Session start hook — emits resumable project context at the start of each session.
+ *
+ * Runs at session start. Reads .cx/context.json, workflow state, git status, and efficiency log to produce a structured resume message. Non-blocking — always exits 0.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { loadWorkflow, summarizeWorkflow, alignmentFindings } from '../workflow-state.mjs';
+import { buildCompactEfficiencyDigest, readEfficiencyLog } from '../efficiency.mjs';
+import { readContextState, contextSummaryLine } from '../context-state.mjs';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const CONSTRUCT_BIN = resolve(MODULE_DIR, '..', '..', 'bin', 'construct');
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const cwd = input?.cwd || process.cwd();
+const projectName = cwd.split('/').pop() || 'project';
+const date = new Date().toISOString().slice(0, 10);
+
+// Load context — project-local first, global fallback
+const localCtx = join(cwd, '.cx', 'context.md');
+const globalCtx = join(homedir(), '.cx', 'context.md');
+let context = '';
+const localState = readContextState(cwd);
+const globalState = localState ? null : readContextState(homedir());
+const stateContext = localState || globalState;
+if (stateContext?.markdown) {
+  const raw = String(stateContext.markdown);
+  context = raw.length > 1800 ? `${raw.slice(0, 400)}\n…\n${raw.slice(-1400)}` : raw;
+} else if (existsSync(localCtx)) {
+  try { const raw = readFileSync(localCtx, 'utf8'); context = raw.length > 1800 ? `${raw.slice(0, 400)}\n…\n${raw.slice(-1400)}` : raw; } catch { /* best effort */ }
+} else if (existsSync(globalCtx)) {
+  try { const raw = readFileSync(globalCtx, 'utf8'); context = raw.length > 1800 ? `${raw.slice(0, 400)}\n…\n${raw.slice(-1400)}` : raw; } catch { /* best effort */ }
+}
+const contextSummary = contextSummaryLine(stateContext);
+
+// Git status
+let uncommitted = 0;
+let recentCommits = '';
+try {
+  const status = execSync(`git -C "${cwd}" status --short 2>/dev/null`, { timeout: 5000 }).toString();
+  uncommitted = status.split('\n').filter(l => l.trim()).length;
+} catch { /* not a git repo or git unavailable */ }
+
+try {
+  recentCommits = execSync(`git -C "${cwd}" log --oneline -3 2>/dev/null`, { timeout: 5000 }).toString().trim();
+} catch { /* best effort */ }
+
+// Pending typecheck warning
+const tcPath = join(homedir(), '.cx', 'pending-typecheck.txt');
+let pendingNote = '';
+try {
+  const pending = existsSync(tcPath) ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean) : [];
+  if (pending.length > 0) pendingNote = '\nNote: TypeScript was not checked last session.';
+} catch { /* best effort */ }
+
+const statusLine = uncommitted > 0
+  ? `Current: ${uncommitted} uncommitted file${uncommitted !== 1 ? 's' : ''}`
+  : 'Current: clean working tree';
+
+const recentLine = recentCommits
+  ? `Recent: ${recentCommits.split('\n').join(' · ')}`
+  : '';
+
+const header = `## Resuming — ${projectName} · ${date}\nNote: You are currently working on the **${projectName}** project.`;
+const footer = [statusLine, recentLine].filter(Boolean).join(' · ');
+
+let workflowNote = '';
+try {
+  const workflow = loadWorkflow(cwd);
+  if (workflow) {
+    const findings = alignmentFindings(workflow);
+    const high = findings.filter((finding) => finding.severity === 'HIGH').length;
+    const medium = findings.filter((finding) => finding.severity === 'MEDIUM').length;
+    workflowNote = `\n## Active Construct Workflow\n${summarizeWorkflow(workflow)}\nAlignment: ${high ? `${high} high issue${high === 1 ? '' : 's'}` : 'no high issues'}${medium ? `, ${medium} warning${medium === 1 ? '' : 's'}` : ''}\n`;
+  }
+} catch {
+  // best effort only
+}
+
+const body = context || '## Fresh start — no prior context found.\n';
+const efficiency = buildCompactEfficiencyDigest(readEfficiencyLog(homedir()));
+const efficiencyNote = efficiency?.compact
+  ? `\n## Session efficiency\n${efficiency.compact}\n`
+  : '';
+const stateNote = contextSummary ? `\n## Context digest\n${contextSummary}\n` : '';
+const memoryDirective = `\n## Required first actions\nBefore responding: call memory_search("${projectName}") to retrieve prior session context and user preferences. Apply any relevant results immediately. If context is degraded, compact before broad rereads.\n`;
+process.stdout.write(`${header}\n${body}${stateNote}${workflowNote}${efficiencyNote}${memoryDirective}\n${footer}${pendingNote}\n`);
+process.exit(0);

package/lib/hooks/stop-notify.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/stop-notify.mjs — Stop notify hook — emits a session summary notification when Claude stops.
+ *
+ * Runs as a Stop hook. Summarizes the session work, active workflow state, and efficiency signals into a final message written to stdout for the user.
+ */
+import { readFileSync, writeFileSync, existsSync, appendFileSync, statSync } from 'fs';
+import { execSync } from 'child_process';
+import { homedir } from 'os';
+import { join } from 'path';
+import { loadWorkflow, summarizeWorkflow, alignmentFindings } from '../workflow-state.mjs';
+
+function readLastTranscriptUsage(transcriptPath) {
+  try {
+    if (!transcriptPath || !existsSync(transcriptPath)) return null;
+    const size = statSync(transcriptPath).size;
+    const readSize = Math.min(size, 256 * 1024);
+    const content = readFileSync(transcriptPath, 'utf8');
+    const tail = content.slice(-readSize);
+    const lines = tail.split(/\r?\n/).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const obj = JSON.parse(lines[i]);
+        const usage = obj?.message?.usage || obj?.usage;
+        if (usage && (usage.input_tokens || usage.output_tokens)) return usage;
+      } catch { /* skip */ }
+    }
+  } catch { /* best effort */ }
+  return null;
+}
+
+function resolveAttribution(workflow) {
+  try {
+    if (!workflow) return { agent: 'construct' };
+    const active = (workflow.tasks || []).find((t) => t.status === 'in-progress' || t.status === 'in_progress');
+    if (active?.owner) return { agent: active.owner, taskKey: active.key };
+    return { agent: 'construct' };
+  } catch {
+    return { agent: 'construct' };
+  }
+}
+
+// Stop hooks must echo stdin to stdout
+let raw = '';
+try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+if (raw) process.stdout.write(raw);
+
+const home = homedir();
+const tsResultPath = join(home, '.cx', 'ts-result.txt');
+const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');
+const countPath = join(home, '.cx', 'files-changed-count.txt');
+const costLogPath = join(home, '.cx', 'session-cost.jsonl');
+const lastAgentPath = join(home, '.cx', 'last-agent.json');
+
+// Read TS result
+let tsResult = 'unchecked';
+try { tsResult = existsSync(tsResultPath) ? readFileSync(tsResultPath, 'utf8').trim() : 'unchecked'; } catch { /* best effort */ }
+
+// Read and clear warn flags
+let warnings = [];
+try {
+  if (existsSync(warnFlagsPath)) {
+    warnings = readFileSync(warnFlagsPath, 'utf8').split('\n').filter(Boolean);
+    writeFileSync(warnFlagsPath, '');
+  }
+} catch { /* best effort */ }
+
+// Read and clear files-changed count
+let fileCount = 0;
+try {
+  if (existsSync(countPath)) {
+    fileCount = parseInt(readFileSync(countPath, 'utf8').trim() || '0', 10) || 0;
+    writeFileSync(countPath, '0');
+  }
+} catch { /* best effort */ }
+
+// Estimate cost from stdin usage tokens using Sonnet 4.5/4.6 defaults.
+let costNote = '';
+try {
+  const payload = raw ? JSON.parse(raw) : {};
+  let usage = payload?.usage || payload?.stop_hook_active?.usage || null;
+  const transcriptPath = payload?.transcript_path || payload?.transcriptPath || process.env.CLAUDE_TRANSCRIPT_PATH;
+  if (!usage || (!usage.input_tokens && !usage.output_tokens)) {
+    const fromTranscript = readLastTranscriptUsage(transcriptPath);
+    if (fromTranscript) usage = fromTranscript;
+  }
+  usage = usage || {};
+  const inputTokens = usage?.input_tokens || 0;
+  const outputTokens = usage?.output_tokens || 0;
+  const cacheReadInputTokens = usage?.cache_read_input_tokens || 0;
+  const cacheCreation5mInputTokens = usage?.cache_creation?.ephemeral_5m_input_tokens || usage?.cache_creation_5m_input_tokens || 0;
+  const cacheCreation1hInputTokens = usage?.cache_creation?.ephemeral_1h_input_tokens || usage?.cache_creation_1h_input_tokens || 0;
+  const explicitCacheCreationInputTokens = usage?.cache_creation_input_tokens || 0;
+  const cacheCreationInputTokens = explicitCacheCreationInputTokens || cacheCreation5mInputTokens + cacheCreation1hInputTokens;
+  if (inputTokens || outputTokens) {
+    const cost = (
+      inputTokens * 3 +
+      cacheCreation5mInputTokens * 3.75 +
+      cacheCreation1hInputTokens * 6 +
+      Math.max(0, cacheCreationInputTokens - cacheCreation5mInputTokens - cacheCreation1hInputTokens) * 3.75 +
+      cacheReadInputTokens * 0.3 +
+      outputTokens * 15
+    ) / 1_000_000;
+    costNote = `~${cost.toFixed(2)} this response`;
+
+    // Read agent attribution recorded by agent-tracker hook (best effort, cleared after read)
+    let agentName = null;
+    let taskKey = null;
+    try {
+      if (existsSync(lastAgentPath)) {
+        const lastAgent = JSON.parse(readFileSync(lastAgentPath, 'utf8'));
+        agentName = lastAgent.agent || null;
+        taskKey = lastAgent.taskKey || null;
+        writeFileSync(lastAgentPath, '');
+      }
+    } catch { /* best effort */ }
+
+    // Fallback attribution: active workflow task owner, else 'construct'
+    if (!agentName) {
+      try {
+        const wf = loadWorkflow(process.cwd());
+        const resolved = resolveAttribution(wf);
+        agentName = resolved.agent;
+        if (!taskKey && resolved.taskKey) taskKey = resolved.taskKey;
+      } catch { agentName = 'construct'; }
+    }
+
+    try {
+      const entry = { ts: new Date().toISOString(), input_tokens: inputTokens, output_tokens: outputTokens, cost_usd: cost };
+      if (cacheReadInputTokens) entry.cache_read_input_tokens = cacheReadInputTokens;
+      if (cacheCreationInputTokens) entry.cache_creation_input_tokens = cacheCreationInputTokens;
+      if (cacheCreation5mInputTokens) entry.cache_creation_5m_input_tokens = cacheCreation5mInputTokens;
+      if (cacheCreation1hInputTokens) entry.cache_creation_1h_input_tokens = cacheCreation1hInputTokens;
+      if (agentName) entry.agent = agentName;
+      if (taskKey) entry.task_key = taskKey;
+      appendFileSync(costLogPath, JSON.stringify(entry) + '\n');
+    } catch { /* best effort */ }
+  }
+} catch { /* payload parse failure */ }
+
+// Executive Summary from Workflow
+let execSummary = '';
+try {
+  const workflow = loadWorkflow(process.cwd());
+  if (workflow) {
+    const findings = alignmentFindings(workflow);
+    const high = findings.filter(f => f.severity === 'HIGH').length;
+    const phase = workflow.phase.toUpperCase();
+    execSummary = `${phase}: ${workflow.status}${high > 0 ? ` (${high} blocks)` : ''}`;
+  }
+} catch { /* best effort */ }
+
+// Compose message parts
+const parts = [];
+if (execSummary) parts.push(execSummary);
+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';
+const body = [
+  ...warnings.slice(0, 3),
+  parts.join(' · '),
+].filter(Boolean).join('\n');
+
+// Fire notification
+const platform = process.platform;
+try {
+  if (platform === 'darwin') {
+    const escaped = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+    const titleEsc = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    execSync(`osascript -e 'display notification "${escaped}" with title "${titleEsc}"'`, {
+      timeout: 5000,
+      stdio: 'pipe',
+    });
+  } else if (platform === 'linux') {
+    execSync(`notify-send "${title}" "${body.replace(/"/g, '\\"')}"`, {
+      timeout: 5000,
+      stdio: 'pipe',
+    });
+  } else {
+    process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
+  }
+} catch {
+  // Fallback to stderr if notification fails
+  process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
+}
+
+process.exit(0);

package/lib/hooks/stop-typecheck.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/stop-typecheck.mjs — Stop typecheck hook — runs TypeScript type-check at session end and records result.
+ *
+ * Runs as a Stop hook. Invokes tsc --noEmit on the project and records pass/fail to ~/.cx/pending-typecheck.txt for the next session-start hook to surface.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+
+// Stop hooks must echo stdin to stdout
+let raw = '';
+try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+if (raw) process.stdout.write(raw);
+
+const home = homedir();
+const tcPath = join(home, '.cx', 'pending-typecheck.txt');
+const tsResultPath = join(home, '.cx', 'ts-result.txt');
+const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');
+
+// Read pending files
+const pending = existsSync(tcPath)
+  ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean)
+  : [];
+
+if (pending.length === 0) {
+  try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
+  process.exit(0);
+}
+
+// Clear pending list immediately (don't re-run on next session if this run crashes)
+try { writeFileSync(tcPath, ''); } catch { /* best effort */ }
+
+// Find nearest tsconfig.json by walking up from first pending file's directory
+function findTsConfig(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, 'tsconfig.json');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+const startDir = dirname(pending[0]);
+const tsconfig = findTsConfig(startDir);
+
+if (!tsconfig) {
+  try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
+  process.exit(0);
+}
+
+const projectDir = dirname(tsconfig);
+
+try {
+  execSync('npx tsc --noEmit --pretty false', {
+    cwd: projectDir,
+    stdio: 'pipe',
+    timeout: 90_000,
+  });
+  try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
+} catch (e) {
+  const output = (e.stdout?.toString() || '') + (e.stderr?.toString() || '');
+  // Count error lines (lines ending with "error TS####:")
+  const errorLines = output.split('\n').filter(l => /error TS\d+:/.test(l));
+  const count = errorLines.length || 1;
+
+  try { writeFileSync(tsResultPath, `${count} error${count !== 1 ? 's' : ''}`); } catch { /* best effort */ }
+
+  try {
+    const existing = existsSync(warnFlagsPath) ? readFileSync(warnFlagsPath, 'utf8') : '';
+    writeFileSync(warnFlagsPath, existing + `TypeScript: ${count} error${count !== 1 ? 's' : ''}\n`);
+  } catch { /* best effort */ }
+
+  process.stderr.write(
+    `[stop-typecheck] TypeScript found ${count} error${count !== 1 ? 's' : ''} that need attention. The code runs but won't compile cleanly. Review before releasing.\n`
+  );
+}
+
+process.exit(0);

package/lib/hooks/task-completed-guard.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/task-completed-guard.mjs — Task completed guard hook — enforces verification evidence before marking tasks done.
+ *
+ * Runs as PreToolUse on workflow_update_task. Checks that implement-phase tasks include verification evidence before allowing status to be set to done. Exits 2 to block.
+ */
+import { loadWorkflow, validateWorkflowState } from '../workflow-state.mjs';
+
+function readInput() {
+  try {
+    const chunks = [];
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    return new Promise((resolve) => {
+      process.stdin.on('end', () => {
+        try {
+          const raw = Buffer.concat(chunks).toString('utf8');
+          resolve(raw ? JSON.parse(raw) : {});
+        } catch {
+          resolve({});
+        }
+      });
+    });
+  } catch {
+    return {};
+  }
+}
+
+const input = await readInput();
+const cwd = input.cwd || input.workspace_dir || process.cwd();
+const workflow = loadWorkflow(cwd);
+
+if (!workflow) process.exit(0);
+
+const result = validateWorkflowState(workflow);
+if (result.valid) process.exit(0);
+
+process.stderr.write([
+  '[construct] Task completion blocked by workflow validation.',
+  ...result.errors.map((error) => `- ${error}`),
+  'Update .cx/workflow.json with owner, acceptance criteria, dependencies, and verification before marking the task complete.',
+  '',
+].join('\n'));
+process.exit(2);

package/lib/hooks/teammate-idle-guard.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/teammate-idle-guard.mjs — Teammate idle guard hook — warns when a spawned agent has been idle too long.
+ *
+ * Runs as PostToolUse after Agent tool calls. Tracks agent start times and emits a warning if an agent appears idle or unresponsive beyond the idle threshold.
+ */
+import { loadWorkflow } from '../workflow-state.mjs';
+
+async function readInput() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  try {
+    const raw = Buffer.concat(chunks).toString('utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function namesFromInput(input) {
+  return [
+    input.teammate,
+    input.teammate_name,
+    input.agent,
+    input.agent_name,
+    input.name,
+  ].filter((value) => typeof value === 'string' && value.trim()).map((value) => value.trim());
+}
+
+const input = await readInput();
+const cwd = input.cwd || input.workspace_dir || process.cwd();
+const names = namesFromInput(input);
+const workflow = loadWorkflow(cwd);
+
+if (!workflow || names.length === 0) process.exit(0);
+
+const active = (workflow.tasks || []).find((task) =>
+  names.includes(task.owner)
+  && task.status === 'in-progress'
+  && (!Array.isArray(task.notes) || task.notes.length === 0)
+  && (!Array.isArray(task.verification) || task.verification.length === 0)
+);
+
+if (!active) process.exit(0);
+
+process.stderr.write([
+  `[construct] ${names[0]} is going idle with active task ${active.key} but no workflow update.`,
+  'Before going idle, update .cx/workflow.json with one of:',
+  '- status=done plus verification evidence',
+  '- status=blocked with the blocker',
+  '- status=blocked_needs_user and a NEEDS_MAIN_INPUT packet for the primary persona',
+  '',
+].join('\n'));
+process.exit(2);

package/lib/hooks/workflow-guard.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/workflow-guard.mjs — Workflow guard hook — enforces that significant work flows through the workflow state.
+ *
+ * Runs as PreToolUse on implement tasks. Checks that the active workflow task is set before allowing non-trivial Bash or Edit operations. Warns without blocking.
+ */
+import { readFileSync } from "node:fs";
+import { loadWorkflow, alignmentFindings, summarizeWorkflow } from "../workflow-state.mjs";
+
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+
+const text = [
+  input?.prompt,
+  input?.message,
+  input?.transcript,
+  input?.last_message,
+  input?.assistant_message
+].filter(Boolean).join("\n").toLowerCase();
+
+if (/\b(stop|pause|halt|enough|abort|cancel)\b/.test(text)) {
+  process.exit(0);
+}
+
+const cwd = input?.cwd || process.cwd();
+const workflow = loadWorkflow(cwd);
+if (!workflow || workflow.status !== "in-progress") {
+  process.exit(0);
+}
+
+const tasks = workflow.tasks || [];
+const openTasks = tasks.filter((task) => !["done", "skipped"].includes(task.status));
+const findings = alignmentFindings(workflow).filter((finding) => finding.severity === "HIGH");
+
+if (openTasks.length === 0 && findings.length === 0) {
+  process.exit(0);
+}
+
+const next = tasks.find((task) => task.key === workflow.currentTaskKey) || openTasks[0];
+const lines = [
+  "Construct workflow is still active.",
+  summarizeWorkflow(workflow)
+];
+
+if (next) {
+  lines.push(`Next task: ${next.key} ${next.title} -> ${next.owner} [${next.status}]`);
+}
+
+if (findings.length > 0) {
+  lines.push(`Alignment blockers: ${findings.length}`);
+  for (const finding of findings.slice(0, 3)) {
+    lines.push(`- ${finding.task ? `${finding.task}: ` : ""}${finding.issue}`);
+  }
+}
+
+lines.push("Continue the current workflow, update .cx/workflow.json, or explicitly say stop/pause to end.");
+console.error(lines.join("\n"));
+process.exit(2);