gsd-cc 1.2.0 → 1.3.0

package/bin/install.js

@@ -155,9 +155,77 @@ function install(isGlobal) {
     fs.chmodSync(autoLoop, 0o755);
   }
 
+  // 5. Install hooks
+  const hooksSrc = path.join(__dirname, '..', 'hooks');
+  const hooksDest = path.join(skillsBase, 'gsd-cc-shared', 'hooks');
+  if (fs.existsSync(hooksSrc)) {
+    copyDir(hooksSrc, hooksDest);
+    // Make hooks executable
+    const hookFiles = fs.readdirSync(hooksDest);
+    for (const f of hookFiles) {
+      fs.chmodSync(path.join(hooksDest, f), 0o755);
+    }
+    fileCount += hookFiles.length;
+  }
+
+  // 6. Configure hooks in settings.json
+  installHooks(isGlobal, hooksDest);
+
   console.log(`  ${green}✓${reset} Installed ${fileCount} files to ${label}`);
 }
 
+/**
+ * Install hooks into .claude/settings.json or .claude/settings.local.json
+ */
+function installHooks(isGlobal, hooksDir) {
+  const settingsPath = isGlobal
+    ? path.join(os.homedir(), '.claude', 'settings.json')
+    : path.join(process.cwd(), '.claude', 'settings.local.json');
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    } catch (e) {
+      settings = {};
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const boundaryGuard = path.join(hooksDir, 'gsd-boundary-guard.sh');
+  const contextMonitor = path.join(hooksDir, 'gsd-context-monitor.sh');
+  const workflowGuard = path.join(hooksDir, 'gsd-workflow-guard.sh');
+
+  // PreToolUse: boundary guard on Edit/Write
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+  // Remove existing GSD-CC hooks before adding (idempotent)
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+    h => !JSON.stringify(h).includes('gsd-boundary-guard')
+  );
+  settings.hooks.PreToolUse.push({
+    matcher: 'Edit|Write',
+    hooks: [{ type: 'command', command: boundaryGuard, timeout: 5000 }]
+  });
+
+  // PostToolUse: context monitor + workflow guard
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
+    h => !JSON.stringify(h).includes('gsd-context-monitor') && !JSON.stringify(h).includes('gsd-workflow-guard')
+  );
+  settings.hooks.PostToolUse.push({
+    hooks: [{ type: 'command', command: contextMonitor, timeout: 5000 }]
+  });
+  settings.hooks.PostToolUse.push({
+    matcher: 'Edit|Write',
+    hooks: [{ type: 'command', command: workflowGuard, timeout: 5000 }]
+  });
+
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`  ${green}✓${reset} Hooks configured in ${settingsPath.replace(os.homedir(), '~').replace(process.cwd(), '.')}`);
+}
+
 /**
  * Write language to CLAUDE.md
  */
@@ -254,9 +322,32 @@ function uninstall() {
     }
   }
 
+  // Clean up hooks from settings files
+  for (const isGlobal of [true, false]) {
+    const settingsPath = isGlobal
+      ? path.join(os.homedir(), '.claude', 'settings.json')
+      : path.join(process.cwd(), '.claude', 'settings.local.json');
+    if (fs.existsSync(settingsPath)) {
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        if (settings.hooks) {
+          for (const event of Object.keys(settings.hooks)) {
+            settings.hooks[event] = settings.hooks[event].filter(
+              h => !JSON.stringify(h).includes('gsd-')
+            );
+            if (settings.hooks[event].length === 0) delete settings.hooks[event];
+          }
+          if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+          fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        }
+      } catch (e) { /* ignore parse errors */ }
+    }
+  }
+
   if (!removed) {
     console.log(`  ${yellow}No GSD-CC installation found.${reset}`);
   } else {
+    console.log(`  ${green}✓${reset} Hooks removed from settings`);
     console.log(`\n  ${green}Done.${reset} GSD-CC has been removed.`);
   }
 }

