fix(u32): enforce live constraint budget (#173)

Author: majiayu000

.claude/commands/vibeguard/gc.md

@@ -34,17 +34,23 @@ tags: [vibeguard, gc, cleanup, maintenance]
    - Delete worktrees that have been inactive for more than 7 days and have no unmerged changes
    - Only warnings about unmerged changes, listing those that need to be handled manually
 
-3. **Code Junk Scanning**
+3. **Rule Budget GC**
+   - Run `bash ${VIBEGUARD_DIR}/scripts/gc/gc-rule-budget.sh <project directory>`
+   - Count the effective U-32 task constraint budget across global, project, skill, and path-scoped rule sources
+   - List low-frequency rule candidates that should be downgraded to a skill, hook, or path-scoped child file
+
+4. **Code Junk Scanning**
    - Run `bash ${VIBEGUARD_DIR}/guards/universal/check_code_slop.sh <project directory>`
    - Detect 5 types of AI garbage patterns: null exception handling, legacy debugging code, expired TODO, dead code marking, overlong files
    - Output structured reports
 
-4. **Summary Report**
+5. **Summary Report**
    ```
    VibeGuard GC Report
    ==================
    Log: Archive XX items, current XX items
    Worktree: Clean X, warn X
+   Rule budget: X effective constraints, X downgrade candidates
    Code garbage: X problems
      - Null exception handling: X
      - Legacy debug code: X
@@ -53,13 +59,14 @@ tags: [vibeguard, gc, cleanup, maintenance]
      - Extra long files: X
    ```
 
-5. **Recommended fix**
+6. **Recommended fix**
    - Provide repair suggestions for each type of garbage problem
    - Can be repaired item by item after user confirmation
    - Run `/vibeguard:check` to verify after fixing
 
 **Reference**
 - Log archive: `scripts/gc/gc-logs.sh`
 - Worktree cleanup: `scripts/gc/gc-worktrees.sh`
+- Rule budget GC: `scripts/gc/gc-rule-budget.sh`
 - Code garbage detection: `guards/universal/check_code_slop.sh`
 <!-- VIBEGUARD:GC:END -->

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- U-32 live constraint budget tooling: `count_active_constraints.sh`, `scripts/constraints/count_active_constraints.py`, and GC downgrade-candidate reporting
 - CI doc command path validator (`scripts/ci/validate-doc-command-paths.sh`) to catch stale `~/vibeguard/...` shell examples
 - `setup.sh --check` now emits a structured rollup (counts of OK/INFO/WARN/FAIL/BROKEN/MISSING and a final verdict line) so a single broken probe is not lost in 40+ healthy rows
 - `setup.sh --check --quiet` filters output to problems-only plus the rollup, for fast triage in long install logs

README.md

@@ -189,7 +189,7 @@ python3 ~/vibeguard/guards/python/check_dead_shims.py /path                # dea
 | `/vibeguard:learn` | Generate guard rules from errors / extract Skills from discoveries |
 | `/vibeguard:interview` | Deep requirements interview → SPEC.md |
 | `/vibeguard:exec-plan` | Long-running task execution plan, cross-session resume |
-| `/vibeguard:gc` | Garbage collection (log archival + worktree cleanup + code slop scan) |
+| `/vibeguard:gc` | Garbage collection (logs + worktrees + rule budget + code slop scan) |
 | `/vibeguard:stats` | Hook trigger statistics |
 
 **Routing Contract**

docs/CLAUDE.md.example

@@ -204,7 +204,7 @@ interview → preflight → coding → check → review → learn → stats
 | `/vibeguard:build-fix` | Build error fix |
 | `/vibeguard:learn` | Generate new guards from mistakes |
 | `/vibeguard:exec-plan` | Long-term task execution plan (cross-session recovery) |
-| `/vibeguard:gc` | Garbage collection (log archiving + worktree cleaning + code garbage scanning) |
+| `/vibeguard:gc` | Garbage collection (log archiving + worktree cleaning + rule budget + code garbage scanning) |
 | `/vibeguard:stats` | Hook trigger statistics |
 
 ---

docs/README_CN.md

@@ -155,7 +155,7 @@ python3 ~/vibeguard/guards/python/check_dead_shims.py /path
 | `/vibeguard:learn` | 从错误中生成 guard/rule，或提炼 Skill |
 | `/vibeguard:interview` | 深度需求访谈，输出 SPEC.md |
 | `/vibeguard:exec-plan` | 长任务执行计划，支持跨会话恢复 |
-| `/vibeguard:gc` | 垃圾回收（日志归档 + worktree 清理 + code slop 扫描） |
+| `/vibeguard:gc` | 垃圾回收（日志归档 + worktree 清理 + 规则预算 + code slop 扫描） |
 | `/vibeguard:stats` | hook 触发统计 |
 
 快捷别名：`/vg:pf` `/vg:gc` `/vg:ck` `/vg:lrn`

docs/rule-reference.md

@@ -53,7 +53,7 @@ Canonical source of truth: `rules/claude-rules/`
 | U-29 | Error-driven downgrade paths must be observable at error level | Strict | If an error causes user-visible missing data or incorrect output, you must log it at `error` level or raise it. |
 | U-30 | Cross-boundary Pydantic models must use `extra="allow"` | Strict | Any Pydantic model that receives external or cross-boundary data must set `extra="allow"` so `model_validate()` does not silently drop un... |
 | U-31 | Cache keys must include code version | Strict | When builder or generation logic changes, old cache entries must invalidate automatically. |
-| U-32 | Rule overload threshold + absolute-language detection | Strict | If one rule file contains more than 30 active constraints, raise an overload warning. |
+| U-32 | Rule overload threshold + absolute-language detection | Strict | Keep the effective constraint set for a single agent task at 15 or fewer items. |
 | U-33 | Code search defaults to glob/grep; vector DB requires written justification | Strict | For agent code retrieval, plain glob/grep driven by the model has empirically beaten vector indexes in production. |
 
 ---

hooks/CLAUDE.md

@@ -16,6 +16,7 @@ AI coded agent hooks script, automatically triggered before and after the operat
 | `post-edit-guard.sh` | PostToolUse(Edit) | Detect quality problems after editing: unwrap, console.log, hard-coded path, Go error discard, oversized diff, repeated editing of the same file (churn), W-15 consecutive same-file edit loop. | unsupported |
 | `post-write-guard.sh` | PostToolUse(Write) | Detect duplicate definitions and files with the same name after creating a new file. | unsupported |
 | `analysis-paralysis-guard.sh` | PostToolUse(Read|Glob|Grep) | Detect excessive exploration without progress and prompt the agent to act. | unsupported |
+| `count_active_constraints.sh` | SessionStart | Count effective task constraints loaded into agent context and enforce the U-32 live-context budget in strict profile. | unsupported |
 | `post-build-check.sh` | PostToolUse(Edit/Write) | Automatically run the build check corresponding to the language after editing. | native |
 | `skills-loader.sh` | Manual optional | Optional first read prompt script; not registered to hooks by default. | unsupported |
 | `stop-guard.sh` | Stop | Verify access control before completion and check for uncommitted source code changes. | native |

hooks/count_active_constraints.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# VibeGuard SessionStart/UserPromptSubmit Hook — U-32 live constraint budget
+#
+# Counts the effective constraints that can enter the current agent context.
+# >15 emits an advisory, >30 becomes a hard block when strict mode is enabled.
+
+set -euo pipefail
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${HOOK_DIR}/log.sh"
+source "${HOOK_DIR}/circuit-breaker.sh"
+vg_start_timer
+
+# CI guard: the budget is a human-agent context signal, not a CI failure source.
+vg_is_ci && exit 0
+
+INPUT=$(cat 2>/dev/null || true)
+
+REPO_DIR="$(cd "${HOOK_DIR}/.." && pwd)"
+COUNTER="${REPO_DIR}/scripts/constraints/count_active_constraints.py"
+if [[ ! -f "${COUNTER}" ]]; then
+  REPO_PATH_FILE="${HOME}/.vibeguard/repo-path"
+  if [[ -f "${REPO_PATH_FILE}" ]]; then
+    REPO_DIR=$(<"${REPO_PATH_FILE}")
+    COUNTER="${REPO_DIR}/scripts/constraints/count_active_constraints.py"
+  fi
+fi
+
+if [[ ! -f "${COUNTER}" ]]; then
+  vg_log "count-active-constraints" "SessionStart" "warn" "counter script missing" "${COUNTER}"
+  exit 0
+fi
+
+PROJECT_ROOT="${VIBEGUARD_PROJECT_ROOT:-}"
+if [[ -z "${PROJECT_ROOT}" ]]; then
+  PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+fi
+
+HOOK_EVENT=$(printf '%s' "${INPUT}" | vg_json_field "hook_event_name" 2>/dev/null || true)
+HOOK_EVENT="${HOOK_EVENT:-SessionStart}"
+
+COUNTER_ARGS=(--root "${PROJECT_ROOT}" --home "${HOME}" --json)
+
+if [[ -n "${VIBEGUARD_TASK_PATHS:-}" ]]; then
+  IFS=',' read -r -a _vg_task_paths <<< "${VIBEGUARD_TASK_PATHS}"
+  for _vg_task_path in "${_vg_task_paths[@]}"; do
+    [[ -n "${_vg_task_path}" ]] && COUNTER_ARGS+=(--task-path "${_vg_task_path}")
+  done
+fi
+
+if [[ -n "${VIBEGUARD_ACTIVE_SKILLS:-}" ]]; then
+  IFS=',' read -r -a _vg_skills <<< "${VIBEGUARD_ACTIVE_SKILLS}"
+  for _vg_skill in "${_vg_skills[@]}"; do
+    [[ -n "${_vg_skill}" ]] && COUNTER_ARGS+=(--skill "${_vg_skill}")
+  done
+fi
+
+REPORT_JSON=$(python3 "${COUNTER}" "${COUNTER_ARGS[@]}" 2>/dev/null || true)
+if [[ -z "${REPORT_JSON}" ]]; then
+  vg_log "count-active-constraints" "${HOOK_EVENT}" "warn" "constraint counter failed" "${PROJECT_ROOT}"
+  exit 0
+fi
+
+read -r STATUS TOTAL WARN_THRESHOLD BLOCK_THRESHOLD SUMMARY < <(
+  python3 -c '
+import json, sys
+data = json.load(sys.stdin)
+status = data.get("status", "ok")
+total = data.get("total", 0)
+warn = data.get("warn_threshold", 15)
+block = data.get("block_threshold", 30)
+sources = sorted(data.get("sources", []), key=lambda item: item.get("count", 0), reverse=True)[:3]
+summary = "; ".join(
+    "{count} {kind} {path}".format(
+        count=item.get("count", 0),
+        kind=item.get("kind", "?"),
+        path=item.get("path", ""),
+    )
+    for item in sources
+)
+print(status, total, warn, block, summary)
+' <<< "${REPORT_JSON}"
+)
+
+if [[ "${STATUS}" == "ok" ]]; then
+  vg_log "count-active-constraints" "${HOOK_EVENT}" "pass" "constraints=${TOTAL}" "${SUMMARY}"
+  exit 0
+fi
+
+MESSAGE="VIBEGUARD U-32 ${STATUS}: effective task constraints=${TOTAL} (warn>${WARN_THRESHOLD}, block>${BLOCK_THRESHOLD}). Split low-frequency rules into path-scoped files, skills, or hooks before adding more persistent instructions. Top sources: ${SUMMARY}"
+
+if [[ "${STATUS}" == "block" ]]; then
+  vg_log "count-active-constraints" "${HOOK_EVENT}" "block" "constraints=${TOTAL}" "${SUMMARY}"
+  if [[ "${VIBEGUARD_U32_STRICT:-1}" == "1" ]]; then
+    printf '%s\n' "[BLOCKED] ${MESSAGE}" >&2
+    exit 2
+  fi
+else
+  vg_log "count-active-constraints" "${HOOK_EVENT}" "warn" "constraints=${TOTAL}" "${SUMMARY}"
+fi
+
+VG_HOOK_EVENT="${HOOK_EVENT}" VG_MESSAGE="${MESSAGE}" python3 -c '
+import json, os
+event = os.environ.get("VG_HOOK_EVENT", "SessionStart")
+message = os.environ.get("VG_MESSAGE", "")
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": event,
+        "additionalContext": message,
+    }
+}, ensure_ascii=False))
+'

