@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/hooks/post-merge-tracking.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/post-merge-tracking.mjs — close beads referenced by a merged PR.
+ *
+ * Runs as a PostToolUse hook on Bash. Watches for `gh pr merge <N>` (or
+ * `gh pr merge --auto`) invocations that exited successfully; parses the
+ * PR body via `gh pr view <N> --json body`; extracts every `Refs:` /
+ * `Closes:` / `Fixes:` line that names a `construct-XXX` bead; closes each
+ * still-open bead with reason `Merged via PR #N (<sha>)`. Idempotent on
+ * beads already closed.
+ *
+ * The PR-body parse is the source of truth — not the merge commit subject
+ * — because the bundle PR pattern stores the bead refs in the body's
+ * "Beads issue" section and the squash-merge subject often drops them.
+ *
+ * Best-effort. Exits 0 on any parse or shell failure so the surrounding
+ * tool call is never affected. Stderr lines are advisory; the actual
+ * outcome is the `bd close` state, which is what the next Stop hook's
+ * tracking refresh will read.
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @p95ms 3000
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ * @exits 0 = pass
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readHookInput } from './_lib/input.mjs';
+import { logHookFailure } from './_lib/log.mjs';
+
+const input = readHookInput();
+const command = input?.tool_input?.command || input?.command || '';
+const exitCode = input?.tool_response?.exit_code ?? input?.tool_response?.exitCode;
+
+const ghPrMergeMatch = /\bgh\s+pr\s+merge\b(?:\s+(\d+))?/.exec(command);
+if (!ghPrMergeMatch) process.exit(0);
+if (exitCode !== undefined && exitCode !== 0) process.exit(0);
+
+const cwd = input?.cwd || process.cwd();
+const prNumber = await resolvePrNumber(ghPrMergeMatch[1], cwd);
+if (!prNumber) process.exit(0);
+
+try {
+  const { closeBeadsFromPrRefs } = await import('../tracking-surfaces.mjs');
+  const mergeCommitSha = readMergeCommitSha(cwd);
+  const result = await closeBeadsFromPrRefs({ prNumber, mergeCommitSha, cwd });
+  if (result?.closed?.length > 0) {
+    process.stderr.write(`[post-merge-tracking] closed beads: ${result.closed.join(', ')}\n`);
+  }
+  if (result?.errors?.length > 0) {
+    process.stderr.write(`[post-merge-tracking] failed to close: ${result.errors.map((e) => e.id).join(', ')}\n`);
+  }
+} catch (err) {
+  logHookFailure({ hook: 'post-merge-tracking', err, phase: 'close' });
+}
+
+process.exit(0);
+
+async function resolvePrNumber(captured, cwd) {
+  if (captured) return captured;
+  // Bare `gh pr merge --auto` / `gh pr merge -s` invocations omit the PR
+  // number. Resolve via the most recent merge commit subject, which `gh`
+  // standardly tails with `(#N)`.
+  try {
+    const lastLog = spawnSync('git', ['log', '-1', '--pretty=format:%s'], { cwd, encoding: 'utf8', timeout: 2000 });
+    if (lastLog.status !== 0) return null;
+    const m = /#(\d+)/.exec(lastLog.stdout);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function readMergeCommitSha(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', timeout: 2000 });
+    return result.status === 0 ? result.stdout.trim() : '';
+  } catch {
+    return '';
+  }
+}

package/lib/hooks/pre-compact.mjs

@@ -11,6 +11,10 @@
  *
  * @p95ms 100
  * @maxBlockingScope PreCompact
+ *
+ * @lifecycle PreCompact
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { homedir } from 'os';

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';