@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/hooks/artifact-release-gate.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/artifact-release-gate.mjs — PostToolUse advisory structure/visual gate for typed docs.
+ *
+ * Runs after Write/Edit/MultiEdit on docs/** and .cx/research/** markdown artifacts.
+ * Surfaces manifest structure and visual violations on stderr during drafting; does not
+ * block the edit (full release gate runs via `construct artifact validate` and CI).
+ *
+ * Notice-only: suppressed when stderr is not a TTY, CI=true, or NODE_ENV=test.
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @p95ms 80
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ * @exits 0 = pass
+ */
+
+import { readFileSync } from 'node:fs';
+import { checkArtifactGateNotice, formatArtifactGateNotice } from '../artifact-gate-notice.mjs';
+
+function shouldEmitNotice() {
+  if (process.env.CI === 'true') return false;
+  if (process.env.NODE_ENV === 'test') return false;
+  if (!process.stderr.isTTY) return false;
+  return true;
+}
+
+let filePath = process.env.TOOL_INPUT_FILE_PATH;
+let cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+if (!filePath) {
+  try {
+    const input = JSON.parse(readFileSync(0, 'utf8'));
+    filePath = input?.tool_input?.file_path || input?.tool_input?.path;
+    if (input?.cwd) cwd = input.cwd;
+  } catch { /* no stdin */ }
+}
+if (!filePath) process.exit(0);
+
+const result = checkArtifactGateNotice(filePath, { cwd });
+if (!result || !shouldEmitNotice()) process.exit(0);
+
+process.stderr.write(formatArtifactGateNotice(result));
+process.exit(0);

package/lib/hooks/brand-prose-lint.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/brand-prose-lint.mjs — PostToolUse hook: block brand drift at write time.
+ *
+ * Enforces marketing voice, retired typography, and Construct/cli naming on governed
+ * markdown and template surfaces. Mirrors scripts/audit/03d-brand.mjs scope.
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @p95ms 40
+ * @maxBlockingScope PostToolUse
+ * @exits 0 = pass | 2 = block tool call
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { formatBrandViolations, lintFile } from '../brand-prose.mjs';
+
+let filePath = process.env.TOOL_INPUT_FILE_PATH;
+if (!filePath) {
+  try {
+    const input = JSON.parse(readFileSync(0, 'utf8'));
+    filePath = input?.tool_input?.file_path || input?.tool_input?.path;
+  } catch {}
+}
+if (!filePath) process.exit(0);
+
+const rootDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const result = lintFile(filePath, { rootDir });
+if (!result.violations.length) process.exit(0);
+
+const output = formatBrandViolations([result]);
+process.stderr.write(`${output}\n`);
+process.stderr.write(
+  '\nBrand policy blocked this edit (marketing voice, retired fonts, or Construct/cli naming). See docs/reference/branding.md and docs/STYLE.md.\n',
+);
+process.exit(2);

package/lib/hooks/graph-impact-advisory.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/graph-impact-advisory.mjs — PostToolUse hook: test-impact advisory on code edits.
+ *
+ * On Write|Edit under lib/, bin/, tests/, or src/, runs forward change-impact
+ * over the dependency graph and surfaces affected tests on stderr. Non-blocking;
+ * complements `construct impact` CLI and the doctor graph-staleness watcher.
+ *
+ * @p95ms 50
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @exits 0 = pass
+ */
+
+import { readFileSync } from 'node:fs';
+
+import { computeImpact } from '../graph/impact.mjs';
+import { checkGraphStaleness } from '../graph/staleness.mjs';
+
+const CODE_RE = /^(lib|bin|src|tests)\/.*\.(?:m?js|jsx?|tsx?|cjs)$/;
+
+let filePath = process.env.TOOL_INPUT_FILE_PATH;
+let cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+if (!filePath) {
+  try {
+    const input = JSON.parse(readFileSync(0, 'utf8'));
+    filePath = input?.tool_input?.file_path || input?.tool_input?.path;
+    if (input?.cwd) cwd = input.cwd;
+  } catch { /* stdin optional */ }
+}
+if (!filePath) process.exit(0);
+
+const rel = filePath.startsWith(cwd)
+  ? filePath.slice(cwd.length).replace(/^\/+/, '')
+  : filePath;
+
+if (!CODE_RE.test(rel)) process.exit(0);
+
+const stale = checkGraphStaleness(cwd);
+if (stale.stale) {
+  process.stderr.write(
+    `[graph-impact] dependency graph stale (${stale.staleReason}). Run \`construct graph build\` before trusting impact output.\n`,
+  );
+}
+
+const impact = computeImpact({ rootDir: cwd, changedFiles: [rel] });
+if (!impact.graphPresent) {
+  process.stderr.write('[graph-impact] no .cx/graph/ present — run `construct graph build` to enable test-impact advisories.\n');
+  process.exit(0);
+}
+
+if (impact.affectedTests.length > 0) {
+  const preview = impact.affectedTests.slice(0, 5).map((t) => t.replace(/^test:/, '')).join(', ');
+  const more = impact.affectedTests.length > 5 ? ` (+${impact.affectedTests.length - 5} more)` : '';
+  process.stderr.write(`[graph-impact] ${rel} may affect: ${preview}${more}\n`);
+} else if (impact.coverageGaps.length > 0) {
+  process.stderr.write(`[graph-impact] ${rel} has no capability edge in the dependency graph (coverage gap).\n`);
+}
+
+process.exit(0);

