@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/hooks/continuation-enforcer.mjs

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-/**
- * lib/hooks/continuation-enforcer.mjs — Continuation enforcer hook — ensures agents complete tasks before stopping.
- *
- * Runs as PreToolUse on Stop. Checks workflow state for incomplete tasks and blocks the stop if high-priority work is unfinished, prompting the agent to continue.
- */
-// PostToolUse(TodoWrite) — fires after every todo list update.
-// 1. Counts remaining tasks and reminds agent to continue.
-// 2. Updates .cx/drive-state.json with current loop iteration state.
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
-import { join } from 'path';
-
-let input = {};
-try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
-
-const cwd = input?.cwd || process.cwd();
-const todos = input?.tool_input?.todos || [];
-
-const pending = todos.filter(t => t.status === 'pending');
-const inProgress = todos.filter(t => t.status === 'in_progress');
-const done = todos.filter(t => t.status === 'completed');
-const remaining = pending.length + inProgress.length;
-
-if (remaining > 0) {
-  const parts = [`[continuation-enforcer] ${remaining} task${remaining !== 1 ? 's' : ''} remain. Continue until all are complete.`];
-  if (inProgress.length > 0) parts.push(`  In progress: ${inProgress.map(t => t.content).join(', ')}`);
-  if (pending.length > 0) {
-    const shown = pending.slice(0, 5).map(t => t.content).join(', ');
-    const more = pending.length > 5 ? ` (+${pending.length - 5} more)` : '';
-    parts.push(`  Pending: ${shown}${more}`);
-  }
-  process.stdout.write(parts.join('\n') + '\n');
-}
-
-// Update .cx/drive-state.json if drive mode is active
-const driveStatePath = join(cwd, '.cx', 'drive-state.json');
-if (!existsSync(driveStatePath)) process.exit(0);
-
-try {
-  let ds = {};
-  try { ds = JSON.parse(readFileSync(driveStatePath, 'utf8')); } catch { /* fresh */ }
-
-  if (!ds.active) process.exit(0);
-
-  const total = todos.length;
-  ds.pendingTodos = remaining;
-  ds.updatedAt = new Date().toISOString();
-  ds.momentumScore = total > 0 ? done.length / total : 0;
-  ds.canStop = remaining === 0;
-
-  // Track current iteration snapshot
-  if (!ds.iterations) ds.iterations = [];
-  const n = ds.iteration || 1;
-  const existing = ds.iterations.findIndex(i => i.n === n);
-  const snapshot = {
-    n,
-    updatedAt: new Date().toISOString(),
-    pendingTodos: remaining,
-    doneTodos: done.length,
-    totalTodos: total,
-    inProgress: inProgress.map(t => t.content),
-  };
-  if (existing >= 0) ds.iterations[existing] = { ...ds.iterations[existing], ...snapshot };
-  else ds.iterations.push(snapshot);
-
-  // Increment iteration when all todos complete — ready for next loop pass
-  if (remaining === 0 && total > 0) ds.iteration = (ds.iteration || 1) + 1;
-
-  writeFileSync(driveStatePath, JSON.stringify(ds, null, 2));
-} catch { /* best effort */ }
-
-process.exit(0);

package/lib/hooks/drive-guard.mjs

