@opengsd/gsd-core 1.4.0-rc.1 → 1.4.0-rc.2

package/hooks/gsd-cursor-post-tool.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-cursor-post-tool.js — Cursor postToolUse hook (issue #777)
+//
+// Cursor invokes this script after each tool call completes.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor postToolUse):
+//   { tool_name, tool_input, tool_output, duration,
+//     conversation_id, generation_id, model, hook_event_name,
+//     cursor_version, workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor postToolUse):
+//   { additional_context?: string }   ← injected as context after the tool use
+//
+// Behaviour:
+//   - After a write-class tool that targets .planning/, reminds the agent
+//     to keep STATE.md current.
+//   - Fails open: any error silently exits 0.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
+const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
+const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
+
+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 {
+    let input;
+    try { input = JSON.parse(raw || '{}'); } catch { process.stdout.write(JSON.stringify({})); return; }
+
+    const toolName = String(
+      input.tool_name || input.toolName || ''
+    ).toLowerCase();
+
+    const isWrite = WRITE_TOOL_RE.test(toolName);
+    if (!isWrite) { process.stdout.write(JSON.stringify({})); return; }
+
+    // Collect only PATH-bearing field values (not free-form content).
+    const paths = [];
+    const walk = (v, depth) => {
+      if (depth > 5 || paths.length > 64) return;
+      if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
+      if (v && typeof v === 'object') {
+        for (const k of Object.keys(v)) {
+          const val = v[k];
+          if (typeof val === 'string' && PATH_KEY_RE.test(k)) paths.push(val);
+          else walk(val, depth + 1);
+        }
+      }
+    };
+    walk(input.tool_input || input.toolInput || {}, 0);
+
+    if (paths.some((p) => PLANNING_PATH_RE.test(p))) {
+      process.stdout.write(JSON.stringify({
+        additional_context:
+          'GSD: .planning/ artifact updated — ensure STATE.md reflects the latest phase and progress.',
+      }));
+      return;
+    }
+  } catch { /* fall through to empty response */ }
+
+  process.stdout.write(JSON.stringify({}));
+});

package/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({}));
+  }
+});

package/hooks/hooks.json

@@ -0,0 +1,69 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-check-update.js\"" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-prompt-guard.js\"", "timeout": 5 },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-read-guard.js\"", "timeout": 5 }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-worktree-path-guard.js\"", "timeout": 5 }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|Agent|Task",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-context-monitor.js\"", "timeout": 10 }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-read-injection-scanner.js\"", "timeout": 5 }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-context-monitor.js\"", "timeout": 10 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-context-monitor.js\"", "timeout": 10 }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-context-monitor.js\"", "timeout": 10 }
+        ]
+      }
+    ],
+    "FileChanged": [
+      {
+        "matcher": "config.json",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-config-reload.js\"", "timeout": 8 }
+        ]
+      }
+    ]
+  }
+}

package/hooks/managed-hooks-registry.cjs