package/lib/hooks/session-optimize.mjs

@@ -3,7 +3,7 @@
  * lib/hooks/session-optimize.mjs — Session end optimization hook — triggers agent optimization for low-performers.
  *
  * Runs as a Stop hook at session end. Checks recent performance reviews for agents with avgScore < 0.7
- * and invokes `construct optimize <agent>` to generate and apply improvement patches.
+ * and schedules `construct optimize <agent> --dry-run` detached so the Stop hook returns within budget.
  *
  * @p95ms 300
  * @maxBlockingScope Stop (non-blocking, async)
@@ -12,110 +12,102 @@
  * @matcher  *
  * @exits 0 = pass
  */
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONSTRUCT_BIN = join(__dirname, '..', '..', 'bin', 'construct');
 
-const OPTIMIZATION_THRESHOLD = 0.7;     // Score below this triggers optimization
-const MIN_TRACES_PER_AGENT = 3;          // Minimum traces needed for optimization
-const OPTIMIZATION_DAYS = 7;            // Look back 7 days for performance data
+const OPTIMIZATION_THRESHOLD = 0.7;
+const MIN_TRACES_PER_AGENT = 3;
+const OPTIMIZATION_DAYS = 7;
 const OPTIMIZATION_LOG_DIR = join(homedir(), '.cx', 'optimization-logs');
+const REVIEWS_DIR = join(homedir(), '.cx', 'performance-reviews');
 
-// Ensure optimization log directory exists
 mkdirSync(OPTIMIZATION_LOG_DIR, { recursive: true });
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
 
-// Only run for Construct sessions
 const cwd = input?.cwd || process.cwd();
 const projectName = cwd.split('/').pop() || 'project';
 
-// Skip if this is not a Construct project or in global mode
 if (projectName !== 'construct' && !existsSync(join(cwd, '.cx'))) {
   process.exit(0);
 }
 
-// Reviews older than this trigger an auto-refresh on the next session-stop.
-// Six hours keeps optimization signal current without re-running review on
-// every short session. Operators can still run `construct review` manually.
 const REVIEW_REFRESH_MS = 6 * 60 * 60 * 1000;
 
