Prevent GSD from leaking internal planning related details such as Phase, PRD, D-01, etc in code comments

[Niraj-Kamdar]

I have repeatedly noticed that GSD leaks planning related details in the code comments so I am building a hook script for claude code that catches these leaks before comitting

#!/bin/bash
# Block `git commit` (incl. --amend) when the staged diff or commit message
# leaks GSD planning internals into committed source.
#
# Triggers: PreToolUse on Bash. Filtered by settings.json `if` to git commit*.
#
# Patterns matched: D-NN ids, PRD references, §section refs, "Phase NN",
# "plan NN implements", and any path starting with .planning/

set -u

INPUT=$(cat)
CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""')

# Defensive: only act on git commit invocations
if ! printf '%s' "$CMD" | grep -qE '(^|[[:space:]]|;|&&|\|\|)git[[:space:]]+commit\b'; then
  exit 0
fi

# Find the repo. The cwd may be elsewhere; extract from cd in pipeline if present.
WORK_DIR=$(printf '%s' "$INPUT" | jq -r '.cwd // ""')
if [ -z "$WORK_DIR" ] || [ "$WORK_DIR" = "null" ]; then
  WORK_DIR=$(pwd)
fi

# Allow override "cd /path && git commit ..." by extracting the cd target
CD_TARGET=$(printf '%s' "$CMD" | sed -nE 's/.*cd[[:space:]]+"?([^"&|;[:space:]]+)"?[[:space:]]*&&.*/\1/p' | head -1)
if [ -n "$CD_TARGET" ] && [ -d "$CD_TARGET" ]; then
  WORK_DIR="$CD_TARGET"
fi

cd "$WORK_DIR" 2>/dev/null || exit 0

# Skip if not inside a git repo (avoids false positives)
git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0

PATTERN='D-[0-9]+|PRD\b|§[0-9]|Phase [0-9]+|plan [0-9]+ implements|\.planning/'

# Scan staged diff for added lines only (lines starting with +)
DIFF_LEAKS=$(git diff --cached --no-color 2>/dev/null \
  | grep -nE "^\+" \
  | grep -vE "^\+\+\+" \
  | grep -nE "$PATTERN" \
  | head -30 || true)

# Scan inline commit message for leaks (`git commit -m "..."`)
MSG_LEAKS=$(printf '%s' "$CMD" \
  | grep -oE -- '-m[[:space:]]+("[^"]*"|'"'"'[^'"'"']*'"'"')' \
  | grep -nE "$PATTERN" \
  | head -10 || true)

if [ -z "$DIFF_LEAKS" ] && [ -z "$MSG_LEAKS" ]; then
  exit 0
fi

REASON="Blocked: this commit would leak GSDplanning internals into source/history."
[ -n "$DIFF_LEAKS" ] && REASON="$REASON

Staged diff hits:
$DIFF_LEAKS"
[ -n "$MSG_LEAKS" ] && REASON="$REASON

Commit message hits:
$MSG_LEAKS"
REASON="$REASON

Forbidden tokens: D-NN, PRD, PRD §X.Y, Phase NN, 'plan NN implements', .planning/
Rephrase to self-contained language, then re-stage and retry. Traceability belongs in .planning/phases/<N>/<N>-requirements-coverage.md, not in source."

jq -nc --arg reason "$REASON" '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason: $reason
  }
}'
exit 0

Maybe something like this should be part of the gsd meta flow.

[trek-e]

Good timing on this — GSD already ships a gsd-prompt-guard.js hook (hooks/gsd-prompt-guard.js) that scans writes to .planning/ files for prompt injection patterns. Your idea extends that concept in the other direction: scanning outbound commits for planning internals leaking into source.

A few observations on your script:

• The pattern set (D-NN ids, §section refs, .planning/ paths) is solid for the obvious cases
• The git commit --amend coverage via grep -qE on the CMD is good defensive coverage

If you want this in the official distribution, the right path is a Feature Request issue with the spec — specifically: which patterns, what should trigger a block vs. a warning, and whether it should be opt-in (like workflow_guard) or default-on. The hook would live in hooks/ alongside the existing guards.

If you want to share the working version of your script for others to use in the meantime, posting it here or in a Gist would be useful to the community.

[Niraj-Kamdar]

Sure, I am currently benchmarking and observing if this hook works as expected and once ready I will open a PR.

[trek-e]

@Niraj-Kamdar — the path here is: Feature Request issue first, then PR. /gsd-* hooks ship with the distribution, so a new commit-guard hook needs a spec approved before code is written — same process as any other feature.

To get the hook into the distribution, please open a Feature Request issue with:

• Which patterns trigger a block vs. a warning
• Whether it should be opt-in (like workflow_guard) or default-on
• Which runtimes it should support (Claude Code only, or Gemini/Codex too)

Once approved, a PR from the feature branch is the right next step. Posting your working script here in the meantime is welcome — it helps the community and gives us a concrete implementation to reference in the spec.

[trek-e]

@Niraj-Kamdar — sounds good. One clarification on the process: an issue needs to be filed before the PR, not after. The hook needs a spec approved first so the scope is clear before code is written.

When your benchmarking is done, open a Feature Request issue first with:

• The final pattern list (block vs. warning)
• Whether it should be opt-in or default-on
• Runtime support scope (Claude Code only, or Gemini/Codex too)

Once the spec is approved, the PR from a feature branch is the right next step. That way the implementation has a clear target.