chore(sync): release-workflow-guard dry-run bypass + naming rule

Mirrors socket-repo-template@bc292e1.

The release-workflow-guard hook now allows dispatches that pass
-f dry-run=true when the target workflow declares a dry-run input
in its workflow_dispatch.inputs block. Cross-repo dispatches
(--repo flag pointing at a different project) still block.

CLAUDE.md picks up the kebab-case "Workflow input naming" rule
formalizing the fleet convention.

Author: jdalton

.claude/hooks/release-workflow-guard/index.mts

@@ -11,11 +11,11 @@
 //   - Container workflows push immutable image tags.
 //
 // Even nominally-CI workflow_dispatches often carry prod side
-// effects (the socket-btm binary builders gate prod releases on a
-// `dry_run` input, but the dispatch itself is the trigger). The
-// safe default is "block all dispatches and ask the user to run
-// them themselves." Cost of an extra block: one re-prompt. Cost
-// of a missed prod publish: irreversible.
+// effects — the dispatch itself is the trigger that runs the
+// release pipeline, even when an input gates the destructive step.
+// Default policy: block all dispatches and ask the user to run them
+// themselves. Cost of an extra block: one re-prompt. Cost of a
+// missed prod publish: irreversible.
 //
 // Exit code 2 with a clear stderr message stops the tool call. The
 // model never gets to fire the command. The user re-runs it from
@@ -26,6 +26,25 @@
 //   - `gh workflow dispatch <id>` (alias of `run`)
 //   - `gh api ... actions/workflows/<id>/dispatches` POST/PUT
 //
+// Bypass — verifiable dry-run only:
+//   - Pass `-f dry-run=true` (or =1/=yes) explicitly.
+//   - The workflow YAML must declare a `dry-run:` input under its
+//     `workflow_dispatch.inputs` block (we read the file from
+//     $CLAUDE_PROJECT_DIR/.github/workflows/<name>.yml). If the
+//     workflow doesn't have the input, the gh CLI silently accepts
+//     the flag but the workflow ignores it — that's the unsafe
+//     case the verification step prevents.
+//   - No force-prod overrides may be set: `-f release=true`,
+//     `-f publish=true`, `-f prod=true`, `-f production=true`.
+//   - Bypass applies only to `gh workflow run|dispatch`. The
+//     `gh api .../dispatches` shape takes inputs as a JSON body,
+//     which is harder to verify safely; route those through the user.
+//
+// The hook recognizes only kebab-case `dry-run` as the input name —
+// see CLAUDE.md "Workflow input naming" for the rule. If a workflow
+// declares `dry_run` (snake) or any other shape, the verification
+// fails and the bypass doesn't apply. Fix the workflow.
+//
 // This hook is the enforcement layer paired with the CLAUDE.md
 // rule. The rule documents the policy; the hook makes it
 // mechanical so the model can't accidentally dispatch a workflow
