cc-discipline 2.10.2 → 2.10.3

package/README.md

@@ -21,21 +21,104 @@ Three shell scripts that run automatically before/after Claude's actions:
 
 **`streak-breaker.sh`** — Tracks per-file edit counts. Warns at 3, **hard-blocks at 5**. Forces Claude to stop and find the root cause instead of endlessly patching.
 
+Here's what it looks like in practice:
+
 ```
-MOLE-WHACKING ALERT (hard stop)
-File src/auth.py has been edited 5 times.
-You are repeatedly patching symptoms instead of solving the root cause.
-Required actions:
-  1. Stop editing this file immediately
-  2. Review the purpose of all 5 edits
-  3. Look for the common root cause
-  4. Report findings to the user and wait for guidance
+You:   "Fix the login validation bug in auth.py"
+
+Claude: I'll fix the validation logic.
+        [Edit src/auth.py — fix email regex]
+
+Claude: The regex wasn't enough, let me also add length check.
+        [Edit src/auth.py — add input length validation]
+
+Claude: That broke the existing tests, let me adjust.
+        [Edit src/auth.py — fix test compatibility]
+        ⚠️ EDIT NOTE: File src/auth.py has been edited 3 times.
+        Quick check: are these edits building toward a goal,
+        or fixing previous edits?
+
+Claude: Let me try a different approach to the validation.
+        [Edit src/auth.py — rewrite validation layer]
+
+Claude: Almost there, one more adjustment...
+        [Edit src/auth.py — blocked]
+
+        🛑 EDIT CHECKPOINT
+        File src/auth.py has been edited 5 times this session.
+        Reflect:
+          1. Are these edits progressing toward a goal,
+             or fixing previous edits?
+          2. If fixing previous edits: pause and look
+             for the root cause.
+
+Claude: You're right. Looking at all 5 edits, I was patching
+        symptoms. The real issue is that the User model's
+        validate() method is called before sanitization.
+        Let me fix it at the source instead.
 ```
 
+Without the hook, Claude would keep editing `auth.py` indefinitely — each fix creating the next bug. The hook forces a pause that leads to root-cause discovery.
+
+---
+
 **`pre-edit-guard.sh`** — Checks `docs/debug-log.md` for unverified hypotheses. If you're debugging and haven't finished the process, it blocks source code edits until you do.
 
+```
+You:   "The API is returning 500 errors on /users endpoint"
+
+Claude: Let me investigate.
+        [Bash: curl localhost:3000/users]
+        → 500 Internal Server Error
+
+Claude: I think it's a database connection issue. Let me fix
+        the connection pool config.
+        [Edit src/db.py — blocked]
+
+        🛑 docs/debug-log.md has 2 unverified hypotheses.
+        Please complete the debugging process (verify or
+        eliminate hypotheses) before editing source code.
+
+Claude: Right, I haven't verified my hypothesis yet.
+        Let me check the actual error logs first.
+        [Bash: tail -50 logs/error.log]
+        → TypeError: Cannot read property 'map' of undefined
+           at UserSerializer.format (src/serializers.py:42)
+
+Claude: The error is in the serializer, not the database.
+        My first hypothesis was wrong. Let me update
+        debug-log.md and then fix the actual issue.
+```
+
+Without the hook, Claude would have "fixed" the database config — a perfectly working component — and the real bug would remain.
+
+---
+
 **`post-error-remind.sh`** — Detects error patterns (test failures, crashes, build errors) in command output and injects a debugging discipline reminder before Claude can react impulsively.
 
+```
+Claude: Let me run the tests.
+        [Bash: pytest tests/]
+        → FAILED tests/test_auth.py::test_login - AssertionError
+        → 1 failed, 23 passed
+
+        ⚡ Error encountered — debugging checklist:
+        1. Resist modifying code immediately
+        2. Fully understand the error message
+        3. List >=3 possible causes
+        4. Only then fix
+
+Claude: Before jumping in, let me understand the failure.
+        The test expects a 200 but gets 401. Three possible
+        causes:
+        1. Token generation changed (check auth.py changes)
+        2. Test fixture uses expired mock token
+        3. Middleware order changed after recent refactor
+        Let me verify each...
+```
+
+Without the hook, Claude's instinct is to immediately open the test or source file and start editing. The reminder forces a diagnostic pause.
+
 ### Rules (the reminders)
 
 Auto-injected markdown in `.claude/rules/` — Claude sees them when operating on matching files. Not as strong as hooks, but provides structure:

