cc-discipline 2.3.0 → 2.4.0

package/init.sh

@@ -470,7 +470,7 @@ if [ "$INSTALL_MODE" = "fresh" ]; then
     echo -e "Created files:"
     echo -e "  ${GREEN}CLAUDE.md${NC}                    ← Project rules (fill in [TODO] sections)"
     echo -e "  ${GREEN}.claude/rules/${NC}               ← Auto-injected rules"
-    echo -e "  ${GREEN}.claude/hooks/${NC}               ← 6 discipline hooks (edit guard, streak breaker, phase gate, action counter, error remind, session start)"
+    echo -e "  ${GREEN}.claude/hooks/${NC}               ← 7 discipline hooks (edit guard, streak breaker, git guard, phase gate, action counter, error remind, session start)"
     echo -e "  ${GREEN}.claude/agents/${NC}              ← Reviewer & investigator subagents"
     echo -e "  ${GREEN}.claude/skills/commit/${NC}       ← /commit smart commit"
     echo -e "  ${GREEN}.claude/skills/self-check/${NC}   ← /self-check periodic discipline check"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-discipline",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Discipline framework for Claude Code — rules, hooks, and agents that keep AI on track",
   "bin": {
     "cc-discipline": "bin/cli.sh"

package/templates/.claude/hooks/action-counter.sh

@@ -19,9 +19,17 @@ COUNT=$(cat "$COUNT_FILE" 2>/dev/null) || COUNT=0
 COUNT=$((COUNT + 1))
 echo "$COUNT" > "$COUNT_FILE"
 
+# Early-action phase check: first 3 actions get a planning reminder
+if [ "$COUNT" -le 3 ]; then
+    cat <<JSONEOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"PHASE CHECK (action #${COUNT}): Before writing code: (1) Have you completed research/understanding? (2) Has the user approved an approach? If this is a non-trivial task and you haven't planned first, STOP and plan before implementing. Starting code without user approval is a phase violation."}}
+JSONEOF
+    exit 0
+fi
+
 if [ $((COUNT % THRESHOLD)) -eq 0 ]; then
     cat <<JSONEOF
-{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"AUTO SELF-CHECK (#${COUNT} actions): Pause and verify: (1) Am I still serving the user's original request, or have I drifted? (2) Am I fixing the same thing repeatedly (mole-whacking)? (3) Have I claimed anything as 'verified' without actually running it? (4) Am I making changes the user didn't ask for? (5) Have I updated docs/progress.md with current status and completed milestones? If progress.md is stale, update it NOW before continuing. (6) Plan fidelity: if executing a plan, compare what the current step asked for vs what I actually delivered — am I cutting corners or simplifying the intent? Check the acceptance criteria. (7) Friction check: did any hook/rule get in the way or miss something since last check? If so, note it in one line for /retro later. If ANY answer is concerning, STOP and report to the user before continuing."}}
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"AUTO SELF-CHECK (#${COUNT} actions): Pause and verify: (1) Am I still serving the user's original request, or have I drifted? (2) Am I fixing the same thing repeatedly (mole-whacking)? (3) Have I claimed anything as 'verified' without actually running it? (4) Am I making changes the user didn't ask for? (5) Have I updated docs/progress.md with current status and completed milestones? If progress.md is stale, update it NOW before continuing. (6) Plan fidelity: if executing a plan, compare what the current step asked for vs what I actually delivered — am I cutting corners or simplifying the intent? Check the acceptance criteria. (7) Quality check: am I lowering quality to avoid difficulty? If I'm about to skip a verification, simplify an approach, or take a shortcut — STOP and ask the user instead of silently pushing forward. (8) Friction check: did any hook/rule get in the way or miss something since last check? If so, note it in one line for /retro later. If ANY answer is concerning, STOP and report to the user before continuing."}}
 JSONEOF
 fi
 

package/templates/.claude/hooks/post-error-remind.sh

@@ -2,6 +2,11 @@
 # post-error-remind.sh — PostToolUse / PostToolUseFailure hook
 # Detects error patterns in Bash output and reminds Claude to follow debugging discipline
 #
+# NOTE: We use exit 2 intentionally for Post hooks.
+# exit 0 is completely silent — no way to inject text from Post hooks.
+# exit 2 + stderr is the ONLY mechanism to show reminders to Claude after tool execution.
+# The tool has already executed — exit 2 doesn't block execution, it injects the message.
+#
 # Design principles:
 #   - Only match REAL error patterns, not the word "error" in any context
 #   - Skip non-Bash tools (Edit/Write/Read have their own error handling)
@@ -92,7 +97,7 @@ fi
 # --- Emit reminder if error detected ---
 
 if [ "$HAS_ERROR" = true ]; then
