feat(#777): register Cursor-native hooks (.cursor/hooks.json) for session-start/post-tool parity (#831)

* feat(#777): register Cursor-native hooks (.cursor/hooks.json) for session-start/post-tool parity

- Add gsd-cursor-session-start.js: injects STATE.md presence reminder (or
  new-project nudge) into Cursor sessions via the sessionStart hook event
- Add gsd-cursor-post-tool.js: emits an additional_context nudge when
  write-class tool calls touch .planning/ files (postToolUse hook event)
- Add 'cursor-hooks-json' installSurface to runtime-config-adapter-registry;
  writeCursorHooksJson/reconcileCursorHooksJson write the canonical
  { version: 1, hooks: { sessionStart, postToolUse } } JSON shape with
  idempotent reconciliation that preserves user-owned hook entries
- Hook scripts are copied with /gsd:→gsd- rewrite so installed files
  contain no colon-form slash-command refs (bug-376 invariant)
- 20 new tests in tests/cursor-hooks.test.cjs cover all reconciler paths,
  entry helpers, removal, runtime adapter surface, and hook script behavior
- Update CONTEXT.md, ARCHITECTURE.md, installer-migrations.md, and
  000-first-time-baseline.cts to include Cursor hooks.json surface

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#777): build hooks/dist on demand in bug-376 test for scoped/windows CI

hooks/dist is gitignored and only produced by `npm run build:hooks`.
The CI scoped (ubuntu-latest/node-22) and windows (windows-latest/node-24)
test jobs do NOT run build:hooks before executing tests, so bug-376's
prerequisite suite was failing with "hooks/dist not found" on both legs.

Add ensureHooksDist() helper (mirrors bug-3357 pattern) that builds
hooks/dist on demand in the before() hooks of prerequisite and Suite 3.
Also add ensureHooksDist() call to Suite 3's before() so the snapshot
step is also hermetic.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

hooks/gsd-cursor-session-start.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-cursor-session-start.js — Cursor sessionStart hook (issue #777)
+//
+// Cursor invokes this script at the start of each agent session.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor sessionStart):
+//   { session_id, is_background_agent, composer_mode, conversation_id,
+//     generation_id, model, hook_event_name, cursor_version,
+//     workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor sessionStart):
+//   { additional_context?: string }   ← injected into the session as context
+//
+// Behaviour:
+//   - If .planning/STATE.md is present, injects a brief state reminder.
+//   - If absent, nudges the user toward /gsd:new-project.
+//   - Fails open: any error silently exits 0 so a hook bug never wedges Cursor.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MSG_PRESENT =
+  'GSD: .planning/STATE.md is present — review the current phase and any blockers before acting.';
+const MSG_ABSENT =
+  'GSD: no .planning/ workflow found — run /gsd:new-project to start a tracked workflow.';
+
+let raw = '';
+const stdinTimeout = setTimeout(() => {
+  // Timeout guard: exit silently rather than hanging.
+  process.exit(0);
+}, 10000);
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const statePath = path.join(process.cwd(), '.planning', 'STATE.md');
+    const statePresent = fs.existsSync(statePath);
+    const msg = statePresent ? MSG_PRESENT : MSG_ABSENT;
+    process.stdout.write(JSON.stringify({ additional_context: msg }));
+  } catch {
+    // Fail open — never block a Cursor session because of a GSD hook error.
+    process.stdout.write(JSON.stringify({}));
+  }
+});