package/README.zh-CN.md

@@ -127,10 +127,102 @@ Hooks 是在 Claude 执行操作前/后自动运行的 shell 脚本。**exit 2
 
 | Hook | 触发时机 | 作用 |
 |------|---------|------|
-| `pre-edit-guard.sh` | 编辑文件前 | 检查是否有未完成的调试流程 |
 | `streak-breaker.sh` | 编辑文件前 | 同文件编辑 ≥3 次警告，≥5 次硬停止 |
+| `pre-edit-guard.sh` | 编辑文件前 | 检查是否有未完成的调试流程 |
 | `post-error-remind.sh` | 执行命令后 | 检测到错误输出时提醒遵守调试纪律 |
 
+**实际效果演示：**
+
+**streak-breaker** — 阻止打地鼠：
+
+```
+你：  "修一下 auth.py 的登录验证 bug"
+
+Claude: 我来修正验证逻辑。
+        [编辑 src/auth.py — 修正邮箱正则]
+
+Claude: 正则不够，再加个长度检查。
+        [编辑 src/auth.py — 增加输入长度验证]
+
+Claude: 把之前的测试搞挂了，调整一下。
+        [编辑 src/auth.py — 修复测试兼容性]
+        ⚠️ 提示：auth.py 已被编辑 3 次。
+        检查一下：这些修改是在推进目标，还是在修前面的修改？
+
+Claude: 换个思路重写验证层。
+        [编辑 src/auth.py — 重写验证逻辑]
+
+Claude: 差不多了，再调一下...
+        [编辑 src/auth.py — 被阻止]
+
+        🛑 编辑检查点
+        文件 auth.py 本次会话已被编辑 5 次。
+        反思：
+          1. 这些修改是在推进目标，还是在修之前的修改？
+          2. 如果是后者：停下来，寻找根本原因。
+
+Claude: 你说得对。回顾这 5 次编辑，我一直在修症状。
+        真正的问题是 User 模型的 validate() 在
+        sanitization 之前被调用了。我应该从源头修。
+```
+
+没有这个 hook，Claude 会无限编辑 auth.py — 每次修复都制造下一个 bug。hook 强制暂停，引导发现根本原因。
+
+---
+
+**pre-edit-guard** — 阻止跳过诊断直接改代码：
+
+```
+你：  "API 的 /users 接口返回 500 错误"
+
+Claude: 我来排查。
+        [执行: curl localhost:3000/users]
+        → 500 Internal Server Error
+
+Claude: 我觉得是数据库连接池的问题，改一下配置。
+        [编辑 src/db.py — 被阻止]
+
+        🛑 docs/debug-log.md 中有 2 个未验证的假设。
+        请先完成调试流程（验证或排除假设），
+        再编辑源代码。
+
+Claude: 对，我还没验证我的假设。先看看错误日志。
+        [执行: tail -50 logs/error.log]
+        → TypeError: Cannot read property 'map' of undefined
+           at UserSerializer.format (src/serializers.py:42)
+
+Claude: 错误在序列化器，不是数据库。我的第一个
+        假设是错的。先更新 debug-log.md 再修真正的问题。
+```
+
+没有这个 hook，Claude 会"修好"数据库配置 — 一个完全正常的组件 — 而真正的 bug 依然存在。
+
+---
+
+**post-error-remind** — 阻止看到报错就冲动改代码：
+
+```
+Claude: 跑一下测试。
+        [执行: pytest tests/]
+        → FAILED tests/test_auth.py::test_login - AssertionError
+        → 1 failed, 23 passed
+
+        ⚡ 检测到错误 — 调试清单：
+        1. 不要立即修改代码
+        2. 先完整理解错误信息
+        3. 列出 ≥3 个可能原因
+        4. 然后再动手
+
+Claude: 先别急着改。测试期望 200 但拿到了 401。
+        三个可能原因：
+        1. Token 生成逻辑变了（检查 auth.py 的改动）
+        2. 测试用的 mock token 过期了
+        3. 中间件顺序在最近的重构后变了
+        让我逐个验证...
+```
+
+没有这个 hook，Claude 的本能是立即打开测试文件或源文件开始编辑。提醒强制了一个诊断暂停。
+
 **调整硬度**：编辑 hook 脚本中的 `exit` 返回值：
 - `exit 0` = 允许操作（可附带提醒信息）
 - `exit 1` = 报错但不阻止操作（hook 执行失败）