@@ -18,7 +18,10 @@
 const MANAGED_HOOKS = [
   'gsd-check-update-worker.js',
   'gsd-check-update.js',
+  'gsd-config-reload.js',
   'gsd-context-monitor.js',
+  'gsd-cursor-post-tool.js',
+  'gsd-cursor-session-start.js',
   'gsd-graphify-update.sh',
   'gsd-phase-boundary.sh',
   'gsd-prompt-guard.js',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.4.0-rc.1",
+  "version": "1.4.0-rc.2",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "bin": {
     "gsd-core": "bin/install.js",
@@ -12,6 +12,9 @@
     "gsd-core",
     "assets",
     "agents",
+    ".claude-plugin",
+    "gemini-extension.json",
+    "GEMINI.md",
     "hooks",
     "scripts"
   ],
@@ -80,6 +83,7 @@
     "generate:identity": "node scripts/generate-package-identity.cjs",
     "prepack": "npm run build:lib",
     "prepare": "npm run build:lib",
+    "version": "node scripts/sync-manifest-versions.cjs --stage",
     "prepublishOnly": "npm run build:lib && npm run build:hooks",
     "pretest": "npm run build:lib && npm run lint:skill-deps",
     "pretest:coverage": "npm run build:lib && npm run lint:skill-deps",

package/scripts/build-hooks.js

@@ -30,6 +30,13 @@ const HOOKS_TO_COPY = [
   // so require('./managed-hooks-registry.cjs') resolves in the installed hooks/ dir.
   'managed-hooks-registry.cjs',
   'gsd-context-monitor.js',
+  // Cursor lifecycle hooks (issue #777): sessionStart context injection + postToolUse monitor
+  'gsd-cursor-session-start.js',
+  'gsd-cursor-post-tool.js',
+  // Claude Code FileChanged hook (#770) — hot-reloads gsd config when
+  // .planning/config.json changes mid-session. Must ship to dist so the
+  // installer can copy it to the target hooks/ dir and register FileChanged.
+  'gsd-config-reload.js',
   'gsd-prompt-guard.js',
   'gsd-read-guard.js',
   'gsd-read-injection-scanner.js',

package/scripts/changeset/cli.cjs

@@ -42,6 +42,7 @@ function parseArgs(argv) {
     installCommand: `npx ${packageName}@latest`,
     json: false,
     allowEmpty: false,
+    preview: false,
   };
   if (argv.length === 0) return { ok: true, opts };
   opts.cmd = argv[0];
@@ -62,6 +63,7 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === '--json') { opts.json = true; continue; }
     if (a === '--allow-empty') { opts.allowEmpty = true; continue; }
+    if (a === '--preview') { opts.preview = true; continue; }
     if (
       a === '--repo' ||
       a === '--version' ||
@@ -133,6 +135,19 @@ function assembleChangelog(lead, releaseBlock) {
   ].join('\n');
 }
 
+// Insert a "_No notable changes._" placeholder after the dated release heading
+// of an otherwise-empty release block. serializeChangelog with no sections
+// yields just "## [v] - d\n"; we expand the trailing newline into a blank line
+// + placeholder + blank line so parseChangelog still sees the dated heading
+// first and the output is human-readable. Shared by the --allow-empty and
+// --preview zero-fragment paths so they can never drift.
+function injectEmptyPlaceholder(headerOnlyBlock) {
+  return headerOnlyBlock.replace(
+    /^(##\s+\[[^\]]+\][^\n]*)\n+/,
+    '$1\n\n_No notable changes._\n\n',
+  );
+}
+
 function cmdRender(opts) {
   const repo = path.resolve(opts.repo);
   const changesetDir = path.join(repo, '.changeset');
@@ -156,6 +171,38 @@ function cmdRender(opts) {
   // 2. Read priorText once; reuse in all subsequent branches.
   const priorText = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
 
+  // Preview mode (#759): render the dated release section WITHOUT writing
+  // CHANGELOG.md and WITHOUT consuming .changeset fragments. Used by the rc
+  // release job to surface the curated notes for the version under test while
+  // leaving the fragment set intact for the eventual finalize render.
+  if (opts.preview) {
+    // priorChangelog is intentionally null: a preview shows ONLY the new dated
+    // section for the version under test, not the full file history.
+    // serializeChangelog appends priorChangelog verbatim, so passing the prior
+    // text here would dump every past release into the rc job summary.
+    const ir = renderChangelog({
+      fragments,
+      version: opts.version,
+      date: opts.date,
+      priorChangelog: null,
+    });
+    let releaseBlock = serializeChangelog(ir);
+    if (fragments.length === 0) {
+      // Mirror --allow-empty: a no-fragment release still shows a dated heading
+      // with a placeholder rather than an empty block.
+      releaseBlock = injectEmptyPlaceholder(releaseBlock);
+    }
+    return {
+      exitCode: 0,
+      report: {
+        consumed: 0,
+        failures: [],
+        preview: releaseBlock,
+        fragmentCount: fragments.length,
+      },
+    };
+  }
+
   // 3. FIX 1: idempotency guard — if the version is already promoted (a dated
   //    release heading for this version already exists in CHANGELOG), split on
   //    whether fragments are still present:
@@ -201,15 +248,7 @@ function cmdRender(opts) {
       priorChangelog: prior || null,
     });
     const headerOnlyBlock = serializeChangelog(ir);
-    // Insert placeholder after the release header line.
-    // serializeChangelog with no sections yields just "## [v] - d\n" (single
-    // trailing newline, no blank line).  We replace that trailing newline with
-    // a blank line + placeholder + blank line so parseChangelog still sees the
-    // dated heading first and the file is human-readable.
-    const releaseBlock = headerOnlyBlock.replace(
-      /^(##\s+\[[^\]]+\][^\n]*)\n+/,
-      '$1\n\n_No notable changes._\n\n',
-    );
+    const releaseBlock = injectEmptyPlaceholder(headerOnlyBlock);
     // FIX 2: use shared assembleChangelog helper.
     const out = assembleChangelog(lead, releaseBlock);
     fs.writeFileSync(changelogPath, out);
@@ -460,7 +499,8 @@ function cmdGithubReleaseNotes(opts) {
 function usage() {
   return [
     'usage:',
-    '  changeset/cli.cjs render --repo <dir> --version V --date D [--allow-empty] [--json]',
+    '  changeset/cli.cjs render --repo <dir> --version V --date D [--allow-empty] [--preview] [--json]',
+    '    --preview renders the dated section to stdout without writing CHANGELOG.md or consuming fragments.',
     '  changeset/cli.cjs github-release-notes --repo <dir> --from REF --to REF [--output FILE] [--repo-slug OWNER/REPO] [--install-command CMD] [--json]',
     '  changeset/cli.cjs extract --from VERSION --to VERSION [--changelog FILE] [--repo <dir>] [--json]',
     '    Extracts changelog entries strictly after --from (exclusive) and up to',
@@ -525,6 +565,9 @@ function main() {
   const { exitCode, report } = opts.cmd === 'render' ? cmdRender(opts) : cmdGithubReleaseNotes(opts);
   if (opts.json) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  } else if (opts.cmd === 'render' && opts.preview) {
+    // render --preview: emit the rendered section verbatim (no mutation occurred).
+    process.stdout.write(report.preview);
   } else if (opts.cmd === 'github-release-notes' && report.body) {
     process.stdout.write(report.body);
   } else {

package/scripts/ci-test-scope.cjs

@@ -6,16 +6,84 @@ const { existsSync, readdirSync, appendFileSync } = require('fs');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
+// Workflow files that are purely administrative / policy bots. Changes to these
+// files do NOT require the cross-platform test matrix — only a lightweight
+// ubuntu lane running workflow-lint tests is needed.
+// FAIL-SAFE: any .github/workflows/*.yml NOT listed here is treated as a
+// pipeline workflow and gets the full matrix. New workflow files default to full.
+const INERT_WORKFLOWS = new Set([
+  'stale.yml',
+  'branch-cleanup.yml',
+  'branch-naming.yml',
+  'auto-label-issues.yml',
+  'auto-branch.yml',
+  'auto-backmerge.yml',
+  'close-draft-prs.yml',
+  'dismiss-unauthorized-pr-approvals.yml',
+  'pr-gate.yml',
+  'pr-target-validator.yml',
+  'pr-template-format.yml',
+  'require-issue-link.yml',
+  'changeset-required.yml',
+  'docs-required.yml',
+  'discord-changelog.yml',
+]);
+
+// Workflows that gate merges, ship the product, or run security/cross-platform
+// suites — these must ALWAYS get the full pipeline treatment and can never be
+// added to INERT_WORKFLOWS. A module-load assertion enforces this so a mistaken
+// or malicious addition fails CI loudly in the `changes` job on every PR.
+const PROTECTED_WORKFLOWS = new Set([
+  'test.yml',
+  'install-smoke.yml',
+  'mutation.yml',
+  'security-scan.yml',
+  'release.yml',
+]);
+for (const wf of PROTECTED_WORKFLOWS) {
+  if (INERT_WORKFLOWS.has(wf)) {
+    throw new Error(`ci-test-scope: protected workflow "${wf}" must not be in INERT_WORKFLOWS (it requires the full test matrix).`);
+  }
+}
+
+/**
+ * Returns true if the path is an inert (non-pipeline) workflow file.
+ * Only `.github/workflows/<name>` where <name> is in INERT_WORKFLOWS qualifies.
+ */
+function isInertCi(filePath) {
+  if (!filePath.startsWith('.github/workflows/')) return false;
+  const name = filePath.slice('.github/workflows/'.length);
+  // Must be a direct child (no further slashes) and in the allowlist.
+  return !name.includes('/') && INERT_WORKFLOWS.has(name);
+}
+
+// Tests shared by both the 'workflow automation' and 'inert CI' rules.
+const WORKFLOW_LINT_TESTS = [
+  'tests/workflow-shell-pinning.test.cjs',
+  'tests/pr-template-policy.test.cjs',
+  'tests/lint-pr-check-project-dir.test.cjs',
+];
+
 const RULES = [
   {
     name: 'workflow automation',
-    match: path => path.startsWith('.github/workflows/') || path.startsWith('.github/rulesets/'),
+    // Only NON-inert .github/workflows/* and all .github/rulesets/* trigger full matrix.
+    // FAIL-SAFE: any .github/workflows/*.yml not in INERT_WORKFLOWS is treated as pipeline.
+    match: filePath => (filePath.startsWith('.github/workflows/') && !isInertCi(filePath)) ||
+      filePath.startsWith('.github/rulesets/'),
     fullMatrix: true,
     tests: [
-      'tests/workflow-shell-pinning.test.cjs',
+      ...WORKFLOW_LINT_TESTS,
       'tests/release-tarball-smoke-workflow.test.cjs',
-      'tests/lint-pr-check-project-dir.test.cjs',
-      'tests/pr-template-policy.test.cjs',
+    ],
+  },
+  {
+    name: 'inert CI',
+    match: filePath => isInertCi(filePath),
+    fullMatrix: false,
+    tests: [
+      ...WORKFLOW_LINT_TESTS,
+      'tests/policy-lint-shallow-checkout.test.cjs',
     ],
   },
   {
@@ -144,14 +212,6 @@ const RULES = [
       'tests/docs-parity-live-registry.test.cjs',
     ],
   },
-  {
-    name: 'docs content',
-    match: path => path.startsWith('docs/'),
-    fullMatrix: false,
-    tests: [
-      'tests/docs-parity-live-registry.test.cjs',
-    ],
-  },
   {
     name: 'configuration',
     match: path => ['config', 'configuration', 'model-catalog', 'model-profile'].some(k => path.includes(k)),
@@ -229,7 +289,12 @@ function changedFiles(args) {
   if (!args.base || !args.head) {
     throw new Error('--base/--head or --files is required');
   }
-  const stdout = execFileSync('git', ['diff', '--name-only', args.base, args.head], {
+  // Three-dot diff (merge-base...head) matches GitHub's PR "Files changed" semantics.
+  // A two-dot `git diff base head` would surface every file `next` gained after this
+  // branch's merge-base, mis-flagging product_changed/full_matrix on docs-only PRs cut
+  // from a slightly stale base (#837). The `changes` job checks out with fetch-depth: 0,
+  // so the merge-base is always available.
+  const stdout = execFileSync('git', ['diff', '--name-only', `${args.base}...${args.head}`], {
     encoding: 'utf8',
   });
   return splitFiles(stdout);
@@ -251,16 +316,30 @@ function classify(files) {
   const targeted = new Set();
   const windows = new Set();
   const reasons = [];
-  let codeChanged = false;
+  let productOrPipelineChanged = false; // product/pipeline code (excludes docs)
+  let inertCiChanged = false;           // inert workflow files
   let fullMatrix = false;
 
   for (const file of files) {
-    if (['bin/', 'gsd-core/', 'agents/', 'commands/', 'docs/', 'hooks/', 'tests/', 'scripts/'].some(p => file.startsWith(p)) ||
+    // Determine if this file is product/pipeline code.
+    // docs/ and root-level .md files are intentionally excluded.
+    if (
+      ['bin/', 'src/', 'gsd-core/', 'agents/', 'commands/', 'hooks/', 'tests/', 'scripts/'].some(p => file.startsWith(p)) ||
       file === 'package.json' || file === 'package-lock.json' ||
       (file.startsWith('tsconfig') && file.endsWith('.json')) ||
-      file.startsWith('.github/workflows/') ||
-      file.startsWith('.github/rulesets/')) {
-      codeChanged = true;
+      file.startsWith('.github/rulesets/')
+    ) {
+      productOrPipelineChanged = true;
+    }
+
+    // Non-inert .github/workflows/* are pipeline code → full matrix.
+    if (file.startsWith('.github/workflows/') && !isInertCi(file)) {
+      productOrPipelineChanged = true;
+    }
+
+    // Inert workflow files set a lightweight signal.
+    if (isInertCi(file)) {
+      inertCiChanged = true;
     }
 
     if (file.startsWith('tests/') && file.endsWith('.test.cjs')) {
@@ -280,6 +359,10 @@ function classify(files) {
     }
   }
 
+  // code_changed: true when product/pipeline OR inert CI changed.
+  // Docs-only PRs (neither flag set) get code_changed=false → full matrix skip.
+  const codeChanged = productOrPipelineChanged || inertCiChanged;
+
   const targetedTests = existingTests([...targeted].sort());
 
   // When code changed but no rule matched any changed file, fall back to the
@@ -290,8 +373,25 @@ function classify(files) {
 
   const windowsTests = existingTests([...new Set([...windows, ...targetedTests.filter(isWindowsHint)])].sort());
 
+  // Inert-CI-only: full_matrix must be false (override any RULES that fired).
+  if (inertCiChanged && !productOrPipelineChanged) {
+    fullMatrix = false;
+  }
+
+  // Normalize: when code_changed is false, the output must be self-consistent.
+  // A docs file can coincidentally match a coarse content RULE (e.g. docs/installer-migrations.md
+  // matches the installer rule via path.includes('install')), leaving full_matrix=true and
+  // non-empty targeted_tests/windows_tests. The workflow skips correctly (gated on code_changed)
+  // but the output object would be self-contradictory. Force a clean "nothing to run" result.
+  if (!codeChanged) {
+    fullMatrix = false;
+    targetedTests.length = 0;
+    windowsTests.length = 0;
+  }
+
   return {
     code_changed: codeChanged,
+    product_changed: productOrPipelineChanged,
     full_matrix: fullMatrix,
     targeted_tests: targetedTests,
     windows_tests: windowsTests,
@@ -303,6 +403,7 @@ function writeOutputs(result) {
   if (!process.env.GITHUB_OUTPUT) return;
   const lines = [
     `code_changed=${result.code_changed}`,
+    `product_changed=${result.product_changed}`,
     `full_matrix=${result.full_matrix}`,
     `targeted_tests=${result.targeted_tests.join(' ')}`,
     `windows_tests=${result.windows_tests.join(' ')}`,
@@ -313,6 +414,7 @@ function writeOutputs(result) {
 function main() {
   try {
     const args = parseArgs(process.argv.slice(2));
+
     const files = changedFiles(args);
     const result = classify(files);
     result.changed_files = files;