-    REMINDER="ERROR DETECTED. Follow debugging discipline: 1. Do NOT modify code immediately 2. Fully understand the error message 3. List possible causes (>=2) 4. Record in docs/debug-log.md 5. Verify hypotheses before fixing"
+    REMINDER="ERROR DETECTED. Follow debugging discipline: 1. Do NOT modify code immediately 2. Fully understand the error message 3. List >=3 possible causes — label them HYPOTHESES, not root cause 4. Record in docs/debug-log.md 5. Eliminate >=2 hypotheses with evidence BEFORE declaring root cause 6. Only then fix. WARNING: Do NOT say 'found the root cause' or 'the issue is' after seeing one error — that kills investigation. Say 'possible cause' until you have elimination evidence."
 
     if [ "$ERROR_TYPE" = "test" ]; then
         REMINDER="$REMINDER. WARNING: Test failure — do NOT change the test to make it pass! First determine if it's a code bug or an outdated test."

package/templates/.claude/hooks/pre-edit-guard.sh

@@ -76,4 +76,11 @@ if [ "$HAS_JQ" = true ]; then
     fi
 fi
 
+# ─── Bug-fix sanity check ───
+# Inject a lightweight reminder on source file edits:
+# "If this is a bug fix, have you eliminated alternative hypotheses?"
+# Uses additionalContext (non-blocking) so it doesn't slow down normal edits.
+cat <<JSONEOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"If this edit is a bug fix: have you listed >=3 possible causes and eliminated >=2 with evidence? If not, you are guessing, not debugging. Say 'possible cause', not 'root cause', until you have elimination evidence."}}
+JSONEOF
 exit 0

package/templates/.claude/hooks/session-start.sh

@@ -38,6 +38,7 @@ Reminders:
 - Before editing: root cause identified? scope respected? change recorded?
 - 3 consecutive failures → stop and report to user
 - Do NOT jump to implementation before user confirms the approach
+- Do NOT assume project state (phase, status, dependencies) — verify by reading files or asking
 EOF
 
 exit 0

package/templates/.claude/rules/00-core-principles.md

@@ -7,6 +7,8 @@ description: "Core working principles — auto-injected before all operations"
 
 1. **Understand before acting** — Before modifying any file, state: what you're changing, why, and the expected impact
 2. **Don't lock onto the first explanation** — After finding a suspected cause, list >=2 alternative hypotheses before acting
-3. **Minimal change principle** — No large-scale refactors or rewrites unless explicitly requested
+3. **Minimal change, minimal complexity** — No large-scale refactors unless explicitly requested. When proposing solutions, prefer the simplest approach that meets requirements. If a lightweight solution exists, do NOT propose a heavyweight one unless the user asks for it.
 4. **3 consecutive failures → forced stop** — Report current state, attempted solutions, and points of confusion; wait for human guidance
 5. **Distinguish trigger from root cause** — The first anomaly you see is often just the trigger, not the root cause
+6. **"Root cause" is a conclusion, not a guess** — You may NOT use the phrase "root cause" or "found the issue" unless you have: (a) listed ≥3 hypotheses, (b) eliminated ≥2 with evidence, (c) have direct proof for the remaining one. Until then, say "possible cause" or "hypothesis". Premature certainty kills investigation.
+7. **Follow established procedures** — When a project has a Makefile, CI script, setup.sh, or documented install process, follow it exactly. Do NOT invent shortcuts or install dependencies individually. Read the build/install instructions first. If none exist, ask.

package/templates/.claude/rules/01-debugging.md

@@ -9,14 +9,21 @@
 - List >=3 possible causes
 - Annotate each with supporting/contradicting evidence
 - Record hypotheses in `docs/debug-log.md`
+- **Do NOT declare any single hypothesis as "the root cause" at this stage**
 
-### Phase 3: Verify
-- Use minimal experiments to confirm/refute hypotheses — don't jump to fixing
+### Phase 3: Verify (do NOT jump to fixing)
+- Design a minimal experiment to confirm/refute EACH hypothesis
+- Run the experiment and record results
+- Eliminate hypotheses one by one with evidence
 - Update debug-log as each hypothesis is eliminated
+- **Only after ≥2 hypotheses are eliminated with evidence may you identify a root cause**
 
 ### Phase 4: Fix
-- Only act after confirming the root cause
-- Explain how the fix addresses the root cause (not just the symptoms)
+- State which hypotheses were eliminated and how
+- Explain how the fix addresses the confirmed root cause (not just the symptoms)
 - Run all related tests after fixing
 
-**Absolutely forbidden: seeing an error and immediately changing code to "try something"**
+### Absolutely forbidden
+- Seeing an error and immediately changing code to "try something"
+- Declaring "root cause" after seeing a single error message — that's a hypothesis, not a conclusion
+- Stopping investigation after the first plausible explanation — plausible ≠ confirmed

package/templates/.claude/rules/03-context-mgmt.md

@@ -14,6 +14,18 @@
 - Ensure progress.md is up to date before compact
 - First thing after compact: read `docs/progress.md` to restore context
 
