@skillcap/gdh 0.26.1 → 0.26.3

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

@@ -4,9 +4,18 @@
 const PINNED_VERSION = {{pinnedVersionJson}};
 const TARGET_RELATIVE_PATH = {{targetRelativePathJson}};
 const AGENT = {{agentJson}};
+// POSIX-normalised relative path from this hook script's directory (__dirname)
+// to the integration root's `.gdh-state/` directory. Baked at install-plan time
+// from `path.relative(hookDirAbsolute, path.join(integrationRootAbsolute, ".gdh-state"))`.
+// The embedded broker-snapshot reader (Task 2) resolves
+// `path.resolve(__dirname, STATE_RELATIVE_PATH_FROM_HOOK)` to find
+// `authoring/lsp-instance.json` and `authoring/diagnostics-broker/snapshot.json`.
+const STATE_RELATIVE_PATH_FROM_HOOK = {{stateRelativePathFromHookJson}};
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
+const { pathToFileURL } = require('url');
 const { spawnSync } = require('child_process');
 
 const AUTHORING_EXTENSIONS = new Set(['.gd', '.tscn', '.tres']);
@@ -49,32 +58,36 @@ function handlePostEdit(input, targetRoot) {
   // within CHECK_TIMEOUT_MS regardless of warmup outcome (Pitfall 1: detached +
   // stdio:'ignore' + .unref() means the parent never blocks on the child).
   spawnDetachedWarmup(targetRoot);
-  const changedArgs = authoring.flatMap((file) => ['--changed', file]);
-  // Run one compact fast check. Post-edit checks reuse a running LSP if present,
-  // trust only content-matched broker diagnostics, and avoid cold Godot startup.
-  const result = runGdh(targetRoot, ['authoring', 'check', '--target', targetRoot, '--mode', 'post-edit', '--format', 'compact', ...changedArgs], {
-    timeoutMs: CHECK_TIMEOUT_MS,
-  });
-  if (result.timedOut) {
-    return context(`GDH post-edit authoring check timed out after ${CHECK_TIMEOUT_MS}ms; continuing without blocking. Run \`gdh authoring check --mode final\` before claiming code-validity.`);
+  // Quick task 260504-ix2: embedded broker-snapshot reader. Replaces the
+  // per-edit synchronous `npx -y @skillcap/gdh@PINNED authoring check ...`
+  // shellout (which was eating the full `CHECK_TIMEOUT_MS` budget on the npx
+  // bootstrap path even before any GDH code ran). The reader synthesises the
+  // same `[fresh]` / `[stale]` / `[pending]` bracketed-token vocabulary the
+  // existing dispatch already consumes, so the regex ladder below is unchanged.
+  let output;
+  try {
+    output = runEmbeddedDiagnosticsRead(targetRoot, authoring);
+  } catch (_err) {
+    return context('GDH post-edit hook embedded read threw; continuing without blocking. Run `gdh authoring check --mode final` 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
   // [error]/[warning]/[info] severity brackets do not match the status token.
-  if (/^\[failed\]/m.test(result.output) || /^\[partial\]/m.test(result.output)) {
-    return block(formatBlockingReason(result.output));
+  // The embedded reader does not currently emit `[failed]` / `[partial]` /
+  // `[timeout]` (those statuses come from the legacy CLI compact formatter),
+  // 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));
   }
-  if (/^\[fresh\]/m.test(result.output)) {
+  if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
-  if (/^\[pending\]/m.test(result.output) || /^\[stale\]/m.test(result.output)) {
-    return context(`GDH post-edit authoring check could not prove this edit quickly; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
-  }
-  if (/^\[timeout\]/m.test(result.output)) {
-    return context(`GDH post-edit authoring check returned a timeout status; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  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.')}`);
   }
-  if (!result.ok) {
-    return context(`GDH post-edit authoring check failed before producing diagnostics; continuing without blocking. ${compactOneLine(result.error || result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  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.')}`);
   }
   return allow();
 }
@@ -122,58 +135,45 @@ function handlePostToolBatch(input, targetRoot) {
   // returns warming without spawning a second Godot.
   spawnDetachedWarmup(targetRoot);
 
-  const changedArgs = authoring.flatMap((file) => ['--changed', file]);
-  // SC1: ONE coalesced check, not N. Same runGdh envelope as handlePostEdit —
-  // do NOT introduce a parallel CLI path.
-  const result = runGdh(
-    targetRoot,
-    ['authoring', 'check', '--target', targetRoot, '--mode', 'post-edit', '--format', 'compact', ...changedArgs],
-    { timeoutMs: CHECK_TIMEOUT_MS },
-  );
-
-  if (result.timedOut) {
-    return context(`GDH PostToolBatch authoring check timed out after ${CHECK_TIMEOUT_MS}ms; continuing without blocking. Run \`gdh authoring check --mode final\` before claiming code-validity.`);
+  // Quick task 260504-ix2: embedded broker-snapshot reader replaces the
+  // synchronous `npx ... authoring check` shellout. The reader is invoked
+  // ONCE with the full deduplicated authoring set — the LSP-09 coalescing
+  // invariant is preserved: the loop in `runEmbeddedDiagnosticsRead` walks
+  // every file but returns on the first non-fresh status (first-failure-wins
+  // is the documented contract; a [stale] in any one file routes the batch
+  // through the drift dispatch branch).
+  let output;
+  try {
+    output = runEmbeddedDiagnosticsRead(targetRoot, authoring);
+  } catch (_err) {
+    return context('GDH PostToolBatch hook embedded read threw; continuing without blocking. Run `gdh authoring check --mode final` before claiming code-validity.');
   }
+
   // Bracketed-token dispatch — IDENTICAL to handlePostEdit. Pitfall 5 from Phase 81
   // applies: anchor regex with /^.../m so per-diagnostic [error]/[warning]/[info]
-  // severity brackets do not match the line-leading status token.
-  if (/^\[failed\]/m.test(result.output) || /^\[partial\]/m.test(result.output)) {
-    return block(formatBlockingReason(result.output));
+  // 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));
   }
-  if (/^\[fresh\]/m.test(result.output)) {
+  if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
-  if (/^\[pending\]/m.test(result.output) || /^\[stale\]/m.test(result.output)) {
-    return context(`GDH PostToolBatch authoring check could not prove this batch quickly; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
-  }
-  if (/^\[timeout\]/m.test(result.output)) {
-    return context(`GDH PostToolBatch authoring check returned a timeout status; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  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.')}`);
   }
-  if (!result.ok) {
-    return context(`GDH PostToolBatch authoring check failed before producing diagnostics; continuing without blocking. ${compactOneLine(result.error || result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  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.')}`);
   }
   return allow();
 }
 
-function runGdh(targetRoot, args, options = {}) {
-  const result = spawnSync('npx', ['-y', `@skillcap/gdh@${PINNED_VERSION}`, ...args], {
-    cwd: targetRoot,
-    encoding: 'utf8',
-    windowsHide: true,
-    timeout: options.timeoutMs || CHECK_TIMEOUT_MS,
-  });
-  const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
-  const error = result.error ? String(result.error.message || result.error) : '';
-  return {
-    ok: result.status === 0 && !result.error,
-    output,
-    error,
-    timedOut: Boolean(
-      (result.error && result.error.code === 'ETIMEDOUT') ||
-      result.signal === 'SIGTERM'
-    ),
-  };
-}
+// Quick task 260504-ix2: `runGdh` deleted. The function previously wrapped
+// `spawnSync('npx', ['-y', '@skillcap/gdh@PINNED', ...args])` for the three
+// event handlers (handlePostEdit, handlePostToolBatch, handleStop). All three
+// now call `runEmbeddedDiagnosticsRead` instead. `spawnDetachedWarmup` uses
+// `child_process.spawn` directly (always did — it was never a `runGdh`
+// caller), so removing the helper has no effect on the warmup path.
 
 // Phase 82 / LSP-02. Fire-and-forget warmup spawn from the post-edit hook. The
 // hook returns within CHECK_TIMEOUT_MS regardless of whether warmup has finished
@@ -202,24 +202,48 @@ function spawnDetachedWarmup(targetRoot) {
   }
 }
 
-// Phase 82 / LSP-03. Session-end ("Stop") freshness barrier.
+// 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.
 //
-// Hard contract:
-//   - Runs gdh authoring check --mode final with STOP_TIMEOUT_MS bound (60 s default)
-//   - Reports unresolved diagnostics as additionalContext, NEVER decision: block (Pitfall 3)
-//   - Degrades to context() on subprocess timeout, error, or Godot crash
-//   - additionalContext bounded to MAX_STOP_CONTEXT_CHARS = 8000 (Pitfall 6)
+// 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.
 //
-// Stop hook waits for in-flight warmup naturally: --mode final calls
-// getManagedLspStatus(launch_if_needed) which acquires lsp.lock; if warmup is
-// holding the lock, the 5 s LSP_STATE_LOCK_ACQUIRE_TIMEOUT_MS retry loop inside
-// the lock primitive handles the wait (Pitfall 9 — well within 60 s).
+// 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 handleStop(input, targetRoot) {
-  const result = runGdh(
-    targetRoot,
-    ['authoring', 'check', '--target', targetRoot, '--mode', 'final', '--format', 'compact'],
-    { timeoutMs: STOP_TIMEOUT_MS },
-  );
+  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.
+  const authoringFiles = listAuthoringFilesInTarget(targetRoot);
+
+  let output;
+  try {
+    output = runEmbeddedDiagnosticsRead(targetRoot, authoringFiles);
+  } catch (_err) {
+    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();
@@ -228,33 +252,254 @@ function handleStop(input, targetRoot) {
     const headroom = ceiling - truncatedSuffix.length;
     return context(text.slice(0, headroom).trimEnd() + truncatedSuffix);
   }
-  if (result.timedOut) {
-    return stopContext(
-      `GDH session-end check timed out after ${STOP_TIMEOUT_MS}ms; continuing without blocking.` +
-      ' Run `gdh authoring check --mode final` manually before claiming code-validity.',
-    );
-  }
+
   // Bracketed-token dispatch — same vocabulary as PostToolUse but EVERY branch
   // routes to context() or allow(); decision: block is forbidden on Stop.
-  if (/^\[fresh\]/m.test(result.output)) {
+  // 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(result.output) || /^\[partial\]/m.test(result.output) || /^\[stale\]/m.test(result.output)) {
-    return stopContext(`GDH session-end check found unresolved diagnostics: ${compactOneLine(result.output)}`);
+  if (/^\[failed\]/m.test(output) || /^\[partial\]/m.test(output) || /^\[stale\]/m.test(output)) {
+    return stopContext(`GDH session-end check found unresolved diagnostics: ${compactOneLine(output)}`);
   }
-  if (/^\[pending\]/m.test(result.output) || /^\[timeout\]/m.test(result.output)) {
+  if (/^\[pending\]/m.test(output) || /^\[timeout\]/m.test(output)) {
+    // Cold/missing broker: spawn detached warmup 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). spawnDetachedWarmup is fire-and-forget; it never
+    // blocks hook return.
+    spawnDetachedWarmup(targetRoot);
     return stopContext(
-      'GDH session-end check did not produce a final result before time bound; continuing without blocking. ' +
-      compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.'),
+      '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),
     );
   }
-  // Unknown / runtime error: degrade to additionalContext (NEVER block).
+  // Unknown status: degrade to additionalContext (NEVER block).
+  spawnDetachedWarmup(targetRoot);
   return stopContext(
     'GDH session-end check could not produce a final result; continuing without blocking. ' +
-    compactOneLine(result.output || result.error || 'Run final authoring validation before claiming code-validity.'),
+    'Run `gdh authoring check --mode final` manually before claiming code-validity. ' +
+    compactOneLine(output),
   );
 }
 
+// Quick task 260504-ix2: collect authoring-relevant files in the working tree
+// under `targetRoot`. Sibling helper to `hasAuthoringWorkInTarget` (which
+// 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).
+function listAuthoringFilesInTarget(targetRoot) {
+  let result;
+  try {
+    result = spawnSync('git', ['-C', targetRoot, 'status', '--porcelain', '--', '.'], {
+      encoding: 'utf8',
+      timeout: 1500,
+      windowsHide: true,
+    });
+  } catch (_error) {
+    return [];
+  }
+  if (!result || result.error || result.status !== 0 || result.signal) return [];
+  const files = [];
+  for (const raw of String(result.stdout || '').split('\n')) {
+    if (!raw || raw.length < 4) continue;
+    let rest = raw.slice(3);
+    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);
+  }
+  return unique(files);
+}
+
+// Quick task 260504-ix2: dependency-free embedded broker-snapshot reader.
+//
+// Replaces the per-edit `npx -y @skillcap/gdh@PINNED authoring check ...`
+// shellout (which paid the ~9.3 s npx bootstrap cost on every hook fire).
+// Reads `<stateRoot>/authoring/lsp-instance.json` and
+// `<stateRoot>/authoring/diagnostics-broker/snapshot.json` directly,
+// validates LSP instance identity + per-file SHA-256 content hash +
+// freshness window, and synthesises the same bracketed-token output the
+// existing dispatch consumes (`[fresh]` / `[stale]` / `[pending]`).
+//
+// Reasons vocabulary (kept aligned with packages/authoring/src/lsp.ts):
+//   lsp_instance_not_running, lsp_instance_parse_error,
+//   broker_not_yet_primed, snapshot_parse_error, unsupported_broker_schema,
+//   lsp_instance_identity_mismatch, content_hash_mismatch, freshness_expired,
+//   file_not_in_snapshot, state_root_unresolved.
+//
+// Hash parity: the broker writer (`packages/authoring/src/diagnostics-broker.ts`
+// `hashText`) and the cache validator (`packages/authoring/src/lsp.ts`
+// `hashFilesByUri`) both read files via `fs.readFile(path, "utf8")` and
+// SHA-256 the resulting string. The embedded reader MUST do the same so a
+// fresh snapshot covering an unmodified file matches by content hash.
+function runEmbeddedDiagnosticsRead(targetRoot, authoringFiles) {
+  const stateRoot = resolveStateRoot(targetRoot);
+  if (stateRoot === null) {
+    return formatStatus('pending', ['state_root_unresolved']);
+  }
+
+  const lspInstancePath = path.join(stateRoot, 'authoring', 'lsp-instance.json');
+  let lspInstance;
+  try {
+    const raw = fs.readFileSync(lspInstancePath, 'utf8');
+    lspInstance = JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return formatStatus('pending', ['lsp_instance_not_running']);
+    return formatStatus('pending', ['lsp_instance_parse_error']);
+  }
+  const expectedInstanceId = lspInstance && lspInstance.instance && lspInstance.instance.instanceId;
+  if (typeof expectedInstanceId !== 'string' || expectedInstanceId.length === 0) {
+    return formatStatus('pending', ['lsp_instance_not_running']);
+  }
+
+  const snapshotPath = path.join(stateRoot, 'authoring', 'diagnostics-broker', 'snapshot.json');
+  let snapshot;
+  try {
+    const raw = fs.readFileSync(snapshotPath, 'utf8');
+    snapshot = JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return formatStatus('pending', ['broker_not_yet_primed']);
+    return formatStatus('pending', ['snapshot_parse_error']);
+  }
+  if (!snapshot || snapshot.schemaVersion !== 1) {
+    return formatStatus('pending', ['unsupported_broker_schema']);
+  }
+  if (snapshot.lspInstanceId !== expectedInstanceId) {
+    return formatStatus('stale', ['lsp_instance_identity_mismatch']);
+  }
+
+  const filesByUri = new Map();
+  if (Array.isArray(snapshot.files)) {
+    for (const f of snapshot.files) if (f && typeof f.uri === 'string') filesByUri.set(f.uri, f);
+  }
+
+  // Match the constant in `packages/authoring/src/lsp.ts`
+  // (`DIAGNOSTICS_BROKER_DEFAULT_FRESHNESS_STALE_AFTER_MS`). Hard-coded here
+  // because the hook is dependency-free and cannot import @gdh/authoring.
+  const STALE_AFTER_MS = 60000;
+  const nowMs = Date.now();
+  const allDiagnostics = [];
+
+  for (const relPath of authoringFiles) {
+    // Match the broker writer's URI canonicalisation: it calls
+    // `fs.realpath` on each requested file before `pathToFileURL.href`,
+    // which collapses macOS `/var/folders` → `/private/var/folders`
+    // symlinks (and similar real-symlink layouts on Linux/Windows). The
+    // hook's `__dirname` already comes through canonicalised by Node's
+    // module loader, but the legacy `path.resolve` in the resolver does
+    // NOT walk symlinks. Use `canonicalPath` (already-defined helper) so
+    // the URIs match a snapshot captured by `hashFilesByUri`.
+    const absolutePath = canonicalPath(path.resolve(targetRoot, relPath));
+    const expectedUri = pathToFileURL(absolutePath).href;
+    const entry = filesByUri.get(expectedUri);
+    if (!entry) return formatStatus('pending', ['file_not_in_snapshot']);
+
+    if (typeof entry.contentHash !== 'string' || entry.contentHash.length === 0) {
+      // Pre-content-hash snapshot entries cannot prove current file content.
+      // Plan info-note: route through `[pending]` (not `[stale]`) — the broker
+      // is not yet fully primed for this file even if the snapshot exists.
+      return formatStatus('pending', ['broker_not_yet_primed']);
+    }
+
+    let onDiskHash;
+    try {
+      const text = fs.readFileSync(absolutePath, 'utf8');
+      onDiskHash = crypto.createHash('sha256').update(text).digest('hex');
+    } catch (_err) {
+      // File deleted between hook trigger and read, or unreadable encoding.
+      // Fallthrough: treat as not-in-snapshot so we degrade to additionalContext.
+      return formatStatus('pending', ['file_not_in_snapshot']);
+    }
+    if (onDiskHash !== entry.contentHash) {
+      return formatStatus('stale', ['content_hash_mismatch']);
+    }
+
+    const updatedMs = Date.parse(entry.lastUpdatedAt);
+    if (!Number.isFinite(updatedMs) || (nowMs - updatedMs) > STALE_AFTER_MS) {
+      return formatStatus('stale', ['freshness_expired']);
+    }
+
+    if (Array.isArray(entry.diagnostics)) {
+      for (const diag of entry.diagnostics) {
+        allDiagnostics.push({ uri: entry.uri, diag });
+      }
+    }
+  }
+
+  return formatFreshDiagnostics(allDiagnostics);
+}
+
+function formatStatus(token, reasons) {
+  return `[${token}]\nReasons: ${reasons.join(', ')}`;
+}
+
+function formatFreshDiagnostics(items) {
+  let errors = 0;
+  let warnings = 0;
+  let infoCount = 0;
+  const lines = [];
+  for (const item of items) {
+    const diag = item.diag;
+    const sev = (diag && typeof diag.severity === 'string') ? diag.severity : 'info';
+    if (sev === 'error') errors += 1;
+    else if (sev === 'warning') warnings += 1;
+    else infoCount += 1;
+    const line = (diag && diag.range && diag.range.start && Number.isFinite(diag.range.start.line)) ? diag.range.start.line + 1 : 0;
+    const col = (diag && diag.range && diag.range.start && Number.isFinite(diag.range.start.character)) ? diag.range.start.character + 1 : 0;
+    const msg = (diag && typeof diag.message === 'string') ? diag.message : '';
+    lines.push(`${item.uri}:${line}:${col} [${sev}] ${msg}`);
+  }
+  // Mirror packages/authoring/src/diagnostics-summary.ts: with the default
+  // "error" severity policy, ANY error diagnostic produces a `blocked` summary
+  // → CLI emits `[failed]` → hook dispatch routes to `block()`. The embedded
+  // reader must produce the same status token so the hook still blocks edits
+  // that introduce errors. Warnings and info do not alter the status token.
+  const statusToken = errors > 0 ? 'failed' : 'fresh';
+  const completion = errors > 0 ? 'blocked' : 'allowed';
+  const head = lines.length ? `${lines.join('\n')}\n` : '';
+  return `${head}[${statusToken}] ${errors} errors, ${warnings} warnings, ${infoCount} info. Completion ${completion}.`;
+}
+
+function resolveStateRoot(targetRoot) {
+  // 1. Baked render-time path — the canonical resolution for installed hooks.
+  try {
+    const baked = path.resolve(__dirname, STATE_RELATIVE_PATH_FROM_HOOK);
+    if (fs.existsSync(baked)) return baked;
+  } catch (_err) {
+    // Fall through to walk-up fallbacks if the baked path is malformed.
+  }
+  // 2. Walk up from __dirname looking for `.gdh/project.yaml`. Useful when the
+  //    hook script has been moved or the bake-time relative path is wrong.
+  let dir = __dirname;
+  for (let i = 0; i < 10; i += 1) {
+    if (fs.existsSync(path.join(dir, '.gdh', 'project.yaml'))) {
+      return path.join(dir, '.gdh-state');
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // 3. Walk up from targetRoot — covers root-launched cases where the hook
+  //    might be loaded from outside the project tree.
+  dir = targetRoot;
+  for (let i = 0; i < 10; i += 1) {
+    if (fs.existsSync(path.join(dir, '.gdh', 'project.yaml'))) {
+      return path.join(dir, '.gdh-state');
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 function collectChangedFiles(input, targetRoot) {
   const baseCwd = input && typeof input.cwd === 'string' ? input.cwd : process.cwd();
   const files = [];
@@ -310,6 +555,43 @@ function isAuthoringValidationPath(file) {
   return AUTHORING_EXTENSIONS.has(path.extname(file).toLowerCase());
 }
 
+// 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.
+//
+// Honors GDH_AUTHORING_STOP_GIT_GATE=0 as an ops escape valve.
+function hasAuthoringWorkInTarget(targetRoot) {
+  if (process.env['GDH_AUTHORING_STOP_GIT_GATE'] === '0') return true;
+  let result;
+  try {
+    result = spawnSync('git', ['-C', targetRoot, 'status', '--porcelain', '--', '.'], {
+      encoding: 'utf8',
+      timeout: 1500,
+      windowsHide: true,
+    });
+  } catch (_error) {
+    return true; // fail-closed: spawn threw (e.g. git missing on PATH)
+  }
+  if (!result || result.error || result.status !== 0 || result.signal) return true;
+  const lines = String(result.stdout || '').split('\n');
+  for (const raw of lines) {
+    if (!raw) continue;
+    // Porcelain v1: 2 status chars + space + path (or path -> path for renames).
+    // Skip lines shorter than the minimum "XY P" shape.
+    if (raw.length < 4) continue;
+    let rest = raw.slice(3);
+    // Renames / copies: "OLD -> NEW" — take NEW.
+    const arrow = rest.indexOf(' -> ');
+    if (arrow !== -1) rest = rest.slice(arrow + 4);
+    // Quoted paths (spaces / non-ASCII): strip surrounding quotes.
+    if (rest.startsWith('"') && rest.endsWith('"')) {
+      rest = rest.slice(1, -1);
+    }
+    if (isAuthoringValidationPath(rest)) return true;
+  }
+  return false;
+}
+
 function resolveTargetRoot(input) {
   const base = path.resolve(__dirname, '..', '..');
   const fromScript = path.resolve(base, TARGET_RELATIVE_PATH || '.');

package/node_modules/@gdh/adapters/package.json

@@ -11,13 +11,13 @@
     }
   },
   "dependencies": {
-    "@gdh/authoring": "0.26.1",
-    "@gdh/core": "0.26.1",
-    "@gdh/docs": "0.26.1",
-    "@gdh/observability": "0.26.1",
-    "@gdh/runtime": "0.26.1",
-    "@gdh/scan": "0.26.1",
-    "@gdh/verify": "0.26.1"
+    "@gdh/authoring": "0.26.3",
+    "@gdh/core": "0.26.3",
+    "@gdh/docs": "0.26.3",
+    "@gdh/observability": "0.26.3",
+    "@gdh/runtime": "0.26.3",
+    "@gdh/scan": "0.26.3",
+    "@gdh/verify": "0.26.3"
   },
-  "version": "0.26.1"
+  "version": "0.26.3"
 }

package/node_modules/@gdh/authoring/package.json

@@ -14,7 +14,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@gdh/core": "0.26.1"
+    "@gdh/core": "0.26.3"
   },
-  "version": "0.26.1"
+  "version": "0.26.3"
 }

package/node_modules/@gdh/cli/package.json

@@ -15,16 +15,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@gdh/adapters": "0.26.1",
-    "@gdh/authoring": "0.26.1",
-    "@gdh/core": "0.26.1",
-    "@gdh/docs": "0.26.1",
-    "@gdh/mcp": "0.26.1",
-    "@gdh/observability": "0.26.1",
-    "@gdh/runtime": "0.26.1",
-    "@gdh/scan": "0.26.1",
-    "@gdh/verify": "0.26.1",
+    "@gdh/adapters": "0.26.3",
+    "@gdh/authoring": "0.26.3",
+    "@gdh/core": "0.26.3",
+    "@gdh/docs": "0.26.3",
+    "@gdh/mcp": "0.26.3",
+    "@gdh/observability": "0.26.3",
+    "@gdh/runtime": "0.26.3",
+    "@gdh/scan": "0.26.3",
+    "@gdh/verify": "0.26.3",
     "picocolors": "^1.1.1"
   },
-  "version": "0.26.1"
+  "version": "0.26.3"
 }

package/node_modules/@gdh/core/dist/index.d.ts

@@ -55,7 +55,7 @@ export declare const GDH_AUTHORING_DOGFOOD_VERSION = 1;
 export declare const GDH_AUTHORING_SLICE_REPORT_VERSION = 1;
 export declare const GDH_MCP_MANIFEST_VERSION = 1;
 export declare const GDH_CURSOR_RULE_VERSION = 4;
-export declare const GDH_UPDATE_HOOK_VERSION = 10;
+export declare const GDH_UPDATE_HOOK_VERSION = 12;
 export declare const GDH_RUNTIME_RECIPE_RUN_VERSION = 1;
 export declare const GDH_RUNTIME_RUN_BUNDLE_VERSION = 1;
 export declare const GDH_RUNTIME_CORPUS_ARTIFACT_VERSION = 1;

package/node_modules/@gdh/core/dist/index.js

@@ -47,7 +47,7 @@ export const GDH_AUTHORING_DOGFOOD_VERSION = 1;
 export const GDH_AUTHORING_SLICE_REPORT_VERSION = 1;
 export const GDH_MCP_MANIFEST_VERSION = 1;
 export const GDH_CURSOR_RULE_VERSION = 4;
-export const GDH_UPDATE_HOOK_VERSION = 10;
+export const GDH_UPDATE_HOOK_VERSION = 12;
 export const GDH_RUNTIME_RECIPE_RUN_VERSION = 1;
 export const GDH_RUNTIME_RUN_BUNDLE_VERSION = 1;
 export const GDH_RUNTIME_CORPUS_ARTIFACT_VERSION = 1;

package/node_modules/@gdh/core/package.json

@@ -10,5 +10,5 @@
       "import": "./dist/index.js"
     }
   },
-  "version": "0.26.1"
+  "version": "0.26.3"
 }

package/node_modules/@gdh/docs/package.json

@@ -11,8 +11,8 @@
     }
   },
   "dependencies": {
-    "@gdh/core": "0.26.1",
+    "@gdh/core": "0.26.3",
     "yaml": "^2.8.3"
   },
-  "version": "0.26.1"
+  "version": "0.26.3"
 }