@@ -1,89 +0,0 @@
-#!/usr/bin/env node
-/**
- * lib/hooks/drive-guard.mjs — Drive guard hook — enforces that work/drive commands follow the orchestration policy.
- *
- * Runs as PreToolUse on Bash for construct do/drive commands. Validates that the requested goal is routed through the orchestrator rather than bypassing the policy.
- */
-// Stop hook — blocks session stop when drive mode is active and acceptance criteria lack evidence.
-// Reads .cx/drive-state.json (active loop manifest) + .cx/workflow.json (acceptance criteria).
-// Superior to OmO's boulder: tracks per-criterion evidence, iteration history, momentum score.
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-let input = {};
-try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
-
-const cwd = input?.cwd || process.cwd();
-const driveStatePath = join(cwd, '.cx', 'drive-state.json');
-const workflowPath = join(cwd, '.cx', 'workflow.json');
-
-if (!existsSync(driveStatePath)) process.exit(0);
-
-let driveState = {};
-try { driveState = JSON.parse(readFileSync(driveStatePath, 'utf8')); } catch { process.exit(0); }
-
-if (!driveState.active || driveState.canStop) process.exit(0);
-
-// Collect all acceptance criteria from non-done workflow tasks
-let allCriteria = [];
-let pendingTaskCount = 0;
-try {
-  const wf = JSON.parse(readFileSync(workflowPath, 'utf8'));
-  const activeTasks = (wf.tasks || []).filter(t => t.status !== 'done' && t.status !== 'skipped');
-  pendingTaskCount = activeTasks.length;
-  for (const t of activeTasks) {
-    for (const c of (t.acceptanceCriteria || [])) {
-      if (!allCriteria.includes(c)) allCriteria.push(c);
-    }
-  }
-} catch { /* no workflow — rely on todo count */ }
-
-const criteriaStatus = driveState.criteriaStatus || {};
-const metCriteria = allCriteria.filter(c => criteriaStatus[c]?.met);
-const unmetCriteria = allCriteria.filter(c => !criteriaStatus[c]?.met);
-const pendingTodos = driveState.pendingTodos || 0;
-const iteration = driveState.iteration || 1;
-const momentum = driveState.momentumScore != null ? Math.round(driveState.momentumScore * 100) : null;
-
-// Decide whether to block
-const hasPendingWork = (unmetCriteria.length > 0) || (allCriteria.length === 0 && (pendingTodos > 0 || pendingTaskCount > 0));
-
-if (!hasPendingWork) {
-  // All criteria met or no criteria defined and no pending work — allow stop
-  process.exit(0);
-}
-
-// Emit rich drive-state report
-const lines = [
-  `[drive-guard] Drive mode active — iteration ${iteration}. Cannot stop yet.`,
-  '',
-];
-
-if (unmetCriteria.length > 0) {
-  lines.push(`Unmet criteria (${unmetCriteria.length}/${allCriteria.length}):`);
-  for (const c of unmetCriteria) lines.push(`  ✗ ${c}`);
-  lines.push('');
-}
-
-if (metCriteria.length > 0) {
-  lines.push(`Verified criteria (${metCriteria.length}/${allCriteria.length}):`);
-  for (const c of metCriteria) {
-    const ev = criteriaStatus[c]?.evidence || 'recorded';
-    lines.push(`  ✓ ${c} — ${ev.slice(0, 80)}`);
-  }
-  lines.push('');
-}
-
-if (allCriteria.length === 0) {
-  lines.push(`Remaining tasks: ${pendingTodos} todos, ${pendingTaskCount} workflow tasks`);
-  lines.push('');
-}
-
-if (momentum != null) lines.push(`Momentum: ${momentum}% (iteration ${iteration})`);
-
-lines.push('');
-lines.push(`[drive-guard] Record evidence by updating .cx/drive-state.json criteriaStatus, then criteria will pass.`);
-lines.push(`[drive-guard] To mark a criterion met: set criteriaStatus["<criterion>"] = { met: true, evidence: "..." }`);
-
-process.stderr.write(lines.join('\n') + '\n');
-process.exit(2);

package/lib/hooks/mcp-task-scope.mjs

@@ -1,47 +0,0 @@
-#!/usr/bin/env node
-/**
- * lib/hooks/mcp-task-scope.mjs — MCP task scope hook — constrains MCP tool use to the active workflow task scope.
- *
- * Runs as PreToolUse on MCP tool calls. Reads the active workflow task and warns when MCP tools are used outside the declared task scope.
- */
-// PreToolUse(mcp__*) — task-aware MCP scope advisor.
-// Reads the active workflow task's mcpScope field.
-// Warns (non-blocking) if calling an MCP not declared for the active task.
-// Exceeds OmO's per-task scoped MCPs: adds attribution, guidance, and audit trail
-// without requiring runtime MCP lifecycle management.
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-let input = {};
-try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
-
-const cwd = input?.cwd || process.cwd();
-const toolName = input?.tool_name || '';
-
-const match = toolName.match(/^mcp__([^_]+(?:__[^_]+)*)__/);
-if (!match) process.exit(0);
-const mcpServer = match[1].replace(/__/g, '-');
-
-const workflowPath = join(cwd, '.cx', 'workflow.json');
-if (!existsSync(workflowPath)) process.exit(0);
-
-try {
-  const wf = JSON.parse(readFileSync(workflowPath, 'utf8'));
-  const activeTaskKey = wf.currentTaskKey;
-  if (!activeTaskKey) process.exit(0);
-
-  const task = (wf.tasks || []).find(t => t.key === activeTaskKey);
-  if (!task?.mcpScope || task.mcpScope.length === 0) process.exit(0);
-
-  const scope = task.mcpScope;
-  const inScope = scope.some(s => mcpServer.includes(s) || s.includes(mcpServer));
-
-  if (!inScope) {
-    process.stderr.write(
-      `[mcp-scope] ${mcpServer} is not in mcpScope for task "${activeTaskKey}".\n` +
-      `[mcp-scope] Declared scope: ${scope.join(', ')}. Proceeding — verify this call is intentional.\n`
-    );
-  }
-} catch { /* best effort */ }
-
-process.exit(0);

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