package/hooks/gsd-boundary-guard.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# GSD-CC Boundary Guard — PreToolUse hook
+# Blocks Write/Edit operations on files listed in .gsd/STATE.md boundaries.
+# This is a HARD enforcement — Claude cannot bypass this regardless of prompting.
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
+CWD=$(echo "$INPUT" | jq -r '.cwd')
+
+# Only check Edit and Write operations
+if [ "$TOOL_NAME" != "Edit" ] && [ "$TOOL_NAME" != "Write" ]; then
+  exit 0
+fi
+
+# Get the file being edited/written
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Check if STATE.md exists and has boundaries
+STATE_FILE="$CWD/.gsd/STATE.md"
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+# Extract boundary files from STATE.md
+# Boundaries section contains lines like: - path/to/file (reason)
+BOUNDARIES=$(sed -n '/^## Boundaries Active/,/^##/p' "$STATE_FILE" | grep '^ *- ' | sed 's/^ *- //' | sed 's/ (.*//')
+
+if [ -z "$BOUNDARIES" ]; then
+  exit 0
+fi
+
+# Normalize the target file path (make relative to CWD if absolute)
+RELATIVE_PATH="$FILE_PATH"
+if [[ "$FILE_PATH" == "$CWD"* ]]; then
+  RELATIVE_PATH="${FILE_PATH#$CWD/}"
+fi
+
+# Check each boundary file
+while IFS= read -r BOUNDARY_FILE; do
+  BOUNDARY_FILE=$(echo "$BOUNDARY_FILE" | xargs) # trim whitespace
+  if [ -z "$BOUNDARY_FILE" ]; then
+    continue
+  fi
+
+  # Check exact match or path containment
+  if [ "$RELATIVE_PATH" = "$BOUNDARY_FILE" ] || [ "$FILE_PATH" = "$BOUNDARY_FILE" ]; then
+    jq -n --arg file "$BOUNDARY_FILE" '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": ("BOUNDARY VIOLATION: " + $file + " is in the DO NOT CHANGE list for this task. This file is protected. If you need to modify it, stop and discuss with the user first.")
+      }
+    }'
+    exit 0
+  fi
+done <<< "$BOUNDARIES"
+
+# File not in boundaries — allow
+exit 0

package/hooks/gsd-context-monitor.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# GSD-CC Context Monitor — PostToolUse hook
+# Injects warnings when context usage is getting high.
+# Uses the transcript file size as a proxy for context consumption.
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd')
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+
+# Skip if no transcript path
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+  exit 0
+fi
+
+# Check if we're in a GSD-CC project
+if [ ! -d "$CWD/.gsd" ]; then
+  exit 0
+fi
+
+# Use transcript line count as context proxy
+# Typical context window: ~200K tokens ≈ ~2000 transcript lines for a heavy session
+LINE_COUNT=$(wc -l < "$TRANSCRIPT" | xargs)
+
+# Debounce: only warn every 20 tool calls
+DEBOUNCE_FILE="/tmp/gsd-cc-ctx-monitor-$$"
+if [ -f "$DEBOUNCE_FILE" ]; then
+  LAST_WARN=$(cat "$DEBOUNCE_FILE")
+  DIFF=$((LINE_COUNT - LAST_WARN))
+  if [ "$DIFF" -lt 50 ]; then
+    exit 0
+  fi
+fi
+
+# Warning thresholds (based on transcript lines)
+if [ "$LINE_COUNT" -gt 1500 ]; then
+  echo "$LINE_COUNT" > "$DEBOUNCE_FILE"
+  jq -n '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "⚠️ CRITICAL: Context window is very full. You MUST wrap up the current task immediately, write the summary, and instruct the user to start a fresh session. Do NOT start new work."
+    }
+  }'
+  exit 0
+elif [ "$LINE_COUNT" -gt 1000 ]; then
+  echo "$LINE_COUNT" > "$DEBOUNCE_FILE"
+  jq -n '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "⚠️ WARNING: Context window is filling up. Finish the current task soon and prepare to hand off to a fresh session."
+    }
+  }'
+  exit 0
+fi
+
+exit 0

