fix(regen): report missing dependencies as REGEN_DEPS_MISSING, not REGEN_STALE

When package.json declares dependencies and node_modules is missing, the
scratch worktree runs the generator without them. A generator that degrades
and still exits 0 then looked stale, and the fix line sent people to rerun
the generator. gstack-regen check and the pregate regen check now report
"dependencies missing; run <install>" with its own result code and
troubleshooting anchor; the install command follows the lockfile. The
fixture reproduces the shape GSTA-31 saw in gbrain.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

lib/pregate/checks/regen.ts

@@ -27,7 +27,9 @@ function run(ctx: PregateContext): CheckResult {
   const lines = results.map(renderEntry);
   const stale = results.filter(r => r.status === 'stale');
   const failed = results.filter(r => r.status === 'failed');
+  const depsMissing = results.filter(r => r.status === 'deps-missing');
   ctx.explain.push(...results.map(r => `regen ${r.id}: selected because touched ∩ (${selected.find(e => e.id === r.id)?.inputs.join(',') || 'always'} ∪ outputs) ≠ ∅`));
+  if (depsMissing.length) return { id: 'regen', stage: 'preflight', status: 'incomplete', inputs, lines, code: 'REGEN_DEPS_MISSING', detail: `dependencies missing; ${depsMissing[0]!.fix} (${depsMissing.length} entr${depsMissing.length === 1 ? 'y' : 'ies'} unverified: ${depsMissing.map(d => d.id).join(', ')})`, fix: depsMissing[0]!.fix };
   if (failed.length) return { id: 'regen', stage: 'preflight', status: 'incomplete', inputs, lines, code: 'REGEN_COMMAND_FAILED', detail: `${failed.length} regen command(s) failed: ${failed.map(f => f.id).join(', ')}`, fix: failed.map(f => f.fix).join('; ') };
   if (stale.length) return { id: 'regen', stage: 'preflight', status: 'fail', inputs, lines, code: 'REGEN_STALE', detail: `${stale.length} stale: ${stale.flatMap(s => s.changed.concat(s.outside)).join(' ')}`, fix: stale.map(s => s.fix).join('; ') };
   return { id: 'regen', stage: 'preflight', status: 'pass', inputs, lines, detail: `${results.length} entr${results.length === 1 ? 'y' : 'ies'} fresh${results.some(r => r.status === 'listed') ? ' (hand-regenerated outputs listed)' : ''}` };

lib/regen.ts

@@ -156,7 +156,7 @@ export function scratchWorktree(repoRoot: string, prefix = 'gstack-regen-'): Scr
 
 export interface EntryResult {
   id: string; command: string | null;
-  status: 'fresh' | 'stale' | 'failed' | 'listed' | 'written' | 'skipped';
+  status: 'fresh' | 'stale' | 'failed' | 'listed' | 'written' | 'skipped' | 'deps-missing';
   /** Output files whose bytes changed (stale) or were written. */
   changed: string[];
   /** Files the command wrote outside its declared outputs (a refusal in `check`). */
@@ -189,6 +189,20 @@ function diffSnapshots(a: Map<string, string>, b: Map<string, string>): string[]
   return [...changed].filter(p => p !== 'node_modules').sort();
 }
 
+/**
+ * The install command for a repository whose package.json declares
+ * dependencies but has no node_modules (the scratch worktree links none
+ * then), picked from its lockfile; null when nothing is missing.
+ */
+export function missingDependencies(repoRoot: string): string | null {
+  if (fs.existsSync(path.join(repoRoot, 'node_modules'))) return null;
+  let pkg: { dependencies?: Record<string, unknown>; devDependencies?: Record<string, unknown> };
+  try { pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) ?? {}; } catch { return null; }
+  if (!Object.keys(pkg.dependencies ?? {}).length && !Object.keys(pkg.devDependencies ?? {}).length) return null;
+  const lockfiles: Array<[string, string]> = [['bun.lock', 'bun install'], ['bun.lockb', 'bun install'], ['pnpm-lock.yaml', 'pnpm install'], ['yarn.lock', 'yarn install'], ['package-lock.json', 'npm install']];
+  return lockfiles.find(([file]) => fs.existsSync(path.join(repoRoot, file)))?.[1] ?? 'bun install';
+}
+
 function runCommand(cwd: string, command: string, env: NodeJS.ProcessEnv, timeoutMs: number): { exit: number | null; stderr: string } {
   const r = runBashSync(`set -o pipefail; ${command}`, { cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, env: { ...env, GSTACK_REGEN_SCRATCH: cwd } });
   return { exit: r.status, stderr: ((r.stderr ?? '') + (r.error ? `\n${r.error.message}` : '')).trim().slice(-4000) };
@@ -207,7 +221,9 @@ export interface RunRegenOptions {
  * `check`: run every selected command in one scratch worktree and compare its
  * outputs with the working tree; `write`: run them in the repository. An
  * entry with `command: null` is `listed` (its fix line names the outputs an
- * author refreshes by hand). Never runs a command the caller did not opt into:
+ * author refreshes by hand). A `check` whose outputs differ while the
+ * repository's dependencies are not installed is `deps-missing`, not `stale`:
+ * the generator may have run without them. Never runs a command the caller did not opt into:
  * the bin enforces --allow-repo-commands before calling this.
  */
 export function runRegen(o: RunRegenOptions): { results: EntryResult[]; wtree: string | null } {
@@ -215,6 +231,7 @@ export function runRegen(o: RunRegenOptions): { results: EntryResult[]; wtree: s
   const timeout = o.timeoutMs ?? 600_000;
   const results: EntryResult[] = [];
   let scratch: Scratch | null = null;
+  const install = o.mode === 'check' ? missingDependencies(o.repoRoot) : null;
   const fixFor = (e: RegenEntry) => e.command ? `${e.command}  # then commit ${e.outputs.join(' ')}` : `regenerate by hand: ${e.outputs.join(' ')}${e.note ? ` (${e.note})` : ''}`;
   try {
     if (o.mode === 'check' && entries.some(e => e.command)) scratch = scratchWorktree(o.repoRoot);
@@ -230,7 +247,9 @@ export function runRegen(o: RunRegenOptions): { results: EntryResult[]; wtree: s
       const ms = Date.now() - started;
       if (run.exit !== 0) { results.push({ id: e.id, command: e.command, status: 'failed', changed, outside, exit: run.exit, stderr: run.stderr, ms, fix: fixFor(e) }); continue; }
       if (o.mode === 'check') {
-        results.push({ id: e.id, command: e.command, status: changed.length || outside.length ? 'stale' : 'fresh', changed, outside, exit: 0, ms, fix: fixFor(e) });
+        const differs = changed.length > 0 || outside.length > 0;
+        if (differs && install) results.push({ id: e.id, command: e.command, status: 'deps-missing', changed, outside, exit: 0, ms, fix: `run ${install}, then rerun the check` });
+        else results.push({ id: e.id, command: e.command, status: differs ? 'stale' : 'fresh', changed, outside, exit: 0, ms, fix: fixFor(e) });
         // Reset the scratch so the next entry's diff is its own.
         git(cwd, ['checkout', '-q', '--', '.']); git(cwd, ['clean', '-fdq']);
       } else results.push({ id: e.id, command: e.command, status: changed.length ? 'written' : 'fresh', changed, outside, exit: 0, ms, fix: fixFor(e) });
@@ -247,6 +266,7 @@ export function renderEntry(r: EntryResult): string {
   if (r.status === 'fresh' || r.status === 'skipped') return head;
   if (r.status === 'listed') return `${head} — ${r.fix}`;
   if (r.status === 'failed') return `${head} — exit ${r.exit}: ${(r.stderr ?? '').split('\n').pop() ?? ''}; fix: run \`${r.command}\` and read its output (REGEN_COMMAND_FAILED)`;
+  if (r.status === 'deps-missing') return `${head} — dependencies missing (no node_modules); ${r.fix} — differs without them: ${[...r.changed, ...r.outside].join(' ')} (REGEN_DEPS_MISSING)`;
   const parts = [head];
   if (r.changed.length) parts.push(`stale: ${r.changed.join(' ')}`);
   if (r.outside.length) parts.push(`outside declared outputs: ${r.outside.join(' ')}`);

lib/result-codes-release.ts

@@ -1,6 +1,7 @@
 /**
  * Result codes for the release path: gstack-ship-queue and the ship-policy
- * floor, pregate timing and its working-tree fingerprint, approval classes and
+ * floor, pregate timing and its working-tree fingerprint, regen with missing
+ * dependencies, approval classes and
  * the state-machine matrix. Kept beside lib/result-codes.ts (which spreads
  * this table into RESULT_CODES) so
  * the owner module stays within the module-size ratchet; the same rules apply:
@@ -83,4 +84,10 @@ export const RELEASE_RESULT_CODES = {
     summary: 'cannot fingerprint the working tree: bin/gstack-wtree could not start (on Windows, no Git Bash was found) or it ran and failed',
     fix: 'on Windows point GSTACK_GIT_BASH at Git Bash\'s bash.exe (Git Bash: export GSTACK_GIT_BASH=\'C:/Program Files/Git/bin/bash.exe\'; PowerShell: $env:GSTACK_GIT_BASH = \'C:\\Program Files\\Git\\bin\\bash.exe\'), or install Git for Windows (winget install --id Git.Git -e); elsewhere rerun ./setup so bin/gstack-wtree is present; then rerun gstack-pregate',
   },
+  // Fix wave W5 (GSTA-31): pregate regen without installed dependencies.
+  REGEN_DEPS_MISSING: {
+    anchor: 'regen-deps-missing',
+    summary: 'a regen command exited 0 with different outputs while package.json declares dependencies and node_modules is missing, so the outputs were not verified',
+    fix: 'install the dependencies (the printed command, such as bun install), then rerun the check',
+  },
 } as const satisfies Record<string, ResultCode>;