@geraldmaron/construct 1.0.12 → 1.0.14

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

@@ -1,32 +1,35 @@
 #!/usr/bin/env node
 /**
- * pre-push-gate.mjs — PreToolUse / Bash
+ * lib/hooks/pre-push-gate.mjs — PreToolUse / Bash
  *
+ * Local pre-push gate, shrunk to what only the developer's machine can know.
  * Intercepts three command shapes:
- *   git push                refuses claude/* branches, refuses on red remote CI,
- *                           runs project test/build/evals/docs in parallel
+ *   git push                refuses claude/* branches, blocks re-pushing the
+ *                           exact SHA CI just rejected. No test/build/lint —
+ *                           CI is the source of truth.
  *   gh pr create            lints the --body / --body-file against the PR
- *                           template policy before the PR is opened
- *   gh pr edit              same body lint when --body / --body-file is changed
+ *                           template policy before the PR is opened (CI can't
+ *                           — the body doesn't exist until the PR is created).
+ *   gh pr edit              same body lint when --body / --body-file is changed.
  *
- * Template-policy severity is conditional: a hard block (exit 2) when a
- * specialist sub-agent is active (CONSTRUCT_AGENT_ID set, or the cx-tracker
- * shows a fresh dispatch in the last 10 minutes); a warning otherwise so a
- * human driving the session can override editorial nits without ceremony.
- * CI still enforces the same rules on the resulting PR.
+ * Template-policy severity for PR body lint is conditional: a hard block
+ * (exit 2) when a specialist sub-agent is active; a warning otherwise so a
+ * human driving the session can override editorial nits. CI still enforces
+ * the same rules on the resulting PR.
  *
- * Silent and instant when there's nothing to run.
+ * Silent and instant when there's nothing to flag.
  *
- * Bypasses (env vars):
- *   CONSTRUCT_SKIP_PREPUSH=1        skip the entire push gate
- *   CONSTRUCT_ALLOW_CLAUDE_PUSH=1   allow pushing a claude/* branch
- *   CONSTRUCT_SKIP_PR_LINT=1        skip the gh pr body lint
+ * No bypass mechanism. If a check fires wrong, the check is wrong — repair
+ * the policy or the matcher; do not add a skip env var.
  *
- * @p95ms 30000
+ * @lifecycle PreToolUse
+ * @matcher  Bash
+ * @p95ms 5000
  * @maxBlockingScope PreToolUse
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
-import { execSync, spawn, spawnSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 import { dirname, join, resolve } from 'path';
 import { tmpdir } from 'os';
 import { logHookFailure } from './_lib/log.mjs';
@@ -48,7 +51,18 @@ if (!isGitPush && !isGhPrCreate && !isGhPrEdit) { echo(); }
 
 const cwd = input?.cwd || process.cwd();
 
-if ((isGhPrCreate || isGhPrEdit) && process.env.CONSTRUCT_SKIP_PR_LINT !== '1') {
+const PROTECTED_BRANCHES = new Set(['main', 'staging', 'master']);
+
+function currentBranch() {
+  try {
+    return execSync('git branch --show-current', { cwd, timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString().trim();
+  } catch { return ''; }
+}
+
+// gh pr create / gh pr edit body lint
+
+if (isGhPrCreate || isGhPrEdit) {
   const { body, bodyFile } = extractGhPrBody(command);
   const hasArgs = body != null || bodyFile != null;
 
@@ -85,7 +99,6 @@ if ((isGhPrCreate || isGhPrEdit) && process.env.CONSTRUCT_SKIP_PR_LINT !== '1')
             ? '[pre-push-gate] PR body fails template policy (specialist agent active — blocking):'
             : '[pre-push-gate] PR body fails template policy (no specialist agent active — warning only):';
           process.stderr.write(`${banner}\n${out}\n`);
-          process.stderr.write(`Override: CONSTRUCT_SKIP_PR_LINT=1 <command>\n`);
           emitRoleEvent({
             type: agentActive ? 'push_gate.fail' : 'push_gate.warn',
             summary: `PR body fails template policy (${severity})`,
@@ -103,36 +116,12 @@ if ((isGhPrCreate || isGhPrEdit) && process.env.CONSTRUCT_SKIP_PR_LINT !== '1')
   echo();
 }
 
-if (process.env.CONSTRUCT_SKIP_PREPUSH === '1') { echo(); }
-
-function extractGhPrBody(cmd) {
-  let m = cmd.match(/--body-file[\s=]+(["']?)(\S+?)\1(?=\s|$)/);
-  if (m) return { bodyFile: m[2] };
-  m = cmd.match(/(?:^|\s)-F[\s=]+(["']?)(\S+?)\1(?=\s|$)/);
-  if (m) return { bodyFile: m[2] };
-  m = cmd.match(/--body[\s=]+"((?:\\.|[^"\\])*)"/s);
-  if (m) return { body: m[1].replace(/\\(["\\])/g, '$1') };
-  m = cmd.match(/--body[\s=]+'([^']*)'/s);
-  if (m) return { body: m[1] };
-  return {};
-}
-
-function findRepoFile(startDir, relPath) {
-  let dir = startDir;
-  for (let i = 0; i < 10; i++) {
-    const candidate = join(dir, relPath);
-    if (existsSync(candidate)) return candidate;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
+// git push: refuse claude/* unconditionally.
 
-if (/\bclaude\//.test(command) && process.env.CONSTRUCT_ALLOW_CLAUDE_PUSH !== '1') {
+if (/\bclaude\//.test(command)) {
   process.stderr.write(
     `[pre-push-gate] Refusing to push a claude/* branch to remote (user policy).\n` +
-    `  Use a non-agent branch name, or override with CONSTRUCT_ALLOW_CLAUDE_PUSH=1 git push ...\n`,
+    `  Use a non-agent branch name.\n`,
   );
   emitRoleEvent({
     type: 'push_gate.fail',
@@ -143,208 +132,72 @@ if (/\bclaude\//.test(command) && process.env.CONSTRUCT_ALLOW_CLAUDE_PUSH !== '1
   process.exit(2);
 }
 
+// Prior remote CI red-check: block only when HEAD == the SHA that failed
+// (the developer is about to re-push the exact broken commit). If HEAD has
+// moved past the failed SHA, those new commits may well BE the fix; let
+// them push so CI can re-evaluate.
+
 try {
-  const branch = execSync('git branch --show-current', { cwd, timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] })
-    .toString().trim();
-  if (branch && branch !== 'main' && branch !== 'dev' && branch !== 'master') {
+  const branch = currentBranch();
+  if (branch && !PROTECTED_BRANCHES.has(branch) && branch !== 'dev') {
     const json = execSync(
-      `gh run list --branch=${JSON.stringify(branch)} --limit=1 --json conclusion,databaseId,url`,
+      `gh run list --branch=${JSON.stringify(branch)} --limit=1 --json conclusion,databaseId,url,headSha`,
       { cwd, timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] },
     ).toString().trim();
     if (json) {
       const [run] = JSON.parse(json);
       if (run?.conclusion === 'failure') {
+        const headSha = execSync('git rev-parse HEAD', { cwd, timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] })
+          .toString().trim();
+        const runSha = run.headSha || '';
+        const runUrl = run.url || `gh run view ${run.databaseId}`;
+        if (runSha && headSha === runSha) {
+          process.stderr.write(
+            `[pre-push-gate] HEAD (${headSha.slice(0, 7)}) is the commit that failed CI on '${branch}'.\n` +
+            `  Re-pushing the same SHA will fail again. Add a fix commit before pushing.\n` +
+            `  Failed run: ${runUrl}\n`,
+          );
+          emitRoleEvent({
+            type: 'push_gate.fail',
+            summary: 'remote CI red on current HEAD — push blocked',
+            hookInput: input,
+            context: { branch, runId: run.databaseId, runUrl: run.url, headSha, runSha },
+          });
+          process.exit(2);
+        }
         process.stderr.write(
-          `[pre-push-gate] Last CI run on '${branch}' FAILED — fix it before pushing more.\n` +
-          `  Run: ${run.url || `gh run view ${run.databaseId}`}\n` +
-          `  Override: CONSTRUCT_SKIP_PREPUSH=1 git push ...\n`,
+          `[pre-push-gate] Note: last CI run on '${branch}' (${runSha.slice(0, 7) || 'unknown SHA'}) failed; HEAD (${headSha.slice(0, 7)}) is past it. Allowing push — CI will re-evaluate.\n` +
+          `  Prior failure: ${runUrl}\n`,
         );
-        emitRoleEvent({
-          type: 'push_gate.fail',
-          summary: 'remote CI red — push blocked',
-          hookInput: input,
-          context: { branch, runId: run.databaseId, runUrl: run.url },
-        });
-        process.exit(2);
       }
     }
   }
 } catch {}
 
-function findUp(filename, from) {
-  let dir = from;
-  for (let i = 0; i < 8; i++) {
-    const candidate = join(dir, filename);
-    if (existsSync(candidate)) return { path: candidate, dir };
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
-// ── Node/npm project ──────────────────────────────────────────────────────────
-function runNpmGate(projectDir) {
-  let pkg;
-  try { pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8')); } catch { return null; }
-
-  const scripts = pkg.scripts || {};
-  const hasTest  = !!(scripts.test  && !scripts.test.includes('no test specified'));
-  const hasBuild = !!(scripts.build);
-  const hasCi    = !!(scripts['test:ci'] || scripts['test:run']);
-
-  const testScript  = scripts['test:ci'] ? 'test:ci' : scripts['test:run'] ? 'test:run' : 'test';
-  const runner = existsSync(join(projectDir, 'pnpm-lock.yaml')) ? 'pnpm'
-               : existsSync(join(projectDir, 'yarn.lock'))      ? 'yarn'
-               : 'npm';
-
-  const jobs = [];
-  if (hasTest || hasCi) jobs.push({ label: 'tests', cmd: runner, args: ['run', testScript],                  timeout: 90_000 });
-  if (hasBuild)         jobs.push({ label: 'build', cmd: runner, args: ['run', 'build'],                     timeout: 120_000 });
-  // Use the project's package manager for audit so the lockfile format matches.
-  const auditArgs = runner === 'pnpm'
-    ? ['audit', '--prod', '--audit-level=high']
-    : runner === 'yarn'
-      ? ['npm-audit', '--groups', 'dependencies', '--level', 'high']
-      : ['audit', '--omit=dev', '--audit-level=high'];
-  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: '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'))) {
-    jobs.push({ label: 'prose',    cmd: 'node', args: ['scripts/lint-prose.mjs'],         timeout: 15_000 });
-  }
-  if (existsSync(join(projectDir, 'scripts/lint-profiles.mjs'))) {
-    jobs.push({ label: 'profiles', cmd: 'node', args: ['scripts/lint-profiles.mjs', '--quiet'], timeout: 15_000 });
-  }
-
-  return { projectDir, jobs };
-}
-
-// ── Rust/Cargo project ────────────────────────────────────────────────────────
-function runCargoGate(projectDir) {
-  const jobs = [
-    { label: 'tests', cmd: 'cargo', args: ['test', '--quiet'], timeout: 120_000 },
-    { label: 'build', cmd: 'cargo', args: ['build', '--quiet'], timeout: 120_000 },
-  ];
-  return { projectDir, jobs };
-}
-
-// ── Python project ────────────────────────────────────────────────────────────
-function runPythonGate(projectDir) {
-  const hasPytest = (() => { try { execSync('pytest --version', { stdio: 'pipe', timeout: 3000 }); return true; } catch { return false; } })();
-  if (!hasPytest) return null;
-  const jobs = [{ label: 'tests', cmd: 'pytest', args: ['--tb=short', '-q'], timeout: 90_000 }];
-  return { projectDir, jobs };
-}
-
-// Detect project type
-let gate = null;
-const npm     = findUp('package.json', cwd);
-const cargo   = findUp('Cargo.toml', cwd);
-const pyproj  = findUp('pyproject.toml', cwd) || findUp('setup.py', cwd);
-
-if (npm)    gate = runNpmGate(npm.dir);
-else if (cargo)  gate = runCargoGate(cargo.dir);
-else if (pyproj) gate = runPythonGate(pyproj.dir);
+echo();
 
-// Nothing to check
-if (!gate || gate.jobs.length === 0) { echo(); }
+// helpers
 
-// Jobs run concurrently. Wall-clock = max(test, build) instead of sum, so the
-// gate fits inside the harness's 180s timeout even when both jobs near their
-// individual limits.
-function runJob(job) {
-  return new Promise((resolve) => {
-    let stdoutBuf = '';
-    let stderrBuf = '';
-    const child = spawn(job.cmd, job.args, {
-      cwd: gate.projectDir,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, CI: '1', FORCE_COLOR: '0' },
-    });
-
-    const timer = setTimeout(() => {
-      try { child.kill('SIGKILL'); } catch { /* already gone */ }
-    }, job.timeout);
-
-    child.stdout?.on('data', (chunk) => { stdoutBuf += chunk.toString(); });
-    child.stderr?.on('data', (chunk) => { stderrBuf += chunk.toString(); });
-    child.on('error', (err) => {
-      clearTimeout(timer);
-      resolve({ label: job.label, status: -1, stdout: stdoutBuf, stderr: stderrBuf || err.message, error: err });
-    });
-    child.on('close', (code) => {
-      clearTimeout(timer);
-      resolve({ label: job.label, status: code ?? -1, stdout: stdoutBuf, stderr: stderrBuf });
-    });
-  });
+function extractGhPrBody(cmd) {
+  let m = cmd.match(/--body-file[\s=]+(["']?)(\S+?)\1(?=\s|$)/);
+  if (m) return { bodyFile: m[2] };
+  m = cmd.match(/(?:^|\s)-F[\s=]+(["']?)(\S+?)\1(?=\s|$)/);
+  if (m) return { bodyFile: m[2] };
+  m = cmd.match(/--body[\s=]+"((?:\\.|[^"\\])*)"/s);
+  if (m) return { body: m[1].replace(/\\(["\\])/g, '$1') };
+  m = cmd.match(/--body[\s=]+'([^']*)'/s);
+  if (m) return { body: m[1] };
+  return {};
 }
 
-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`);
+function findRepoFile(startDir, relPath) {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, relPath);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
+  return null;
 }
-
-for (const result of results) {
-  if (result.status === 0) continue;
-  const detail = (result.stderr || result.stdout || '').trim();
-  failures.push({ label: result.label, detail: detail || `exited ${result.status}` });
-}
-
-if (failures.length === 0) { echo(); }
-
-const summary = failures
-  .map((f) => `${f.label} failed — ${f.detail}`)
-  .join('\n');
-
-process.stderr.write(
-  `[pre-push-gate] Push blocked — fix these before pushing:\n${summary}\n\nRun the failing checks locally, then push again.\n`
-);
-
-emitRoleEvent({
-  type: 'push_gate.fail',
-  summary,
-  hookInput: input,
-  context: { failures },
-});
-
-process.exit(2);

package/lib/hooks/proactive-activation.mjs

@@ -20,9 +20,12 @@
  *
  * @p95ms 5
  * @maxBlockingScope none
+ *
+ * @unwired (not referenced from platforms/claude/settings.template.json)
+ * @exits 0 = pass
  */
 
-import { EVENT_OWNERSHIP } from '../orchestration-policy.mjs';
+import { ownerForEvent } from '../orchestration/routing-tables.mjs';
 import { loadProjectConfig } from '../config/project-config.mjs';
 
 // Rate limiting: max activations per specialist per hour
@@ -116,7 +119,7 @@ export function getActivationStats(specialist) {
  * Route an event to the owning specialist.
  */
 export function routeEvent(eventType, eventData = {}) {
-  const owner = EVENT_OWNERSHIP[eventType];
+  const owner = ownerForEvent(eventType);
   
   if (!owner) {
     return {

package/lib/hooks/readme-age-check.mjs

@@ -9,6 +9,10 @@
  *
  * @p95ms 1500
  * @maxBlockingScope none (async, non-blocking)
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @exits 0 = pass
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';

package/lib/hooks/registry-sync.mjs

@@ -1,30 +1,45 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/registry-sync.mjs — Registry sync hook — reminds to run construct sync after registry changes.
+ * lib/hooks/registry-sync.mjs — Registry-change reminder hook.
  *
- * Runs as PostToolUse after edits to specialists/registry.json. Checks if the file was modified and emits a reminder to run construct sync to regenerate platform adapters.
+ * PostToolUse on Write|Edit. Fires only when the edited file is
+ * specialists/registry.json (the construct repo) or an installed
+ * agents/registry.json mirror. Emits a one-line reminder on stderr telling
+ * the developer to run `construct sync` when they're ready. Does NOT
+ * auto-execute sync — auto-execution during tests (which legitimately
+ * mutate registry.json) races test cleanup and regenerates platform state
+ * mid-suite. The dev decides when to sync, the same way ordinary code
+ * changes don't auto-build.
  *
- * @p95ms 12000
- * @maxBlockingScope none (PostToolUse, non-blocking)
+ * The reminder is suppressed automatically when CI=true or NODE_ENV=test.
+ * Stderr is not used as an interactivity signal: Claude Code captures hook
+ * stderr rather than passing it through to a TTY, so a TTY check would
+ * silently suppress the reminder in real usage. No skip env var — broaden
+ * the detection here if the reminder fires in a context where it shouldn't.
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit
+ * @p95ms 50
+ * @maxBlockingScope none
+ * @exits 0 = pass
  */
-import { execSync } from 'child_process';
 import path from 'node:path';
-import { logHookFailure } from './_lib/log.mjs';
-import { constructDir } from '../paths.mjs';
+import { readHookInput } from './_lib/input.mjs';
+
+const input = readHookInput();
+const filePath = input?.tool_input?.file_path || process.env.TOOL_INPUT_FILE_PATH || '';
+const matchesRegistry =
+  filePath.endsWith(path.join('agents', 'registry.json')) ||
+  filePath.endsWith('/specialists/registry.json');
+if (!matchesRegistry) process.exit(0);
 
-const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
-if (!filePath.endsWith(path.join('agents', 'registry.json')) && !filePath.endsWith('/specialists/registry.json')) process.exit(0);
+const isNonInteractive =
+  process.env.CI === 'true' ||
+  process.env.NODE_ENV === 'test';
 
-const toolkitDir = constructDir();
-try {
-  execSync('node scripts/sync-specialists.mjs', {
-    cwd: toolkitDir,
-    stdio: 'pipe',
-    env: { ...process.env, CX_TOOLKIT_DIR: toolkitDir },
-    timeout: 12_000,
-  });
-} catch (err) {
-  logHookFailure({ hook: 'registry-sync', err, phase: 'execute', input: { toolkitDir } });
-  process.stderr.write(`[registry-sync] Sync failed: ${err.message}\n`);
+if (!isNonInteractive) {
+  process.stderr.write(
+    `[registry-sync] registry.json changed — run \`construct sync\` to regenerate platform adapters when ready.\n`,
+  );
 }
 process.exit(0);

package/lib/hooks/rule-verifier.mjs

@@ -21,6 +21,9 @@
  *
  * @p95ms 200
  * @maxBlockingScope Stop
+ *
+ * @unwired (not referenced from platforms/claude/settings.template.json)
+ * @exits 0 = pass | 2 = block tool call
  */
 
 import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';

package/lib/hooks/scan-secrets.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 30
  * @maxBlockingScope PostToolUse
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync } from 'fs';
 import { extname } from 'path';

package/lib/hooks/session-optimize.mjs

@@ -7,6 +7,10 @@
  *
  * @p95ms 300
  * @maxBlockingScope Stop (non-blocking, async)
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';

package/lib/hooks/session-reflect.mjs

@@ -14,6 +14,10 @@
  *
  * @p95ms 300
  * @maxBlockingScope Stop
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';

package/lib/hooks/session-start.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 300
  * @maxBlockingScope SessionStart
+ *
+ * @lifecycle SessionStart
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, existsSync, statSync, writeFileSync } from 'fs';
 import { execSync } from 'child_process';
@@ -321,6 +325,49 @@ try {
   brokerStatusNote = `\n${buildBrokerStatusLine({ env: process.env })}\n`;
 } catch { /* best effort */ }
 
+// Missing-env-vars notice. Reads .env.example from the project root,
+// compares against .env and process.env, lists keys whose example value
+// is a placeholder and whose live value is unset. Empty string when the
+// project has no .env.example or all required keys are populated.
+
+const envCheckNote = buildEnvCheckNote(cwd);
+
+function buildEnvCheckNote(rootDir) {
+  const examplePath = join(rootDir, '.env.example');
+  if (!existsSync(examplePath)) return '';
+  const example = parseEnvFile(examplePath);
+  if (example.size === 0) return '';
+  const envFile = parseEnvFile(join(rootDir, '.env'));
+  const PLACEHOLDER = /^(YOUR_|<|__|\$\{|REPLACE|ADD_|INSERT_|xxx|TODO)/i;
+  const missing = [];
+  for (const [key, exampleVal] of example) {
+    const required = !exampleVal || PLACEHOLDER.test(exampleVal);
+    if (!required) continue;
+    const liveFromEnvFile = envFile.has(key) && envFile.get(key) !== '' && !PLACEHOLDER.test(envFile.get(key));
+    const liveFromProcessEnv = process.env[key] && !PLACEHOLDER.test(process.env[key]);
+    if (!liveFromEnvFile && !liveFromProcessEnv) missing.push(key);
+  }
+  if (missing.length === 0) return '';
+  const noun = missing.length === 1 ? 'variable' : 'variables';
+  const list = missing.map((k) => `  - ${k}`).join('\n');
+  return `\n## Environment check — ${missing.length} required ${noun} not set\n${list}\nAdd these to .env before running the app.\n`;
+}
+
+function parseEnvFile(p) {
+  const map = new Map();
+  if (!existsSync(p)) return map;
+  for (const line of readFileSync(p, 'utf8').split('\n')) {
+    const stripped = line.trim();
+    if (!stripped || stripped.startsWith('#')) continue;
+    const eq = stripped.indexOf('=');
+    if (eq === -1) continue;
+    const key = stripped.slice(0, eq).trim();
+    const val = stripped.slice(eq + 1).trim();
+    if (key) map.set(key, val);
+  }
+  return map;
+}
+
 // Permission posture: surface gaps in ~/.claude/settings.json permissions.allow
 // so the agent can ask the user to close them instead of stumbling into the
 // classifier mid-task. Empty string when no gaps — keeps the banner small.
@@ -331,7 +378,7 @@ try {
   permissionPostureNote = buildPermissionPostureLine({ cwd });
 } catch { /* best effort */ }
 
-process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}\n${footer}${pendingNote}\n`);
+process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`);
 // Auto-bootstrap the policy-engine gate. session-start has just emitted
 // branch + recent commits + prior observations + context-state — that is
 // already grounding; mark the session bootstrapped so the PreToolUse rule