package/hooks/gsd-workflow-guard.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# GSD-CC Workflow Guard — PostToolUse hook
+# Nudges Claude back into the GSD-CC flow when it drifts.
+# Advisory only — does not block operations.
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
+CWD=$(echo "$INPUT" | jq -r '.cwd')
+
+# Only check Edit and Write on source files (not .gsd/ files)
+if [ "$TOOL_NAME" != "Edit" ] && [ "$TOOL_NAME" != "Write" ]; then
+  exit 0
+fi
+
+# Skip if not a GSD-CC project
+STATE_FILE="$CWD/.gsd/STATE.md"
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Allow writes to .gsd/ directory (that's the workflow itself)
+if [[ "$FILE_PATH" == *".gsd/"* ]] || [[ "$FILE_PATH" == *".claude/"* ]]; then
+  exit 0
+fi
+
+# Check if we're in an active execution phase
+PHASE=$(grep '^phase:' "$STATE_FILE" | head -1 | sed 's/phase: *//')
+
+case "$PHASE" in
+  "seed"|"seed-complete"|"stack-complete"|"roadmap-complete"|"plan-complete"|"discuss-complete")
+    # Not in execution — source file edits are unexpected
+    jq -n --arg phase "$PHASE" --arg file "$FILE_PATH" '{
+      "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": ("Note: You edited " + $file + " but the current GSD-CC phase is \"" + $phase + "\" which is a planning phase, not execution. Source file changes should happen during the apply phase. If this was intentional, carry on. If not, consider running /gsd-cc to check the current state.")
+      }
+    }'
+    exit 0
+    ;;
+  "applying")
+    # In execution — this is expected
+    exit 0
+    ;;
+  *)
+    exit 0
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-cc",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Get Shit Done on Claude Code — structured AI development with your Max plan",
   "author": "Philipp Briese (https://github.com/0ui-labs)",
   "homepage": "https://github.com/0ui-labs/GSD-CC#readme",

package/skills/gsd/discuss/SKILL.md

@@ -156,25 +156,31 @@ When running in full-auto mode (`auto_mode_scope: milestone`), Discuss is NOT sk
 
 ### How it works
 