package/global/CLAUDE.md

@@ -41,5 +41,5 @@ Don't skip the first three steps and jump straight to the fourth.
 
 - Use subagents for research. Don't read large volumes of files in the main conversation.
 - Update docs/progress.md after completing each milestone.
-- Proactively warn when context is nearly full. Don't wait for auto-compact.
+- Don't proactively warn about context running low or suggest compacting. The system auto-compacts at 0% — you cannot see the percentage. Keep progress.md updated instead.
 - First thing after compact: read `docs/progress.md` and `docs/debug-log.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-discipline",
-  "version": "2.10.2",
+  "version": "2.10.3",
   "description": "Discipline framework for Claude Code — rules, hooks, and agents that keep AI on track",
   "bin": {
     "cc-discipline": "bin/cli.js"
@@ -28,7 +28,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/techhu/cc-discipline.git"
+    "url": "git+https://github.com/TechHU-GS/cc-discipline.git"
   },
-  "homepage": "https://github.com/techhu/cc-discipline#readme"
+  "homepage": "https://github.com/TechHU-GS/cc-discipline#readme"
 }

package/templates/.claude/skills/self-check/SKILL.md

@@ -61,11 +61,35 @@ Pause and honestly answer every question below.
 
 If any of the above are stale or incomplete: **update docs/progress.md now before continuing.** This takes 2 minutes and saves hours of re-discovery after compact.
 
-## 6. What's working well?
+## 6. Am I using the project's scaffolding?
+
+Projects accumulate custom tooling — audit scripts, lint configs, validators (cppcheck, custom DRC, schema checkers, etc.). These get forgotten and rot if not exercised.
+
+- Check **CLAUDE.md "Project Tools"** and the **Project-specific Checks** list below. Are any relevant to current work but haven't been run?
+- Did I build a new tool/script/check this session that future sessions should know about? If yes, **register it now in two places**:
+  1. `CLAUDE.md` "Project Tools" — what it is, where it lives, when to use it
+  2. The **Project-specific Checks** list below — so the next /self-check surfaces it automatically
+- If the **Project-specific Checks** list below is empty or stale, that's a signal worth raising with the user.
+
+### Project-specific Checks
+
+<!--
+Add project-specific scaffolding here. One line per check, format:
+  - `<command>` — when to run / what it catches
+Examples:
+  - `make lint` — before commit, catches license headers and formatting
+  - `python tools/audit_rbac.py` — after schema changes, catches RBAC drift
+  - `cppcheck src/` — after C/C++ edits, catches null deref / leak patterns
+Keep this list curated — remove tools that are obsolete.
+-->
+
+(Empty — fill in as the project develops scaffolding worth checking periodically.)
+
+## 7. What's working well?
 
 Before reporting issues, note one thing that's going well — a good approach, a clean fix, effective tool use, or strong alignment with the user's direction. Recognizing what works reinforces it.
 
-## 7. Status report
+## 8. Status report
 
 After answering the above, output a brief status:
 
@@ -76,6 +100,7 @@ Current action: [what I'm doing now]
 On track: yes/no/drifted
 Progressing: yes/circling
 Progress recorded: yes/updated now/no
+Scaffolding: [used/skipped/n/a]
 Going well: [one thing]
 Issues found: [list, or "none"]
 ```