@skillcap/gdh 0.26.7 → 0.26.9

package/node_modules/@gdh/adapters/dist/templates/authoring-hook.js.tpl

@@ -15,20 +15,13 @@ const STATE_RELATIVE_PATH_FROM_HOOK = {{stateRelativePathFromHookJson}};
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { pathToFileURL } = require('url');
+const { fileURLToPath, pathToFileURL } = require('url');
 const { spawnSync } = require('child_process');
+const os = require('os');
 
-const AUTHORING_EXTENSIONS = new Set(['.gd', '.tscn', '.tres']);
-const CHECK_TIMEOUT_MS = readBoundedPositiveIntEnv('GDH_AUTHORING_HOOK_CHECK_TIMEOUT_MS', 2500, 10000);
+const AUTHORING_EXTENSIONS = new Set(['.gd']);
 const FOREGROUND_REFRESH_TIMEOUT_MS = readBoundedPositiveIntEnv('GDH_AUTHORING_HOOK_REFRESH_TIMEOUT_MS', 8000, 30000);
-// Phase 82 / LSP-03: session-end ("Stop") freshness barrier. Default 60 s gives
-// real Godot LSP startup + final-mode authoring check headroom; hard cap 300 s
-// keeps the env var from becoming a denial-of-service surface.
-const STOP_TIMEOUT_MS = readBoundedPositiveIntEnv('GDH_AUTHORING_STOP_HOOK_TIMEOUT_MS', 60000, 300000);
 const MAX_BLOCK_OUTPUT_CHARS = 4000;
-// Phase 82 / Pitfall 6: bound Stop additionalContext to 8000 chars (2000-char
-// headroom under Claude's 10000 cap so the hook payload always lands).
-const MAX_STOP_CONTEXT_CHARS = 8000;
 let CURRENT_EVENT = '';
 
 main();
