cc-discipline 2.3.0 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-discipline",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "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

@@ -21,7 +21,7 @@ echo "$COUNT" > "$COUNT_FILE"
 
 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

@@ -92,7 +92,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/rules/00-core-principles.md

@@ -10,3 +10,4 @@ description: "Core working principles — auto-injected before all operations"
 3. **Minimal change principle** — No large-scale refactors or rewrites unless explicitly requested
 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.

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