@@ -1,43 +0,0 @@
-#!/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

@@ -1,54 +0,0 @@
-#!/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

@@ -1,62 +0,0 @@
-#!/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);

package/lib/prompt-composer.mjs

@@ -1,196 +0,0 @@
-/**
- * lib/prompt-composer.mjs — Assemble the final agent prompt from core file, task packet, and context digest.
- *
- * Called by the orchestrator and MCP dispatch layer before invoking a specialist agent.
- * Inlines role anti-pattern guidance from skills/roles/ when a role directive is present in the prompt.
- * Produces a deterministic, cache-friendly prompt string with a stable token footprint.
- */
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { buildContextDigest, readContextState } from './context-state.mjs';
-import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from './model-router.mjs';
-import { routeRequest } from './orchestration-policy.mjs';
-import { resolvePromptEntry, resolvePromptMetadata } from './prompt-metadata.mjs';
-import { loadWorkflow } from './workflow-state.mjs';
-
-function compactText(text, limit = 1200) {
-  if (!text) return '';
-  const normalized = String(text).trim();
-  return normalized.length <= limit ? normalized : `${normalized.slice(0, limit)}…`;
-}
-
-function readPromptBody(promptFile, rootDir) {
-  const filePath = path.join(rootDir, promptFile);
-  if (!fs.existsSync(filePath)) return '';
-  return fs.readFileSync(filePath, 'utf8').trim();
-}
-
-export function resolveBasePrompt(entryOrName, {
-  rootDir = process.cwd(),
-  registry,
-  fallback = '',
-} = {}) {
-  return resolvePromptContract(entryOrName, { rootDir, registry, fallback }).prompt;
-}
-
-export function resolvePromptContract(entryOrName, {
-  rootDir = process.cwd(),
-  registry,
-  fallback = '',
-} = {}) {
-  const directEntry = entryOrName && typeof entryOrName === 'object' ? entryOrName : null;
-  if (directEntry?.prompt) {
-    return {
-      prompt: String(directEntry.prompt).trim(),
-      metadata: resolvePromptMetadata(directEntry.name || entryOrName, { rootDir, registry }),
-    };
-  }
-
-  const agentName = directEntry?.name || entryOrName;
-  if (!agentName) return { prompt: fallback, metadata: {} };
-
-  const composed = composePrompt(agentName, { rootDir, registry });
-  return {
-    prompt: composed.prompt || fallback,
-    metadata: composed.metadata || {},
-  };
-}
-
-function resolveActiveTask(workflow) {
-  if (!workflow || !Array.isArray(workflow.tasks)) return null;
-  if (workflow.currentTaskKey) {
-    const currentTask = workflow.tasks.find((task) => task.key === workflow.currentTaskKey && !['done', 'skipped'].includes(task.status));
-    if (currentTask) return currentTask;
-  }
-  return workflow.tasks.find((task) => ['in-progress', 'in_progress', 'blocked_needs_user'].includes(task.status)) || null;
-}
-
-export function composePrompt(agentName, {
-  rootDir = process.cwd(),
-  registry,
-  task = null,
-  contextState = null,
-  hostConstraints = null,
-  intent = null,
-  workCategory = null,
-} = {}) {
-  const entry = resolvePromptEntry(agentName, { rootDir, registry });
-  if (!entry?.promptFile) return { metadata: {}, fragments: [], prompt: '' };
-
-  const metadata = resolvePromptMetadata(agentName, { rootDir, registry });
-  const fragments = [];
-
-  fragments.push({ type: 'core', label: entry.name, content: readPromptBody(entry.promptFile, rootDir) });
-
-  if (intent || workCategory) {
-    fragments.push({
-      type: 'task-context',
-      label: 'task-classification',
-      content: compactText(`Intent: ${intent || 'unknown'}\nWork category: ${workCategory || 'unknown'}`, 200),
-    });
-  }
-
-  if (task) {
-    const taskBlock = [
-      task.title ? `Task: ${task.title}` : null,
-      task.owner ? `Owner: ${task.owner}` : null,
-      Array.isArray(task.acceptanceCriteria) && task.acceptanceCriteria.length ? `Acceptance: ${task.acceptanceCriteria.join('; ')}` : null,
-      Array.isArray(task.readFirst) && task.readFirst.length ? `Read first: ${task.readFirst.join(', ')}` : null,
-      Array.isArray(task.doNotChange) && task.doNotChange.length ? `Do not change: ${task.doNotChange.join(', ')}` : null,
-    ].filter(Boolean).join('\n');
-    if (taskBlock) fragments.push({ type: 'task-packet', label: 'workflow-task', content: compactText(taskBlock, 500) });
-  }
-
-  const digest = buildContextDigest(contextState);
-  if (digest) {
-    fragments.push({ type: 'context-digest', label: 'context', content: compactText(JSON.stringify(digest), 600) });
-  }
-
-  if (hostConstraints) {
-    fragments.push({ type: 'host-constraints', label: 'host', content: compactText(JSON.stringify(hostConstraints), 300) });
-  }
-
-  const prompt = fragments.filter((fragment) => fragment.content).map((fragment) => fragment.content).join('\n\n');
-  return { metadata, fragments, prompt };
-}
-
-export function summarizePromptComposition(agentName, options = {}) {
-  const route = options.route || (options.request ? routeRequest({ request: options.request }) : null);
-  const executionContractModel = options.executionContractModel
-    || resolveExecutionContractModelMetadata({
-      envValues: options.envValues || {},
-      registryModels: options.registryModels || {},
-      requestedTier: options.requestedTier || selectModelTierForWorkCategory(route?.workCategory),
-      workCategory: route?.workCategory || null,
-    });
-  const composed = composePrompt(agentName, {
-    ...options,
-    intent: options.intent || route?.intent || null,
-    workCategory: options.workCategory || route?.workCategory || null,
-  });
-  const fragmentTypes = composed.fragments.map((fragment) => fragment.type);
-  const composedPromptHash = composed.prompt
-    ? crypto.createHash('sha256').update(composed.prompt).digest('hex')
-    : null;
-  const task = options.task || null;
-
-  return {
-    ...composed.metadata,
-    ...(composedPromptHash ? {
-      composedPromptHash,
-      composedPromptVersion: composedPromptHash.slice(0, 12),
-    } : {}),
-    promptFragmentCount: composed.fragments.length,
-    promptFragmentTypes: fragmentTypes,
-    promptHasTaskPacket: fragmentTypes.includes('task-packet'),
-    promptHasContextDigest: fragmentTypes.includes('context-digest'),
-    promptHasHostConstraints: fragmentTypes.includes('host-constraints'),
-    ...(task?.key ? { workflowTaskKey: task.key } : {}),
-    ...(task?.owner ? { workflowTaskOwner: task.owner } : {}),
-    ...(task?.phase ? { workflowTaskPhase: task.phase } : {}),
-    ...(route ? {
-      routeIntent: route.intent,
-      routeTrack: route.track,
-      routeWorkCategory: route.workCategory,
-      routeSpecialists: route.specialists,
-      routeDispatchPlan: route.dispatchPlan,
-    } : {}),
-    executionContractModel,
-  };
-}
-
-export function resolveRuntimePromptMetadata(agentName, {
-  rootDir = process.cwd(),
-  registry,
-  workflow = null,
-  task = null,
-  contextState = null,
-  request = null,
-  route = null,
-  registryModels = {},
-  envValues = {},
-  executionContractModel = null,
-  hostConstraints = null,
-} = {}) {
-  const resolvedWorkflow = workflow ?? loadWorkflow(rootDir);
-  const resolvedTask = task ?? resolveActiveTask(resolvedWorkflow);
-  const resolvedContextState = contextState ?? readContextState(rootDir);
-  const resolvedRoute = route || (request ? routeRequest({ request }) : null);
-
-  return summarizePromptComposition(agentName, {
-    rootDir,
-    registry,
-    task: resolvedTask,
-    contextState: resolvedContextState,
-    request,
-    route: resolvedRoute,
-    registryModels,
-    envValues,
-    executionContractModel,
-    hostConstraints,
-    intent: resolvedRoute?.intent || null,
-    workCategory: resolvedRoute?.workCategory || null,
-  });
-}