@@ -51,13 +44,13 @@ function main() {
 
 function handlePostEdit(input, targetRoot) {
   const changed = collectChangedFiles(input, targetRoot);
-  const authoring = changed.filter(isAuthoringValidationPath);
+  const authoring = changed.filter(file => isExistingAuthoringValidationPath(targetRoot, file));
   if (authoring.length === 0) return allow();
   let output;
   try {
     output = runPostEditDiagnostics(targetRoot, authoring);
   } catch (_err) {
-    return context(`GDH post-edit hook embedded read threw; continuing without blocking. Run \`${gdhCommandPrefix()} authoring check --mode final --target ${JSON.stringify(targetRoot)}\` before claiming code-validity.`);
+    return context("GDH post-edit hook embedded read threw; continuing without blocking. Do not treat this edit as validated; collect final validation evidence before claiming code-validity.");
   }
   // Phase 81 / LSP-06 / D-01: dispatch on bracketed-token vocabulary.
   // Pitfall 5: anchor regex to line-start with /m flag so per-diagnostic
@@ -67,16 +60,16 @@ function handlePostEdit(input, targetRoot) {
   // but the dispatch retains them as forward-compat branches in case a future
   // reader extension surfaces them.
   if (/^\[failed\]/m.test(output) || /^\[partial\]/m.test(output)) {
-    return block(formatBlockingReason(output));
+    return block(formatBlockingReason(output, targetRoot));
   }
   if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
   if (/^\[pending\]/m.test(output) || /^\[stale\]/m.test(output)) {
-    return context(`GDH post-edit authoring check could not prove this edit quickly; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
+    return context(`GDH post-edit authoring check could not prove this edit quickly; continuing without blocking. ${compactOneLine(output || 'Collect final validation evidence before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
   }
   if (/^\[timeout\]/m.test(output)) {
-    return context(`GDH post-edit authoring check returned a timeout status; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
+    return context(`GDH post-edit authoring check returned a timeout status; continuing without blocking. ${compactOneLine(output || 'Collect final validation evidence before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
   }
   return allow();
 }
@@ -116,14 +109,14 @@ function handlePostToolBatch(input, targetRoot) {
     for (const file of parsePatchFileNames(command)) addFile(files, file, targetRoot, baseCwd);
   }
   // Pitfall 4: order-stable dedup via unique() (Set + sort) — same dedup as handlePostEdit.
-  const authoring = unique(files).filter(isAuthoringValidationPath);
+  const authoring = unique(files).filter(file => isExistingAuthoringValidationPath(targetRoot, file));
   if (authoring.length === 0) return allow();  // Pitfall 2: no authoring files — no work
 
   let output;
   try {
     output = runPostEditDiagnostics(targetRoot, authoring);
   } catch (_err) {
-    return context(`GDH PostToolBatch hook embedded read threw; continuing without blocking. Run \`${gdhCommandPrefix()} authoring check --mode final --target ${JSON.stringify(targetRoot)}\` before claiming code-validity.`);
+    return context("GDH PostToolBatch hook embedded read threw; continuing without blocking. Do not treat this batch as validated; collect final validation evidence before claiming code-validity.");
   }
 
   // Bracketed-token dispatch — IDENTICAL to handlePostEdit. Pitfall 5 from Phase 81
@@ -131,16 +124,16 @@ function handlePostToolBatch(input, targetRoot) {
   // severity brackets do not match the line-leading status token. Forward-compat
   // [partial] / [timeout] branches retained per quick-task 260504-ix2 plan note.
   if (/^\[failed\]/m.test(output) || /^\[partial\]/m.test(output)) {
-    return block(formatBlockingReason(output));
+    return block(formatBlockingReason(output, targetRoot));
   }
   if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
   if (/^\[pending\]/m.test(output) || /^\[stale\]/m.test(output)) {
-    return context(`GDH PostToolBatch authoring check could not prove this batch quickly; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
+    return context(`GDH PostToolBatch authoring check could not prove this batch quickly; continuing without blocking. ${compactOneLine(output || 'Collect final validation evidence before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
   }
   if (/^\[timeout\]/m.test(output)) {
-    return context(`GDH PostToolBatch authoring check returned a timeout status; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
+    return context(`GDH PostToolBatch authoring check returned a timeout status; continuing without blocking. ${compactOneLine(output || 'Collect final validation evidence before claiming code-validity.')} ${reasonHint(output, targetRoot, authoring)}`);
   }
   return allow();
 }
@@ -174,60 +167,21 @@ function handlePostToolBatch(input, targetRoot) {
 //   4. If foreground refresh cannot prove within budget, spawn detached refresh
 //      as a fallback and emit non-blocking context.
 function runPostEditDiagnostics(targetRoot, authoringFiles) {
-  const groups = splitAuthoringFiles(authoringFiles);
-  let output = '';
-  let gdFresh = false;
-  let sceneFreshOutput = '';
-
-  if (groups.gd.length > 0) {
-    output = runEmbeddedDiagnosticsRead(targetRoot, groups.gd);
-    if (isBlockingDiagnosticsOutput(output)) return output;
-    if (isConclusiveDiagnosticsOutput(output) && groups.scene.length === 0 && groups.resource.length === 0 && groups.project.length === 0) {
-      return output;
-    }
-
-    const refreshed = runForegroundDiagnosticsRefresh(targetRoot, groups.gd);
-    if (refreshed) {
-      output = runEmbeddedDiagnosticsRead(targetRoot, groups.gd);
-      if (isBlockingDiagnosticsOutput(output)) return output;
-      if (isConclusiveDiagnosticsOutput(output) && groups.scene.length === 0 && groups.resource.length === 0 && groups.project.length === 0) {
-        return output;
-      }
-    }
-    gdFresh = /^\[fresh\]/m.test(output);
-  }
-
-  if (groups.scene.length > 0) {
-    const sceneOutput = runForegroundSceneAuthoringCheck(targetRoot, groups.scene);
-    if (sceneOutput && isBlockingDiagnosticsOutput(sceneOutput)) return sceneOutput;
-    if (!sceneOutput || !/^\[fresh\]/m.test(sceneOutput)) {
-      return sceneOutput || formatStatus('pending', ['scene_validation_not_confirmed']);
-    }
-    sceneFreshOutput = sceneOutput;
-  }
-
-  if (groups.project.length > 0) {
-    return formatStatus('pending', ['project_godot_requires_final_authoring_check']);
-  }
-
-  if (groups.resource.length > 0) {
-    return formatStatus('pending', ['tres_scoped_validation_ignored']);
-  }
+  const gdFiles = unique(Array.isArray(authoringFiles) ? authoringFiles : [])
+    .filter(file => isExistingAuthoringValidationPath(targetRoot, file));
+  if (gdFiles.length === 0) return '[fresh] 0 errors, 0 warnings, 0 info. Completion allowed.';
 
-  if (groups.gd.length > 0 && !gdFresh) {
-    spawnDetachedRefresh(targetRoot, groups.gd);
-    return output || formatStatus('pending', ['broker_not_yet_primed']);
-  }
-
-  if (groups.scene.length > 0) {
-    return sceneFreshOutput;
-  }
+  let output = runEmbeddedDiagnosticsRead(targetRoot, gdFiles);
+  if (isBlockingDiagnosticsOutput(output) || isConclusiveDiagnosticsOutput(output)) return output;
 
-  if (groups.gd.length > 0) {
-    return output;
+  const refreshed = runForegroundDiagnosticsRefresh(targetRoot, gdFiles);
+  if (refreshed) {
+    output = runEmbeddedDiagnosticsRead(targetRoot, gdFiles);
+    if (isBlockingDiagnosticsOutput(output) || isConclusiveDiagnosticsOutput(output)) return output;
   }
 
-  return formatStatus('pending', ['no_authoring_files_to_check']);
+  spawnDetachedRefresh(targetRoot, gdFiles);
+  return output || formatStatus('pending', ['broker_not_yet_primed']);
 }
 
 function isConclusiveDiagnosticsOutput(output) {
@@ -238,23 +192,14 @@ function isBlockingDiagnosticsOutput(output) {
   return /^\[failed\]/m.test(output) || /^\[partial\]/m.test(output);
 }
 
-function splitAuthoringFiles(files) {
-  const inputFiles = Array.isArray(files) ? unique(files) : [];
-  return {
-    gd: inputFiles.filter(f => path.extname(f).toLowerCase() === '.gd'),
-    scene: inputFiles.filter(f => path.extname(f).toLowerCase() === '.tscn'),
-    resource: inputFiles.filter(f => path.extname(f).toLowerCase() === '.tres'),
-    project: inputFiles.filter(f => path.basename(f) === 'project.godot'),
-  };
-}
-
 function runForegroundDiagnosticsRefresh(targetRoot, files) {
   const gdFiles = Array.isArray(files) ? unique(files).filter(f => path.extname(f).toLowerCase() === '.gd') : [];
   if (gdFiles.length === 0) return false;
   try {
-    const args = ['-y', `@skillcap/gdh@${PINNED_VERSION}`, 'authoring', 'diagnostics', 'refresh', '--target', targetRoot];
+    const invocation = resolveGdhInvocation(targetRoot);
+    const args = [...invocation.args, 'authoring', 'diagnostics', 'refresh', '--target', targetRoot];
     for (const f of gdFiles) args.push('--changed', f);
-    const result = spawnSync('npx', args, {
+    const result = spawnSync(invocation.command, args, {
       cwd: targetRoot,
       encoding: 'utf8',
       timeout: FOREGROUND_REFRESH_TIMEOUT_MS,
@@ -266,27 +211,6 @@ function runForegroundDiagnosticsRefresh(targetRoot, files) {
   }
 }
 
-function runForegroundSceneAuthoringCheck(targetRoot, files) {
-  const sceneFiles = Array.isArray(files) ? unique(files).filter(f => path.extname(f).toLowerCase() === '.tscn') : [];
-  if (sceneFiles.length === 0) return '';
-  try {
-    const args = ['-y', `@skillcap/gdh@${PINNED_VERSION}`, 'authoring', 'check', '--mode', 'post-edit', '--format', 'compact', '--target', targetRoot];
-    for (const f of sceneFiles) args.push('--changed', f);
-    const result = spawnSync('npx', args, {
-      cwd: targetRoot,
-      encoding: 'utf8',
-      timeout: FOREGROUND_REFRESH_TIMEOUT_MS,
-      windowsHide: true,
-    });
-    if (!result || result.error || result.signal || result.status !== 0) {
-      return formatStatus('pending', ['scene_validation_not_confirmed']);
-    }
-    return String(result.stdout || '').trim();
-  } catch (_error) {
-    return formatStatus('pending', ['scene_validation_not_confirmed']);
-  }
-}
-
 // Quick task 260504-o6w. Fire-and-forget scoped diagnostics refresh from the
 // post-edit hook. The CLI verb calls `refreshAuthoringDiagnostics` which boots
 // Godot LSP if needed, opens scoped files via LSP, drains diagnostics, and
@@ -304,14 +228,15 @@ function runForegroundSceneAuthoringCheck(targetRoot, files) {
 function spawnDetachedRefresh(targetRoot, files) {
   if (Array.isArray(files) && files.length === 0) return;
   try {
-    const args = ['-y', `@skillcap/gdh@${PINNED_VERSION}`, 'authoring', 'diagnostics', 'refresh', '--target', targetRoot];
+    const invocation = resolveGdhInvocation(targetRoot);
+    const args = [...invocation.args, 'authoring', 'diagnostics', 'refresh', '--target', targetRoot];
     if (Array.isArray(files)) {
       for (const f of files) {
         args.push('--changed', f);
       }
     }
     const child = require('child_process').spawn(
-      'npx',
+      invocation.command,
       args,
       {
         cwd: targetRoot,
@@ -326,39 +251,99 @@ function spawnDetachedRefresh(targetRoot, files) {
   }
 }
 
-// Phase 82 / LSP-03 + Quick task 260504-ix2 — Stop-hook contract relaxation.
-//
-// Original Phase 82 contract: Stop synchronously invoked
-// `gdh authoring check --mode final`, which calls
-// `getManagedLspStatus(launch_if_needed)` and could spawn Godot LSP from the
-// Stop event. Real-world dogfooding (2026-05-04 session) showed this path
-// always timed out due to per-invocation `npx -y @skillcap/gdh@PINNED` cost
-// (~9.3 s on the operator's measured machine). The hook ate the full
-// `STOP_TIMEOUT_MS` budget on the npx bootstrap path before producing any
-// output.
-//
-// Updated contract (RFC 0009 addendum): Stop reads the existing broker
-// snapshot via the embedded dependency-free reader; it does NOT synchronously
-// launch LSP. Cold/missing-broker case returns `additionalContext`
-// recommending the user run `gdh authoring check --mode final` manually AND
-// spawns detached warmup so the next session's PostToolUse events have a
-// primed broker. This trades the rare "fresh session, no warm broker" case
-// (where Stop would have produced final diagnostics synchronously) for the
-// common case of sub-100ms hook return on every Stop.
-//
-// Hard invariants preserved:
-//   - GF3 (260504): zero authoring-files-in-target → noop (git gate, runs first)
-//   - Pitfall 3: NEVER returns decision: block (Stop hook must not block session end)
-//   - Pitfall 5: Claude additionalContext lives in hookSpecificOutput
-//   - Pitfall 6: additionalContext bounded to MAX_STOP_CONTEXT_CHARS = 8000
+function resolveGdhInvocation(targetRoot) {
+  const directBin = resolveGdhBin(targetRoot);
+  if (directBin) return { command: directBin, args: [] };
+  return { command: 'npx', args: ['-y', `@skillcap/gdh@${PINNED_VERSION}`] };
+}
+
+function resolveGdhBin(targetRoot) {
+  const envBin = process.env['GDH_AUTHORING_HOOK_GDH_BIN'];
+  if (isExecutableFile(envBin)) return envBin;
+
+  const roots = unique([
+    targetRoot,
+    process.cwd(),
+    __dirname,
+    ...parentDirs(targetRoot, 8),
+    ...parentDirs(__dirname, 8),
+  ]);
+  for (const root of roots) {
+    const packageBin = resolvePackageBin(path.join(root, 'node_modules', '@skillcap', 'gdh'));
+    if (packageBin) return packageBin;
+  }
+
+  const cacheRoots = unique([
+    process.env['npm_config_cache'],
+    process.env['NPM_CONFIG_CACHE'],
+    path.join(os.homedir(), '.npm'),
+  ]);
+  for (const cacheRoot of cacheRoots) {
+    const npxRoot = cacheRoot ? path.join(cacheRoot, '_npx') : null;
+    if (!npxRoot) continue;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(npxRoot, { withFileTypes: true });
+    } catch (_err) {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const packageBin = resolvePackageBin(path.join(npxRoot, entry.name, 'node_modules', '@skillcap', 'gdh'));
+      if (packageBin) return packageBin;
+    }
+  }
+
+  return null;
+}
+
+function resolvePackageBin(packageDir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
+    if (!pkg || pkg.version !== PINNED_VERSION) return null;
+    const binField = pkg.bin;
+    let relativeBin = null;
+    if (typeof binField === 'string') relativeBin = binField;
+    else if (binField && typeof binField.gdh === 'string') relativeBin = binField.gdh;
+    if (!relativeBin) return null;
+    const candidate = path.join(packageDir, relativeBin);
+    return isExecutableFile(candidate) ? candidate : null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+function isExecutableFile(value) {
+  if (typeof value !== 'string' || value.trim() === '') return false;
+  try {
+    return fs.statSync(value).isFile();
+  } catch (_err) {
+    return false;
+  }
+}
+
+function parentDirs(start, limit) {
+  const dirs = [];
+  let dir = path.resolve(start || '.');
+  for (let i = 0; i < limit; i += 1) {
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dirs.push(parent);
+    dir = parent;
+  }
+  return dirs;
+}
+
+// Stop is deliberately silent. It never blocks, never emits additionalContext,
+// and never substitutes for final validation evidence. It may opportunistically
+// prime `.gd` diagnostics for the next session.
 function handleStop(input, targetRoot) {
   if (!hasAuthoringWorkInTarget(targetRoot)) return allow();
 
   // Discover the authoring file set from the working tree under targetRoot.
   // We feed this into the embedded reader so it can resolve broker entries
-  // by file:// URI. If the discovery fails (git unavailable, etc.) we fall
-  // through with an empty list, which routes to a `[pending]` status with
-  // reason `file_not_in_snapshot` — same effect as no broker primed.
+  // by file:// URI. If discovery fails (git unavailable, etc.) Stop remains
+  // silent.
   const authoringFiles = listAuthoringFilesInTarget(targetRoot);
 
   let output;
@@ -368,59 +353,28 @@ function handleStop(input, targetRoot) {
     output = '[pending]\nReasons: embedded_read_threw';
   }
 
-  const truncatedSuffix = ' Run `gdh authoring check --mode final` for full output.';
-  function stopContext(message) {
-    const text = String(message || '').trim();
-    const ceiling = MAX_STOP_CONTEXT_CHARS;
-    if (text.length <= ceiling) return context(text);
-    const headroom = ceiling - truncatedSuffix.length;
-    return context(text.slice(0, headroom).trimEnd() + truncatedSuffix);
-  }
-
-  // Bracketed-token dispatch — same vocabulary as PostToolUse but EVERY branch
-  // routes to context() or allow(); decision: block is forbidden on Stop.
-  // Forward-compat [partial] / [timeout] / [failed] branches retained for
-  // potential future reader extensions; the embedded reader currently emits
-  // only [fresh] / [stale] / [pending].
   if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
   if (/^\[failed\]/m.test(output) || /^\[partial\]/m.test(output) || /^\[stale\]/m.test(output)) {
-    return stopContext(`GDH session-end check found unresolved diagnostics: ${compactOneLine(output)} ${reasonHint(output, targetRoot, authoringFiles)}`);
+    return allow();
   }
   if (/^\[pending\]/m.test(output) || /^\[timeout\]/m.test(output)) {
-    // Cold/missing broker: spawn detached refresh so the NEXT session benefits.
-    // The current Stop returns additionalContext recommending manual
-    // `gdh authoring check --mode final` (the relaxed contract — see RFC 0009
-    // addendum 2026-05-04). spawnDetachedRefresh is fire-and-forget; it never
-    // blocks hook return.
-    spawnDetachedRefresh(targetRoot, splitAuthoringFiles(authoringFiles).gd);
-    return stopContext(
-      'GDH session-end check could not prove final code-validity from the cached broker snapshot; continuing without blocking. ' +
-      'Run `gdh authoring check --mode final` manually before claiming code-validity. ' +
-      compactOneLine(output) + ' ' + reasonHint(output, targetRoot, authoringFiles),
-    );
+    spawnDetachedRefresh(targetRoot, authoringFiles);
+    return allow();
   }
-  // Unknown status: degrade to additionalContext (NEVER block).
-  spawnDetachedRefresh(targetRoot, splitAuthoringFiles(authoringFiles).gd);
-  return stopContext(
-    'GDH session-end check could not produce a final result; continuing without blocking. ' +
-    'Run `gdh authoring check --mode final` manually before claiming code-validity. ' +
-    compactOneLine(output) + ' ' + reasonHint(output, targetRoot, authoringFiles),
-  );
+  spawnDetachedRefresh(targetRoot, authoringFiles);
+  return allow();
 }
 
 function runStopDiagnostics(targetRoot, authoringFiles) {
-  const groups = splitAuthoringFiles(authoringFiles);
-  if (groups.gd.length > 0) {
-    const gdOutput = runEmbeddedDiagnosticsRead(targetRoot, groups.gd);
+  const gdFiles = unique(Array.isArray(authoringFiles) ? authoringFiles : [])
+    .filter(file => isExistingAuthoringValidationPath(targetRoot, file));
+  if (gdFiles.length > 0) {
+    const gdOutput = runEmbeddedDiagnosticsRead(targetRoot, gdFiles);
     if (!/^\[fresh\]/m.test(gdOutput)) return gdOutput;
   }
-  if (groups.scene.length > 0) return formatStatus('pending', ['scene_validation_requires_final_authoring_check']);
-  if (groups.resource.length > 0) return formatStatus('pending', ['tres_scoped_validation_ignored']);
-  if (groups.project.length > 0) return formatStatus('pending', ['project_godot_requires_final_authoring_check']);
-  if (groups.gd.length > 0) return '[fresh] 0 errors, 0 warnings, 0 info. Completion allowed.';
-  return formatStatus('pending', ['no_authoring_files_to_check']);
+  return '[fresh] 0 errors, 0 warnings, 0 info. Completion allowed.';
 }
 
 // Quick task 260504-ix2: collect authoring-relevant files in the working tree
@@ -428,9 +382,7 @@ function runStopDiagnostics(targetRoot, authoringFiles) {
 // returns a boolean for the GF3 gate); this returns the list of files for the
 // embedded broker-snapshot reader to look up by file:// URI. Order-stable.
 //
-// Fail-open: returns [] on any git failure (the embedded reader will then emit
-// `[pending]` reasons, which Stop dispatches to additionalContext — never
-// block).
+// Fail-open: returns [] on any git failure. Stop remains silent.
 function listAuthoringFilesInTarget(targetRoot) {
   let result;
   try {
@@ -450,7 +402,7 @@ function listAuthoringFilesInTarget(targetRoot) {
     const arrow = rest.indexOf(' -> ');
     if (arrow !== -1) rest = rest.slice(arrow + 4);
     if (rest.startsWith('"') && rest.endsWith('"')) rest = rest.slice(1, -1);
-    if (isAuthoringValidationPath(rest)) files.push(rest);
+    if (isExistingAuthoringValidationPath(targetRoot, rest)) files.push(rest);
   }
   return unique(files);
 }
@@ -730,10 +682,18 @@ function isInside(root, candidate) { const rel = path.relative(root, path.resolv
 function canonicalPath(value) { try { return fs.realpathSync.native ? fs.realpathSync.native(value) : fs.realpathSync(value); } catch { return path.resolve(value); } }
 
 function isAuthoringValidationPath(file) {
-  if (file === 'project.godot' || file.endsWith('/project.godot')) return true;
   return AUTHORING_EXTENSIONS.has(path.extname(file).toLowerCase());
 }
 
+function isExistingAuthoringValidationPath(targetRoot, file) {
+  if (!isAuthoringValidationPath(file)) return false;
+  try {
+    return fs.statSync(path.resolve(targetRoot, file)).isFile();
+  } catch (_err) {
+    return false;
+  }
+}
+
 // GF3 (260504): session-end git-gate. Stop hook noops when zero authoring-file
 // changes exist in the working tree under targetRoot. Fails closed (returns
 // true) on any git failure so the freshness barrier never silently weakens.
@@ -766,7 +726,7 @@ function hasAuthoringWorkInTarget(targetRoot) {
     if (rest.startsWith('"') && rest.endsWith('"')) {
       rest = rest.slice(1, -1);
     }
-    if (isAuthoringValidationPath(rest)) return true;
+    if (isExistingAuthoringValidationPath(targetRoot, rest)) return true;
   }
   return false;
 }
@@ -790,14 +750,61 @@ function readBoundedPositiveIntEnv(name, fallback, max) {
   return Math.min(Math.floor(parsed), max);
 }
 
-function formatBlockingReason(output) {
-  return `GDH post-edit authoring check found blocking diagnostics.\n\n${truncate(output || 'No check output.', MAX_BLOCK_OUTPUT_CHARS)}`;
+function formatBlockingReason(output, targetRoot) {
+  const diagnostics = extractDiagnosticSummaries(output, targetRoot);
+  if (diagnostics.length > 0) {
+    const errorCount = diagnostics.filter(d => d.severity === 'error').length || diagnostics.length;
+    const fileCount = new Set(diagnostics.map(d => d.file)).size || 1;
+    const diagText = diagnostics
+      .slice(0, 8)
+      .map(d => `${d.file}:${d.line}:${d.column} ${d.severity} ${d.message}`)
+      .join('; ');
+    const suffix = diagnostics.length > 8 ? '; ...' : '';
+    return `GDH blocked ${errorCount} GDScript ${errorCount === 1 ? 'error' : 'errors'} in ${fileCount} ${fileCount === 1 ? 'file' : 'files'}: ${truncate(diagText + suffix, MAX_BLOCK_OUTPUT_CHARS)}. Fix these diagnostics before continuing.`;
+  }
+  return `GDH blocked GDScript diagnostics: ${truncate(output || 'No check output.', MAX_BLOCK_OUTPUT_CHARS)}. Fix these diagnostics before continuing.`;
+}
+
+function extractDiagnosticSummaries(output, targetRoot) {
+  const diagnostics = [];
+  for (const raw of String(output || '').split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('[')) continue;
+    const match = line.match(/^(.+):(\d+):(\d+)\s+\[(error|warning|info)\]\s+(.+)$/);
+    if (!match) continue;
+    const absoluteOrUri = match[1];
+    const file = diagnosticFileLabel(absoluteOrUri, targetRoot);
+    diagnostics.push({
+      file,
+      line: match[2],
+      column: match[3],
+      severity: match[4],
+      message: compactOneLine(match[5]),
+    });
+  }
+  return diagnostics;
+}
+
+function diagnosticFileLabel(value, targetRoot) {
+  let filePath = value;
+  try {
+    if (String(value).startsWith('file:')) filePath = fileURLToPath(value);
+  } catch (_err) {
+    filePath = value;
+  }
+  if (path.isAbsolute(filePath)) {
+    const relative = path.relative(targetRoot, filePath);
+    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+      return relative.split(path.sep).join('/');
+    }
+  }
+  return String(filePath).replace(/^res:\/\//, '');
 }
 
 function truncate(value, maxChars) {
   const text = String(value || '').trim();
   if (text.length <= maxChars) return text;
-  return `${text.slice(0, maxChars - 80).trimEnd()}\n... GDH hook output truncated; run \`gdh authoring check --mode post-edit\` for full diagnostics.`;
+  return `${text.slice(0, maxChars - 80).trimEnd()}\n... GDH hook output truncated; fix visible diagnostics first. Collect explicit validation evidence only for handoff or if the visible diagnostics are insufficient.`;
 }
 
 function compactOneLine(value) {
@@ -815,13 +822,13 @@ function reasonHint(output, targetRoot, files) {
   const reasons = match ? match[1].split(',').map(r => r.trim()).filter(Boolean) : [];
   // JSON.stringify embeds the path so spaces and quotes survive shell re-use.
   const targetArg = JSON.stringify(targetRoot);
-  const scopedHint = fileTypeScopedHint(targetArg, files);
+  const scopedHint = fileTypeScopedHint(files);
   // First-match-wins ordering: more specific reasons before generic.
   if (reasons.includes('lsp_instance_identity_mismatch')) {
     return `Cross-worktree LSP from another checkout. Run \`${gdhCommandPrefix()} lsp prune --target ${targetArg}\` then retry the edit.`;
   }
   if (reasons.includes('lsp_state_lock_timeout')) {
-    return `Authoring state lock busy; ${describeLspLock(targetRoot)} Retry the scoped command after the current authoring operation finishes. ${scopedHint}`;
+    return `Authoring state lock busy; ${describeLspLock(targetRoot)} Wait for the current authoring operation to finish before trusting diagnostics. ${scopedHint}`;
   }
   if (reasons.includes('lsp_instance_not_running')) {
     return `LSP not ready inside hook budget; foreground refresh attempted for .gd files and background refresh is running if needed. ${scopedHint}`;
@@ -829,44 +836,24 @@ function reasonHint(output, targetRoot, files) {
   if (reasons.includes('lsp_diagnostics_timeout') || reasons.includes('lsp_connection_failed')) {
     return `Godot LSP did not return diagnostics inside the hook budget; do not treat this as clean. ${scopedHint}`;
   }
-  if (reasons.includes('scene_validation_not_confirmed')) {
-    return `Scene validation did not complete inside the hook budget; do not treat this as clean. ${scopedHint}`;
-  }
-  if (reasons.includes('scene_validation_requires_final_authoring_check')) {
-    return `Stop hooks do not run final scene validation. Run final authoring validation before claiming code-validity. ${scopedHint}`;
-  }
-  if (reasons.includes('project_godot_requires_final_authoring_check')) {
-    return `project.godot is not covered by the LSP broker; run final authoring validation before claiming code-validity.`;
-  }
-  if (reasons.includes('tres_scoped_validation_ignored')) {
-    return `.tres automatic scoped validation is ignored in this GDH version; do not wait on LSP/resource diagnostics for those files.`;
-  }
   if (reasons.includes('broker_not_yet_primed') || reasons.includes('file_not_in_snapshot')) {
     return `Broker did not contain this edit after bounded refresh; do not treat this as clean. Background refresh is running if needed. ${scopedHint}`;
   }
   if (reasons.includes('content_hash_mismatch') || reasons.includes('freshness_expired')) {
     return `Broker snapshot stale after bounded refresh; background refresh is running if needed. ${scopedHint}`;
   }
-  return `Run scoped authoring validation before claiming code-validity. ${scopedHint}`;
+  return `Scoped hook validation did not prove this edit clean. ${scopedHint}`;
 }
 
-function fileTypeScopedHint(targetArg, files) {
+function fileTypeScopedHint(files) {
   const inputFiles = Array.isArray(files) ? unique(files) : [];
   const gdFiles = inputFiles.filter(f => path.extname(f).toLowerCase() === '.gd');
-  const sceneFiles = inputFiles.filter(f => path.extname(f).toLowerCase() === '.tscn');
-  const resourceFiles = inputFiles.filter(f => path.extname(f).toLowerCase() === '.tres');
   const parts = [];
   if (gdFiles.length > 0) {
-    parts.push(`For .gd: \`${gdhCommandPrefix()} authoring diagnostics refresh --target ${targetArg}${changedArgs(gdFiles)}\``);
-  }
-  if (sceneFiles.length > 0) {
-    parts.push(`For .tscn: \`${gdhCommandPrefix()} authoring check --mode post-edit --target ${targetArg}${changedArgs(sceneFiles)}\``);
-  }
-  if (resourceFiles.length > 0) {
-    parts.push('.tres automatic scoped validation is ignored in this GDH version; do not wait on LSP/resource diagnostics for those files.');
+    parts.push('For .gd: hook refresh runs automatically; wait for the next hook result instead of rerunning checks during the edit loop.');
   }
   if (parts.length === 0) {
-    return `Run \`${gdhCommandPrefix()} authoring check --mode final --target ${targetArg}\` before claiming code-validity.`;
+    return 'Collect final validation evidence before claiming code-validity.';
   }
   return parts.join(' ');
 }
@@ -875,10 +862,6 @@ function gdhCommandPrefix() {
   return `npx -y @skillcap/gdh@${PINNED_VERSION}`;
 }
 
-function changedArgs(files) {
-  return files.map(f => ` --changed ${JSON.stringify(f)}`).join('');
-}
-
 function describeLspLock(targetRoot) {
   const stateRoot = resolveStateRoot(targetRoot) || path.join(targetRoot, '.gdh-state');
   const candidates = [
@@ -903,24 +886,11 @@ function describeLspLock(targetRoot) {
   }
   return 'lock metadata unavailable (expected .gdh-state/authoring/lsp.lock or .gdh-state/lsp.lock).';
 }
-// Codex always receives hookSpecificOutput.additionalContext (any event — Codex's
-// hook contract accepts it on PreToolUse / PostToolUse / Stop / etc.).
-//
-// Claude receives hookSpecificOutput.additionalContext on PostToolUse / PostToolBatch
-// / FileChanged. Claude Stop is silent-allow because the Stop hook schema does NOT
-// accept additionalContext (only decision/reason/continue/stopReason/suppressOutput/
-// systemMessage). The previous gate emitted the wrong shape on every Claude Stop
-// and Claude rejected it as "invalid stop hook JSON output" (quick task 260504-o6w
-// bug B, verified live on TheBeacon 2026-05-04).
+// PostToolUse / PostToolBatch / FileChanged can receive additionalContext.
+// Stop is silent for every agent: Claude rejects hookSpecificOutput on Stop,
+// and Codex Stop context proved noisy/stale in TheBeacon dogfooding.
 function context(additionalContext) {
-  // Claude: Stop hook schema does NOT accept hookSpecificOutput.additionalContext
-  // (only decision/reason/continue/stopReason/suppressOutput/systemMessage). Emitting
-  // the wrong shape causes Claude to reject the hook with "invalid stop hook JSON
-  // output" — verified locally 2026-05-04 (quick task 260504-o6w bug B). Drop to
-  // silent-allow on Claude Stop. Claude PostToolUse / PostToolBatch DO accept
-  // additionalContext, so those branches still flow through. Codex accepts
-  // additionalContext on every event.
-  if (AGENT !== 'codex' && CURRENT_EVENT === 'Stop') return allow();
+  if (CURRENT_EVENT === 'Stop') return allow();
   const payload = { hookSpecificOutput: { hookEventName: CURRENT_EVENT, additionalContext } };
   process.stdout.write(`${JSON.stringify(payload)}\n`);
   process.exit(0);