+function spawnDetached(args, { cwd: workDir = cwd } = {}) {
+  try {
+    const child = spawn(process.execPath, args, {
+      cwd: workDir,
+      stdio: 'ignore',
+      detached: true,
+      env: process.env,
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function listReviewJsonFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => join(dir, name));
+}
+
 function maybeRefreshReviews() {
-  const reviewsDir = join(homedir(), '.cx', 'performance-reviews');
   let needsRefresh = false;
   try {
-    if (!existsSync(reviewsDir)) {
+    const files = listReviewJsonFiles(REVIEWS_DIR);
+    if (files.length === 0) {
       needsRefresh = true;
     } else {
-      const files = spawnSync('find', [reviewsDir, '-name', '*.json', '-type', 'f'], {
-        encoding: 'utf8', timeout: 5000,
-      }).stdout.trim().split('\n').filter(Boolean);
-      if (files.length === 0) {
-        needsRefresh = true;
-      } else {
-        const newestMs = files.reduce((acc, f) => {
-          try {
-            const m = Number(spawnSync('stat', ['-f', '%m', f], { encoding: 'utf8' }).stdout.trim());
-            return Number.isFinite(m) ? Math.max(acc, m * 1000) : acc;
-          } catch { return acc; }
-        }, 0);
-        if (Date.now() - newestMs > REVIEW_REFRESH_MS) needsRefresh = true;
-      }
+      const newestMs = files.reduce((acc, filePath) => {
+        try {
+          return Math.max(acc, statSync(filePath).mtimeMs);
+        } catch {
+          return acc;
+        }
+      }, 0);
+      if (Date.now() - newestMs > REVIEW_REFRESH_MS) needsRefresh = true;
     }
-  } catch { /* tolerate fs errors silently — refresh is best-effort */ }
+  } catch {
+    /* refresh is best-effort */
+  }
 
   if (!needsRefresh) return;
 
-  // Refresh detached so the Stop hook does not block on telemetry latency.
-  try {
-    spawnSync(process.execPath, [CONSTRUCT_BIN, 'review', '--quiet'], {
-      stdio: 'ignore',
-      timeout: 60_000,
-      detached: true,
-    });
-  } catch { /* refresh is best-effort; manual `construct review` is always available */ }
+  spawnDetached([CONSTRUCT_BIN, 'review', '--quiet']);
 }
 
-// Read the most recent performance review
 function getLatestPerformanceReview() {
-  const reviewsDir = join(homedir(), '.cx', 'performance-reviews');
-  if (!existsSync(reviewsDir)) return null;
-
   try {
-    const files = spawnSync('find', [reviewsDir, '-name', '*.json', '-type', 'f'], {
-      encoding: 'utf8',
-      timeout: 5000
-    }).stdout.trim().split('\n').filter(Boolean);
-
+    const files = listReviewJsonFiles(REVIEWS_DIR);
     if (files.length === 0) return null;
-    
-    // Sort by modification time, newest first
+
     files.sort((a, b) => {
       try {
-        const statA = spawnSync('stat', ['-f', '%m', a], { encoding: 'utf8' }).stdout.trim();
-        const statB = spawnSync('stat', ['-f', '%m', b], { encoding: 'utf8' }).stdout.trim();
-        return parseInt(statB) - parseInt(statA);
+        return statSync(b).mtimeMs - statSync(a).mtimeMs;
       } catch {
         return 0;
       }
     });
-    
-    const latestFile = files[0];
-    const content = readFileSync(latestFile, 'utf8');
-    return JSON.parse(content);
+
+    return JSON.parse(readFileSync(files[0], 'utf8'));
   } catch (error) {
     console.error(`Error reading performance reviews: ${error.message}`);
     return null;
   }
 }
 
-// Check if agent needs optimization
 function needsOptimization(agentStats) {
   return (
     agentStats.scoredInvocations >= MIN_TRACES_PER_AGENT &&
@@ -124,101 +116,25 @@ function needsOptimization(agentStats) {
   );
 }
 
-// Run optimization for a specific agent
-function optimizeAgent(agentName) {
-  console.log(`🔧 Optimizing ${agentName} (score < ${OPTIMIZATION_THRESHOLD})`);
-  
-  const logFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-${agentName}.log`);
-  const startTime = Date.now();
-  
-  try {
-    // Preview only. The new contract requires an explicit --apply from the
-    // operator; hook-driven runs must never modify prompt files.
-    const result = spawnSync(CONSTRUCT_BIN, ['optimize', agentName, `--days=${OPTIMIZATION_DAYS}`, '--dry-run'], {
-      cwd,
-      encoding: 'utf8',
-      timeout: 300000, // 5 minutes timeout for optimization
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    
-    const duration = Date.now() - startTime;
-    
-    // Log the optimization attempt
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      agent: agentName,
-      durationMs: duration,
-      success: result.status === 0,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.status,
-      signal: result.signal
-    };
-    
-    writeFileSync(logFile, JSON.stringify(logEntry, null, 2) + '\n');
-    
-    if (result.status === 0) {
-      console.log(`✅ Optimization for ${agentName} completed in ${duration}ms`);
-      
-      // Record observation about the optimization
-      recordOptimizationObservation(agentName, true, duration);
-    } else {
-      console.log(`❌ Optimization for ${agentName} failed with code ${result.status}`);
-      console.log(`Stderr: ${result.stderr.slice(0, 500)}...`);
-      
-      // Record observation about the failure
-      recordOptimizationObservation(agentName, false, duration, result.stderr);
-    }
-    
-    return result.status === 0;
-  } catch (error) {
-    console.error(`❌ Optimization for ${agentName} threw error: ${error.message}`);
-    
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      agent: agentName,
-      durationMs: Date.now() - startTime,
-      success: false,
-      error: error.message,
-      stack: error.stack
-    };
-    
-    writeFileSync(logFile, JSON.stringify(logEntry, null, 2) + '\n');
-    return false;
-  }
-}
-
-// Record optimization observation for learning
-function recordOptimizationObservation(agentName, success, durationMs, error = null) {
-  const observation = {
-    role: 'construct',
-    category: success ? 'pattern' : 'anti-pattern',
-    summary: success 
-      ? `Auto-optimized ${agentName} in ${durationMs}ms`
-      : `Auto-optimization failed for ${agentName}: ${error?.slice(0, 200) || 'unknown error'}`,
-    content: success
-      ? `Automatic optimization triggered for ${agentName} after performance review showed avgScore < ${OPTIMIZATION_THRESHOLD}. Optimization completed successfully in ${durationMs}ms.`
-      : `Automatic optimization failed for ${agentName}. Error: ${error || 'Unknown'}. System should notify maintainer.`,
-    tags: ['auto-optimization', 'performance-review', agentName],
-    confidence: 0.9
-  };
-  
-  try {
-    // Use existing observation recording if available
-    const observationFile = join(homedir(), '.cx', 'observations', `${Date.now()}-${agentName}-optimization.json`);
-    mkdirSync(dirname(observationFile), { recursive: true });
-    writeFileSync(observationFile, JSON.stringify(observation, null, 2) + '\n');
-  } catch (error) {
-    // Non-critical - observation recording failed
-    console.error(`Failed to record optimization observation: ${error.message}`);
-  }
+function scheduleAgentOptimization(agentName) {
+  const logFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-${agentName}-scheduled.json`);
+  const scheduled = spawnDetached([
+    CONSTRUCT_BIN,
+    'optimize',
+    agentName,
+    `--days=${OPTIMIZATION_DAYS}`,
+    '--dry-run',
+  ]);
+  writeFileSync(logFile, `${JSON.stringify({
+    timestamp: new Date().toISOString(),
+    agent: agentName,
+    scheduled,
+    mode: 'detached-dry-run',
+  })}\n`);
+  return scheduled;
 }
 
-// Main optimization logic
 function main() {
-  // If the most recent review is missing or stale (>6h), kick off a refresh
-  // detached so the Stop hook returns promptly. The refresh runs on the next
-  // session's Stop if it's still in flight; nothing here blocks user work.
   maybeRefreshReviews();
 
   const review = getLatestPerformanceReview();
@@ -226,92 +142,53 @@ function main() {
     console.log('📊 No performance review data found. Run `construct review` first.');
     process.exit(0);
   }
-  
-  console.log(`📊 Checking ${review.agentStats.length} agents from performance review ${review.generated}`);
-  
+
   const agentsNeedingOptimization = review.agentStats.filter(needsOptimization);
-  
+
   if (agentsNeedingOptimization.length === 0) {
     console.log(`✅ All ${review.agentStats.length} agents have scores >= ${OPTIMIZATION_THRESHOLD} or insufficient data`);
     process.exit(0);
   }
-  
-  console.log(`🔧 Found ${agentsNeedingOptimization.length} agents needing optimization:`);
-  agentsNeedingOptimization.forEach(agent => {
-    console.log(`  • ${agent.name}: avgScore=${agent.avgScore}, invocations=${agent.invocations}`);
-  });
-  
-  // Sequential optimization keeps prompt-tuning deterministic and avoids
-  // colliding writes to per-agent prompt files.
-  let optimizedCount = 0;
-  let failedCount = 0;
-  
+
+  console.log(`🔧 Scheduling ${agentsNeedingOptimization.length} detached optimization preview(s):`);
+  let scheduledCount = 0;
   for (const agent of agentsNeedingOptimization) {
-    const success = optimizeAgent(agent.name);
-    if (success) {
-      optimizedCount++;
-    } else {
-      failedCount++;
-    }
-    
-    // Small delay between optimizations to avoid rate limits
-    if (agentsNeedingOptimization.length > 1) {
-      spawnSync('sleep', ['10'], { encoding: 'utf8' });
-    }
-  }
-  
-  // Summary
-  console.log(`\n📈 Optimization Summary:`);
-  console.log(`  • Agents checked: ${review.agentStats.length}`);
-  console.log(`  • Needing optimization: ${agentsNeedingOptimization.length}`);
-  console.log(`  • Successfully optimized: ${optimizedCount}`);
-  console.log(`  • Failed: ${failedCount}`);
-  
-  if (optimizedCount > 0) {
-    console.log(`\n💡 Optimized agents will be evaluated in the next performance review.`);
-    console.log(`   Run \`construct review\` after next session to see improvements.`);
+    console.log(`  • ${agent.name}: avgScore=${agent.avgScore}, invocations=${agent.invocations}`);
+    if (scheduleAgentOptimization(agent.name)) scheduledCount += 1;
   }
-  
-  // Log summary to file
-  const summary = {
+
+  const summaryFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-summary.json`);
+  writeFileSync(summaryFile, `${JSON.stringify({
     timestamp: new Date().toISOString(),
     project: projectName,
     reviewDate: review.generated,
     agentsChecked: review.agentStats.length,
     agentsNeedingOptimization: agentsNeedingOptimization.length,
-    optimizedCount,
-    failedCount,
-    agents: agentsNeedingOptimization.map(a => ({
+    scheduledCount,
+    agents: agentsNeedingOptimization.map((a) => ({
       name: a.name,
       avgScore: a.avgScore,
       invocations: a.invocations,
-      optimized: optimizeAgent.includes ? 'yes' : 'no'
-    }))
-  };
-  
-  const summaryFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-summary.json`);
-  writeFileSync(summaryFile, JSON.stringify(summary, null, 2) + '\n');
+    })),
+  }, null, 2)}\n`);
+
+  console.log(`\n📈 Optimization previews scheduled: ${scheduledCount}/${agentsNeedingOptimization.length}`);
 }
 
-// Run main logic
 try {
   main();
 } catch (error) {
   console.error(`❌ Session optimization hook crashed: ${error.message}`);
-  console.error(error.stack);
-  
-  // Log the crash
   const crashLog = join(OPTIMIZATION_LOG_DIR, 'crashes', `${Date.now()}-crash.json`);
   mkdirSync(dirname(crashLog), { recursive: true });
-  writeFileSync(crashLog, JSON.stringify({
+  writeFileSync(crashLog, `${JSON.stringify({
     timestamp: new Date().toISOString(),
     error: error.message,
     stack: error.stack,
     cwd,
-    projectName
-  }, null, 2) + '\n');
-  
+    projectName,
+  }, null, 2)}\n`);
   process.exit(1);
 }
 
-process.exit(0);
+process.exit(0);

package/lib/hooks/session-start.mjs

@@ -319,11 +319,10 @@ try {
 // plugin so both platforms surface the same prelude on session start.
 
 let intakeReviewNote = '';
-let brokerStatusNote = '';
 try {
-  const { buildIntakePrelude, buildBrokerStatusLine } = await import('../intake/session-prelude.mjs');
-  intakeReviewNote = buildIntakePrelude({ cwd, env: process.env });
-  brokerStatusNote = `\n${buildBrokerStatusLine({ env: process.env })}\n`;
+  const { buildSessionPrelude } = await import('../intake/session-prelude.mjs');
+  const prelude = buildSessionPrelude({ cwd, env: process.env });
+  intakeReviewNote = prelude ? `\n${prelude}\n` : '';
 } catch { /* best effort */ }
 
 // Missing-env-vars notice. Reads .env.example from the project root,
@@ -383,7 +382,7 @@ try {
 // that pollutes the caller's output contract, so the resolved output mode routes
 // the payload to stdout (interactive), stderr, or a debug log (silent).
 
-const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
+const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
 try {
   const { mode } = resolveHookOutputMode({ cwd, env: process.env });
   writeHookContext({ payload, mode });

package/lib/host-disposition.mjs

@@ -2,6 +2,13 @@
  * lib/host-disposition.mjs — single source of truth for the disposition of
  * every artifact Construct creates in a host project (ADR-0027 §1).
  *
+ * Scope model (see docs/concepts/project-scopes.md):
+ *   templates/, docs/  — package/repo durable sources (committed)
+ *   .construct/        — per-project launcher (ignored)
+ *   .cx/               — per-project runtime: intake, oracle, observations, demos (ignored)
+ *   ~/.construct/      — user credentials and doctor state
+ *   ~/.cx/             — user-scope telemetry fallback
+ *
  * `IGNORED_PATTERNS` enumerates machine-specific, sync-regenerated artifacts
  * that must never be committed; the init `.gitignore` writer and the
  * `gitignore-coverage` reconciliation both read from here, and uninstall /