@@ -34,7 +53,8 @@
 // Reads a Claude Code PreToolUse JSON payload from stdin:
 //   { "tool_name": "Bash", "tool_input": { "command": "..." } }
 
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
 import process from 'node:process'
 
 type ToolInput = {
@@ -55,6 +75,35 @@ const GH_WORKFLOW_DISPATCH_RE =
 const GH_API_WORKFLOW_DISPATCH_RE =
   /\bgh\s+api\b[^|]*?\/actions\/workflows\/([^/\s]+)\/dispatches\b/g
 
+// Dry-run input detection. The fleet standardized on `dry-run`
+// (kebab-case) — see socket-registry's shared actions and every
+// `*.yml` workflow that takes a dispatch input. Match values
+// "true"/"1"/"yes" as truthy and "false"/"0"/"no" as falsy. Quote-
+// mask handling lives in detectDispatch; these regexes scan the
+// same masked range as the dispatch detector.
+const DRY_RUN_TRUE_RE = /-f\s+dry-run\s*=\s*['"]?(?:true|1|yes)['"]?/i
+const DRY_RUN_FALSE_RE = /-f\s+dry-run\s*=\s*['"]?(?:false|0|no)['"]?/i
+
+// Inputs that flip a workflow back into "do the prod thing." Even
+// with dry-run=true, if any of these are explicitly set the dispatch
+// is no longer benign — block. Order matters: this runs after
+// dry-run detection, so an explicit publish=true overrides.
+const FORCE_PROD_INPUTS_RE =
+  /-f\s+(?:release|publish|prod|production)\s*=\s*['"]?(?:true|1|yes)['"]?/i
+
+// Workflow YAML input declaration. Match the canonical
+// `dry-run:` line under `inputs:` — used to verify a workflow
+// actually accepts a dry-run override before allowing a dispatch
+// that claims to use it. Tolerates leading whitespace (any
+// indentation) since YAML nesting depth varies by file.
+const WORKFLOW_DRY_RUN_INPUT_RE = /^\s+dry-run:\s*$/m
+
+// `--repo <owner>/<name>` parser. Captures the repo name (after the
+// slash). Used to gate the dry-run bypass: a dispatch targeting a
+// repo other than the current $CLAUDE_PROJECT_DIR can't be verified
+// from disk, so we conservatively block it.
+const GH_REPO_FLAG_RE = /\s--repo\s+\S*?\/([^\s/]+)/
+
 // Walk the command and return a per-position boolean: true means the
 // char at index i sits inside a single- or double-quoted string. We
 // use this to skip matches that fall inside `git commit -m "..."`
@@ -105,11 +154,88 @@ function buildQuoteMask(s: string): boolean[] {
   return mask
 }
 
-function detectDispatch(command: string): {
+type DispatchResult = {
   blocked: boolean
   workflow?: string
   shape?: string
-} {
+  // When `blocked` is false, populated with the reason the dispatch
+  // was allowed through. Surfaced in the hook's "allowed" log line so
+  // the user can see exactly why the guard let it pass.
+  allowedReason?: string
+}
+
+// Resolve the workflow file path and verify it actually declares a
+// `dry-run` input. The path is resolved relative to
+// `$CLAUDE_PROJECT_DIR/.github/workflows/<workflow>` since the hook
+// runs from arbitrary cwds; falls back to ".github/workflows/<wf>"
+// when the env var is unset (e.g. the hook invoked outside Claude
+// Code). The check is intentionally permissive: any unparseable
+// workflow file is treated as "no dry-run input" (block-the-default).
+function workflowDeclaresDryRunInput(workflow: string): boolean {
+  // Workflow arg can be "id.yml", "name.yaml", a numeric ID, or a path.
+  // Numeric IDs and paths-without-extension can't be resolved without
+  // hitting GitHub's API — for those, conservatively return false.
+  if (!/\.(?:yml|yaml)$/i.test(workflow)) {
+    return false
+  }
+  const projectDir = process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd()
+  // Strip any leading directory prefix the user passed (e.g. they
+  // typed the path explicitly). The bare filename is what
+  // .github/workflows/ holds.
+  const filename = path.basename(workflow)
+  const fullPath = path.join(projectDir, '.github', 'workflows', filename)
+  if (!existsSync(fullPath)) {
+    return false
+  }
+  try {
+    const yaml = readFileSync(fullPath, 'utf8')
+    return WORKFLOW_DRY_RUN_INPUT_RE.test(yaml)
+  } catch {
+    return false
+  }
+}
+
+// Decide whether a dispatch on `workflow` should be allowed because
+// it's a verifiable dry-run. All five conditions must hold:
+//   1. `-f dry-run=true|1|yes` is explicitly present in the command
+//   2. `-f dry-run=false|0|no` is NOT present (user didn't override)
+//   3. No force-prod input is present (release/publish/prod=true)
+//   4. If `--repo <owner>/<name>` is present, the repo basename
+//      matches the current $CLAUDE_PROJECT_DIR's basename. Verifying
+//      a workflow file in a different repo would require scanning
+//      sibling clones — too brittle. A cross-repo dispatch goes
+//      through the user.
+//   5. The workflow YAML actually declares a `dry-run:` input under
+//      its `workflow_dispatch.inputs` block — without that, the gh
+//      CLI silently accepts the flag but the workflow ignores it.
+function isVerifiableDryRun(
+  command: string,
+  workflow: string | undefined,
+): boolean {
+  if (!workflow) {
+    return false
+  }
+  if (!DRY_RUN_TRUE_RE.test(command)) {
+    return false
+  }
+  if (DRY_RUN_FALSE_RE.test(command)) {
+    return false
+  }
+  if (FORCE_PROD_INPUTS_RE.test(command)) {
+    return false
+  }
+  const repoMatch = GH_REPO_FLAG_RE.exec(command)
+  if (repoMatch) {
+    const projectDir = process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd()
+    const projectName = path.basename(projectDir)
+    if (repoMatch[1] !== projectName) {
+      return false
+    }
+  }
+  return workflowDeclaresDryRunInput(workflow)
+}
+
+function detectDispatch(command: string): DispatchResult {
   // We can't `replace(/\s+/g, ' ')` first because that would offset
   // the quote mask from the original string. Match against the raw
   // command and use the mask to filter false-positives.
@@ -126,16 +252,28 @@ function detectDispatch(command: string): {
   let cliMatch: RegExpExecArray | null
   while ((cliMatch = GH_WORKFLOW_DISPATCH_RE.exec(command))) {
     if (!mask[cliMatch.index]) {
+      const workflow = cliMatch[2]
+      if (isVerifiableDryRun(command, workflow)) {
+        return {
+          blocked: false,
+          workflow,
+          shape: 'gh workflow run/dispatch',
+          allowedReason:
+            'verifiable dry-run (-f dry-run=true + workflow declares dry-run input)',
+        }
+      }
       return {
         blocked: true,
-        workflow: cliMatch[2],
+        workflow,
         shape: 'gh workflow run/dispatch',
       }
     }
   }
 
   // Same /g-flag reset rationale as above — keep the regex stateless
-  // across calls.
+  // across calls. The dry-run bypass intentionally doesn't apply to
+  // `gh api .../dispatches` — that path takes inputs as a JSON body,
+  // which is harder to verify safely; route those through the user.
   GH_API_WORKFLOW_DISPATCH_RE.lastIndex = 0
   let apiMatch: RegExpExecArray | null
   while ((apiMatch = GH_API_WORKFLOW_DISPATCH_RE.exec(command))) {
@@ -174,8 +312,16 @@ function main(): void {
     return
   }
 
-  const { blocked, workflow, shape } = detectDispatch(command)
+  const { blocked, workflow, shape, allowedReason } = detectDispatch(command)
   if (!blocked) {
+    if (allowedReason) {
+      // Transparently log the bypass so the user sees why the guard
+      // let it through. Stderr only — no exit-code change, hook
+      // behaves as if it never fired.
+      process.stderr.write(
+        `[release-workflow-guard] ALLOWED: ${shape} on ${workflow ?? '<unknown>'} — ${allowedReason}\n`,
+      )
+    }
     return
   }
 
@@ -187,16 +333,17 @@ function main(): void {
     '    - Publish workflows push npm versions (unpublishable after 24h).',
     '    - Build/Release workflows create GitHub releases pinned by SHA.',
     '    - Container workflows push immutable image tags.',
-    "    - Even build workflows with a 'dry_run' input still treat the",
-    '      dispatch itself as the prod trigger.',
     '',
-    '  The user runs workflow_dispatch jobs manually — never Claude.',
-    '  Tell the user to run the command in their own terminal (or',
-    '  via the GitHub Actions UI), then resume.',
+    '  Allowed bypass — verifiable dry-run:',
+    '    - Pass `-f dry-run=true` explicitly, AND',
+    '    - The workflow YAML must declare a `dry-run:` input under',
+    '      its workflow_dispatch.inputs block.',
+    '    - No force-prod overrides may be set',
+    '      (e.g. -f release=true / -f publish=true).',
     '',
-    '  This hook has no opt-out. If you genuinely need to run a',
-    '  benign dispatch (e.g. a debug-only utility workflow), ask',
-    "  the user to invoke it themselves; don't seek a bypass here.",
+    '  Without that bypass, the user runs workflow_dispatch jobs',
+    '  manually. Tell the user to run the command in their own',
+    '  terminal (or via the GitHub Actions UI), then resume.',
   ]
   process.stderr.write(lines.join('\n') + '\n')
   process.exitCode = 2