+### When tasks feel overwhelming
+Hard tasks create discomfort — the urge to simplify, declare partial success, or find an exit. This is normal. But the wrong response is to lower quality or invent excuses. Here's how to stay grounded:
+
+- **It's OK to be stuck.** Say "I'm stuck on X because Y" — that's honest, and the user can help. What's NOT OK is hiding behind "context is full" or "let's continue in a new session" — these are avoidance, not solutions.
+- **Shrink the problem.** When the whole task feels too big, stop looking at the whole. What is the ONE next thing you can verify? Do that. Then the next. Small verified steps compound into completed tasks.
+- **Uncertainty is normal for hard problems.** You don't need to know the full answer to make progress. Verify what you can, label what you can't, and keep moving.
+- **Progress = what you've verified, not how much code you've written.** Three lines with a passing test is more progress than 200 lines of unverified code.
+- **When in doubt, stop and ask — this is mandatory, not optional.** If you notice yourself about to take a shortcut, simplify an approach, or skip a verification step, that is your signal to STOP and check in with the user. Say: "I'm about to [shortcut], because [reason]. Should I proceed this way, or do you want me to [full-quality alternative]?" Silently lowering quality and pushing forward is the worst outcome — it wastes both your work and the user's time, and the further you go the harder it is to undo.
+- **Remember why you're here.** Easy tasks don't need you — the user can do those alone. They brought you in precisely because the task is hard. Difficulty is not a signal to retreat; it's where you provide the most value. Pushing through the hard parts with care and persistence is what makes the collaboration worthwhile.
+
 ### Prohibited
 - Do not start a large new task when context is nearly full
 - Do not mix unrelated tasks in a single conversation
+- Do not use context pressure as a reason to skip edge cases, simplify solutions, or omit verification
+- Do not propose "continuing in a new session" as a way to avoid completing difficult work

package/templates/.claude/rules/05-phase-discipline.md

@@ -1,13 +1,15 @@
 ## Phase Discipline
 
-Claude must confirm which phase it's in before acting.
+Every task progresses through phases. Do NOT skip or jump ahead.
 
 ### Phases
-- **Research**: read only, no edits, no plans, report findings
-- **Plan**: discuss approach, write plan, no code edits
-- **Implement**: execute the agreed plan, make code changes
+- **Research**: read only. No edits, no plans. Output: findings and questions.
+- **Plan**: discuss approach, propose options, write plan. No code edits.
+- **Implement**: execute the agreed plan. Code changes allowed.
 
 ### Rules
-- If the user declares a phase, stay in it. Don't jump ahead.
-- If the current phase is unclear, ask the user before proceeding.
-- Transitioning between phases requires explicit acknowledgment.
+1. If the user declares a phase, stay in it until they say otherwise.
+2. If the current phase is unclear, ask before proceeding.
+3. **Transitioning from Research/Plan → Implement requires explicit user approval.** Words like "go ahead", "do it", "approved", "yes" count. Your own "I'll go ahead and..." does NOT count.
+4. If you are about to write code while still in Research or Plan — that is a phase violation. Stop and ask.
+5. Starting a non-trivial task without planning (or /think) is a phase skip. Default sequence: understand → plan → get approval → implement.

package/templates/.claude/rules/07-integrity.md

@@ -43,6 +43,17 @@ Before starting work, identify and verify:
 
 **Rule: List key assumptions at the start. Verify each one. Record how it was verified.**
 
+### 4a. Project state is NEVER assumed
+
+Project phases (frozen, submitted, taped-out, deployed, released), component statuses (working, broken, deprecated), and environment state (installed, configured, running) must be verified by reading actual files (status docs, CI output, lock files) or asking the user.
+
+Prohibited inferences:
+- "Since we already submitted X..." — did we? Check.
+- "The design is frozen, so..." — is it? Read the status doc.
+- "Dependencies are installed..." — are they? Run the check command.
+
+**Rule: When about to act on a project state assumption, STOP. Read the file that proves the state, or ask the user. "I assume X is in state Y" is not acceptable.**
+
 ### 5. External communications require human review
 
 Anything sent under the user's name — issues, PR comments, emails, forum posts — is the user's reputation on the line. Your mistakes become their embarrassment.

package/templates/.claude/skills/think/SKILL.md

@@ -70,6 +70,7 @@ Rules:
 - Follow existing codebase patterns unless there's a strong reason not to
 - Flag risks or unknowns you've spotted
 - **Every step must have acceptance criteria** — "done when" must be observable and verifiable, not vague. Bad: "done when refactored". Good: "done when 3 methods extracted, each ≤20 lines, all tests pass"
+- **Simplicity bias** — If a simple approach meets all requirements, list it first and recommend it. Do NOT lead with complex/elegant solutions unless the user signals they want that. "Simple but sufficient" beats "powerful but overkill".
 
 ## Step 4: Self-review