-1. Read `.gsd/PROFILE.md` — this is the user's decision-making profile
-2. For each gray area, simulate a discussion:
-   - **You (Planner):** Ask the question as you would ask the user
-   - **Synthetic Stakeholder (Profile):** Answer based on PROFILE.md — using their instincts, preferences, strong opinions, and red lines
-   - The stakeholder MUST cite which part of the profile drives the decision
-3. Write the results to `.gsd/S{nn}-DISCUSS-AUTO.md` with full transparency:
+1. Read `.gsd/PROFILE.md` — this is the user's decision-making profile (if it exists)
+2. For each gray area, simulate a real discussion between two roles:
+   - **Planner:** Analyzes the technical options. Brings expertise about what works best for THIS project. Considers tradeoffs, risks, maintainability, project requirements.
+   - **Stakeholder:** Represents the user's perspective. Influenced by PROFILE.md but not controlled by it. The profile is a **nudge, not a mandate** — it shapes preferences but doesn't override what's technically best for this project.
+3. The discussion should feel like a real debate, not a rubber stamp:
+   - Planner proposes with reasoning
+   - Stakeholder reacts based on profile + common sense
+   - If they disagree, they work it out with arguments
+   - The final decision considers BOTH technical merit AND user preferences
+4. Write the results to `.gsd/S{nn}-DISCUSS-AUTO.md` with full transparency:
 
 ```markdown
-# S{nn} Auto-Discuss — Synthetic Stakeholder Decisions
+# S{nn} Auto-Discuss
 
-> These decisions were made by auto-mode using your decision profile.
-> Review after UNIFY. Update your profile with /gsd-cc-profile if
-> any decision doesn't match how you'd actually decide.
+> These decisions were made by auto-mode.
+> The user's profile influenced but did not dictate decisions.
+> Review after UNIFY. Update your profile with /gsd-cc-profile if needed.
 
 ## Decision 1: {topic}
 **Question:** {what was ambiguous}
-**Stakeholder says:** {decision with reasoning}
-**Profile basis:** {which section/quote from PROFILE.md}
-**Confidence:** {high|medium|low — how clearly does the profile cover this?}
+**Planner says:** {technical analysis — options, tradeoffs, recommendation}
+**Stakeholder says:** {reaction based on profile + common sense}
+**Profile influence:** {how the profile shaped this — or "N/A" if profile didn't cover this}
+**Final decision:** {what was decided and why}
+**Confidence:** {high|medium|low}
 
 ## Decision 2: {topic}
 ...
@@ -182,17 +188,24 @@ When running in full-auto mode (`auto_mode_scope: milestone`), Discuss is NOT sk
 
 ### Confidence levels
 
-- **High:** The profile explicitly covers this (e.g., profile says "always REST for MVPs" and the question is REST vs GraphQL for an MVP)
-- **Medium:** The profile gives strong hints but doesn't directly address this (e.g., profile says "simplicity over flexibility" and the question is about a specific pattern choice)
-- **Low:** The profile doesn't clearly address this — the stakeholder is guessing. Mark these clearly so the user knows to review them.
+- **High:** Clear technical winner that also aligns with the profile
+- **Medium:** Multiple valid options — profile tipped the balance, or technical choice overrode a mild preference with good reason
+- **Low:** Unclear technically AND the profile doesn't help — the decision is a best guess. Mark for user review.
 
-### Rules for the Synthetic Stakeholder
+### How the Profile Influences (NOT Controls)
 
-- **Stay in character.** Answer as the user would, not as a senior dev or a textbook.
-- **Use their language.** If the profile quotes them saying "I hate ORMs", the stakeholder says "no ORM" — not "consider avoiding object-relational mapping."
-- **Respect red lines.** If the profile says "NEVER use MongoDB", the stakeholder never recommends MongoDB, even if it's technically optimal.
-- **Be honest about uncertainty.** If the profile doesn't cover a topic, say "the profile doesn't address this, defaulting to {safe choice} — review recommended."
-- **Capture wildcards.** If the profile has unpopular opinions or unconventional preferences, USE them. That's the whole point.
+The profile is one input among several. The weight depends on the type of decision:
+
+- **Taste decisions** (UI style, naming conventions, code style) → profile weighs heavily. There's no "right answer", so the user's preference matters most.
+- **Technical decisions** (database choice, API design, auth strategy) → profile is a tiebreaker. If two options are technically equal, pick the one the user would prefer. But don't pick a bad option just because the profile likes it.
+- **Red lines** → always respected. If the profile says "NEVER use X", don't use X. Period. But explain the cost if it matters.
+
+### Rules for Auto-Discuss
+
+- **The Planner thinks independently.** Don't just ask "what would the user want?" — first figure out what's technically best, THEN check if the profile agrees.
+- **Disagreements are good.** If the planner thinks X is better but the profile nudges toward Y, document the tension. Don't hide it.
+- **Use the user's language** when representing their perspective. If they said "I hate ORMs", the stakeholder says "no ORM" — not "consider avoiding object-relational mapping."
+- **Be honest about uncertainty.** If neither technical analysis nor the profile gives a clear answer, say so.
 
 ### If no PROFILE.md exists
 

package/skills/gsd/stack/SKILL.md

@@ -111,27 +111,31 @@ If their reasoning is sound, support it. If it's risky, explain the risk honestl
 
 ### For auto-discuss (synthetic stakeholder):
 
-Read PROFILE.md. The stakeholder discusses each decision:
+Read PROFILE.md (if it exists). For each stack decision, run a real discussion:
 
-```
-## Stack Discussion (Synthetic Stakeholder)
+```markdown
+## Stack Discussion (Auto)
 
 ### Language / Runtime
-Planner: "The project needs {requirement}. I'd suggest {language}
-because {reason}."
-Stakeholder: "{Response based on PROFILE.md — e.g. 'Philipp prefers
-TypeScript for anything with a frontend. He mentioned strict mode is
-worth the overhead.'}"
-Profile basis: §Tech Stack Defaults, §Strong Opinions
-Decision: {final choice}
-Confidence: {high|medium|low}
+**Planner:** "For this project we need {requirement}. The best
+options are {A} and {B}. {A} because {reason}. {B} because {reason}.
+I'd lean toward {A}."
+**Stakeholder:** "{Reaction — agrees, disagrees, or adds context.
+Profile is a nudge, not a script. E.g. 'The profile says TypeScript
+for frontend work, and that aligns here. But even without the profile
+TypeScript would be the right call because of {project-specific reason}.'}"
+**Decision:** {final choice}
+**Reasoning:** {why this is right for THIS project — not just because the profile says so}
+**Confidence:** {high|medium|low}
 
 ### Framework
-Planner: ...
-Stakeholder: ...
+**Planner:** ...
+**Stakeholder:** ...
 ```
 
-**Every decision must be discussed.** Even if the profile clearly says "always use Next.js", the planner should validate that Next.js makes sense for THIS project and the stakeholder should confirm.
+**The profile influences, it doesn't dictate.** The planner should first figure out what's technically best for this specific project, THEN check if the profile agrees. If the profile says "always Next.js" but this project is a CLI tool, don't use Next.js.
+
+**Every decision must be discussed.** Even obvious ones. The discussion creates a record of WHY each choice was made.
 
 ## Step 4: Research When Needed