hooks/manifest.json

@@ -130,6 +130,21 @@
       },
       "codex": {"enabled": false, "support": "unsupported", "reason": "Codex runtime scope uses Bash approvals and Stop hooks only"}
     },
+    {
+      "name": "count-active-constraints",
+      "script": "count_active_constraints.sh",
+      "kind": "hook",
+      "trigger": "SessionStart",
+      "responsibilities": "Count effective task constraints loaded into agent context and enforce the U-32 live-context budget in strict profile.",
+      "decision_types": ["pass", "warn", "block"],
+      "claude": {
+        "enabled": true,
+        "event": "SessionStart",
+        "matchers": [null],
+        "profiles": ["strict"]
+      },
+      "codex": {"enabled": false, "support": "unsupported", "reason": "Codex runtime scope uses Bash approvals and Stop hooks only"}
+    },
     {
       "name": "post-build-check",
       "script": "post-build-check.sh",

rules/claude-rules/common/coding-style.md

@@ -97,29 +97,35 @@ When you declare framework components such as configs, traits, persistence layer
 - GC receives `project_root` but never propagates it to child tasks, causing functional downgrade.
 
 ## U-32: Rule overload threshold + absolute-language detection (strict)
-If one rule file contains more than 30 active constraints, raise an overload warning. When a rule uses absolute language such as "always", "never", or "must", it also needs a downgrade path so the system does not create an illusion of control.
+Keep the effective constraint set for a single agent task at 15 or fewer items. If the live task context exceeds 15 constraints, warn and split lower-frequency material into path-scoped child files, skills, hooks, or verify scripts. If it exceeds 30 constraints, block and require decomposition before continuing. When a rule uses absolute language such as "always", "never", or "must", it also needs a downgrade path so the system does not create an illusion of control.
 
-**Sources** (three-source convergence, 2026-04-16):
+**Sources**:
+- arXiv 2605.06445 (Constraint Decay, 2026-05-09 RSS scout): across 80 greenfield and 20 feature tasks over 8 web frameworks, stronger agents lost about 30 assertion-pass-rate points as structured constraints accumulated; data-layer defects were the dominant failure mode.
 - Addy Osmani, "How to Write a Good Spec": the curse of instructions. Ten rules can be obeyed less reliably than five.
 - Anthropic Claude Code Best Practices: a bloated `CLAUDE.md` causes Claude to ignore the instructions that actually matter.
 - Martin Fowler, "Context Engineering": illusion of control is an anti-pattern. LLMs are probabilistic systems, so absolute language creates false guarantees.
 
 **Mechanical checks**:
-1. If a rule file contains more than 30 entries, recommend decomposing it into path-scoped child files (for example, only load Rust rules for `*.rs`).
-2. If a rule uses absolute phrasing such as "ensure X", "never do Y", or "must be 100%", attach both:
+1. Count the actual task-loaded constraint set: global memory files, project `AGENTS.md`/`CLAUDE.md`, active skill files, and path-scoped native rules that match the current task files.
+2. If the live task context contains more than 15 effective constraints, emit a U-32 warning and recommend moving lower-frequency material to path-scoped child files, skills, hooks, or verify scripts.
+3. If the live task context contains more than 30 effective constraints, block the task until the constraint set is decomposed.
+4. If a rule file contains more than 30 entries, recommend decomposing it into path-scoped child files (for example, only load Rust rules for `*.rs`).
+5. If a rule uses absolute phrasing such as "ensure X", "never do Y", or "must be 100%", attach both:
    - A downgrade path: "If X is not feasible, fall back to Y and mark it stale."
    - An observability hook: a verification command or guard script that proves whether the rule is actually being followed.
-3. If a global `CLAUDE.md` or `AGENTS.md` file grows beyond 100 lines, move material into skills or path-scoped rule files.
+6. If a global `CLAUDE.md` or `AGENTS.md` file grows beyond 100 lines, move material into skills or path-scoped rule files.
+7. Run `bash hooks/count_active_constraints.sh` through the strict hook profile, or run `python3 scripts/constraints/count_active_constraints.py --root . --include-canonical-rules --gc-report` manually, to inspect the current budget and downgrade candidates.
 
 **Repair order**:
-1. Audit the current rule set and annotate trigger frequency for each rule from access logs.
-2. Candidate low-frequency rules (zero hits in the last 30 days) for removal or demotion into a skill.
-3. Verify whether high-frequency rules use absolute language without a downgrade path.
-4. Split large files by language or domain (`common/`, `rust/`, `python/`, `security/`).
+1. Count the current task's effective constraints before adding any new persistent instruction.
+2. Audit the current rule set and annotate trigger frequency for each rule from access logs.
+3. Candidate low-frequency rules (zero hits in the last 30 days) for removal or demotion into a skill.
+4. Verify whether high-frequency rules use absolute language without a downgrade path.
+5. Split large files by language or domain (`common/`, `rust/`, `python/`, `security/`) and attach path frontmatter where possible.
 
 **Additional checks**:
-4. Before adding a persistent rule, first confirm it is a high-frequency, stable, cross-task constraint; otherwise prefer a skill, hook, or verify script.
-5. Long workflow templates, one-off playbooks, and low-frequency knowledge should not live permanently in `CLAUDE.md` or `AGENTS.md`; convert them into an index plus on-demand documents.
+1. Before adding a persistent rule, first confirm it is a high-frequency, stable, cross-task constraint; otherwise prefer a skill, hook, or verify script.
+2. Long workflow templates, one-off playbooks, and low-frequency knowledge should not live permanently in `CLAUDE.md` or `AGENTS.md`; convert them into an index plus on-demand documents.
 
 **Anti-patterns**:
 - A single file accumulates 50+ rules and expects all of them to remain active at once.