pinrule 0.16.0__tar.gz

pinrule-0.16.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report (English)
+about: Report a pinrule bug / false positive / install issue / hook malfunction
+title: '[Bug] '
+labels: bug
+assignees: ''
+---
+
+## What did you encounter
+
+Brief description of the problem. For **false positives** (pinrule blocks legitimate operations), paste `pinrule audit` output with the `⚠️ possible false positive` markers.
+
+## Reproduction steps
+
+1. Install via `pinrule install-hooks ...`
+2. ...
+3. Observed error / unexpected behavior
+
+## Real state (output of `pinrule doctor`)
+
+```
+(paste complete `pinrule doctor` output)
+```
+
+## Environment
+
+- pinrule version: (`pinrule --version`)
+- AI client: Claude Code / Codex CLI / Gemini CLI (with version)
+- OS: macOS / Linux / WSL
+- Python: (`python --version`)
+- Shell: zsh / bash / fish
+
+## Key logs (if any)
+
+If hook output schema errors or installation failures occur, paste the stderr / Claude Code UI error section.

pinrule-0.16.0/.github/ISSUE_TEMPLATE/bug_report.zh.md

@@ -0,0 +1,35 @@
+---
+name: Bug 报告
+about: 报告 pinrule 的 bug / 假阳 / 装机问题 / hook 失效
+title: '[Bug] '
+labels: bug
+assignees: ''
+---
+
+## 你遇到什么
+
+简短描述问题。如果是**假阳**（pinrule 误拦合法操作）请贴 `pinrule audit` 输出含 `⚠️ 可能假阳` 标记的 trigger。
+
+## 复现步骤
+
+1. 装机 `pinrule install-hooks ...`
+2. ...
+3. 看到的错误 / 不预期行为
+
+## 状态（用 `pinrule doctor` 输出）
+
+```
+（贴 `pinrule doctor` 完整输出）
+```
+
+## 环境
+
+- pinrule 版本: （`pinrule --version`）
+- AI 客户端: Claude Code / Codex CLI / Gemini CLI（含版本）
+- OS: macOS / Linux / WSL
+- Python: （`python --version`）
+- Shell: zsh / bash / fish
+
+## 关键日志（如有）
+
+如果 hook 输出 schema 错或装机失败，贴 stderr / Claude Code UI 报错段。

pinrule-0.16.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature / Improvement Suggestion (English)
+about: Suggest new features / new rule scenarios / new AI client backend
+title: '[Feature] '
+labels: enhancement
+assignees: ''
+---
+
+## Your real pain point
+
+Describe the scenario concretely. pinrule's design principle is "user-real-pain-driven" — we don't accept "I think this might be useful" type preventive suggestions.
+
+## Proposed solution
+
+If you have a specific idea, write it out. Include:
+- Is it at the rule layer (can users solve this by writing their own `rules.yaml`)?
+- Or at the check layer (needs new engine-layer violation_check function)?
+- Or at the hook layer (needs new hook event or changes to existing hook behavior)?
+
+## Have you considered alternatives
+
+pinrule explicitly **doesn't do** these things — see README's "What pinrule doesn't do" section. If your need falls outside those boundaries, explain why an exception is necessary.
+
+## Real user scenario (not speculation)
+
+One of pinrule v1's failure lessons was "preventive design." New features must be driven by real user scenarios; we don't accept "might be useful" type needs.

pinrule-0.16.0/.github/ISSUE_TEMPLATE/feature_request.zh.md

@@ -0,0 +1,26 @@
+---
+name: 功能 / 改进建议
+about: 建议新功能 / 新规则场景 / 新 AI 客户端 backend
+title: '[Feature] '
+labels: enhancement
+assignees: ''
+---
+
+## 你的痛点
+
+具体描述场景。pinrule 设计原则是「用户痛点驱动」— 不接受「我觉得可能有用」类预防性建议。
+
+## 提议方案
+
+如有具体思路写出来。包括：
+- 是规则层（用户自己写 `rules.yaml` 能解决吗）
+- 还是 check 层（需要新工程层 `violation_check` 函数）
+- 还是 hook 层（需要新 hook event 或改现有 hook 行为）
+
+## 替代方案考虑过吗
+
+pinrule 明确**不做**这些 — 看 README「试过但放弃的」段。如果你的需求落在这些边界外，说明为什么必须破例。
+
+## 真实用户场景（不是猜测）
+
+pinrule v1 的教训之一是「预防性设计」— 新功能必须有真实用户场景驱动，不接受「可能有用」类需求。

pinrule-0.16.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## What this PR does
+
+Brief description of the change. If it's a new feature, explain whether it's at the rule layer / check layer / hook layer.
+
+## Real driving scenario
+
+pinrule's validation criterion is "the author / user can describe 3 concrete cases" — what real scenarios does this PR solve?
+
+## Verification evidence
+
+- [ ] All tests pass: `pytest tests/ -q`
+- [ ] Static checks clean: `ruff check pinrule/ tests/ && mypy pinrule/ tests/ && vulture pinrule/ --min-confidence 80`
+- [ ] Manual run verifies hook behavior (if hooks changed)
+- [ ] If adding new rule templates / check functions, add corresponding tests
+
+## Boundary check
+
+- [ ] No LLM dependency introduced
+- [ ] No retrieval / cosine / scoring system introduced
+- [ ] No backward-incompatible breakage of existing rule configs
+- [ ] Small and reviewable by default; larger batches OK when the maintainer has explicitly asked for "one PR, don't fragment it"
+
+## Related
+
+- Related issue: #
+- Related version: (see `pinrule --version`)

pinrule-0.16.0/.github/PULL_REQUEST_TEMPLATE.zh.md

@@ -0,0 +1,26 @@
+## 这个 PR 做什么
+
+简短描述改动。如果是新功能，说明对应规则层 / check 层 / hook 层哪一层。
+
+## 驱动场景
+
+pinrule 验证标准是「作者 / 用户能讲出 3 个具体案例」— 这个 PR 解决的场景是什么？
+
+## 验证证据
+
+- [ ] 测试全过：`pytest tests/ -q`
+- [ ] 静态检查清干净：`ruff check pinrule/ tests/ && mypy pinrule/ tests/ && vulture pinrule/ --min-confidence 80`
+- [ ] manual run 验证 hook 行为（如果改了 hook）
+- [ ] 如果加规则模板 / check 函数，加对应测试
+
+## 边界检查
+
+- [ ] 不引入 LLM 依赖
+- [ ] 不引入 retrieval / cosine / 评分系统
+- [ ] 不破现有 `rules.yaml` 配置兼容
+- [ ] 默认保持小、可 review；维护者明确要求「一个 PR 别拆碎」时一波到位也合理
+
+## 相关
+
+- 关联 issue: #
+- 相关版本: （从 `pinrule --version` 看）

pinrule-0.16.0/.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check pinrule/ tests/
+
+      - name: Dead code scan (vulture, min-confidence 60)
+        run: vulture pinrule/ whitelist.py --min-confidence 60
+
+      - name: Type check (mypy)
+        run: |
+          mypy pinrule/
+          mypy tests/
+
+      - name: Test
+        run: pytest tests/ -q
+
+      - name: Build wheel
+        run: |
+          pip install build
+          python -m build --wheel
+
+      - name: Verify wheel contains yaml templates AND signal data
+        run: |
+          python -c "
+          import glob, zipfile, sys
+          wheels = glob.glob('dist/pinrule-*-py3-none-any.whl')
+          if not wheels: sys.exit('wheel build 失败 — dist/ 无 wheel')
+          z = zipfile.ZipFile(wheels[0])
+          names = z.namelist()
+          # v0.6.0 BREAKING: sticky.* → rules.* 重命名 (v0.9.6 修)
+          # v0.9.15 critical: data/signals/ 整个目录之前漏 force-include
+          # → wheel 缺 signals 导致 compile_alternation() never-match →
+          # evidence / keep_pushing / non_blocking 等 keyword 层失效.
+          # codex GPT-5.5 cross-model audit 抓到. 影响所有 pip install 用户.
+          expected = [
+              'data/rules.dev.example.yaml',
+              'data/rules.dev.example.zh.yaml',
+              'data/locales/en.yaml',
+              'data/locales/zh.yaml',
+              'data/config.example.yaml',
+              'skills/pinrule/SKILL.md',
+              # v0.9.15: 7 个 signal type * 2 lang = 14 文件
+              # 用 sampling 而非全列：每个 signal type 至少 1 个 lang 在
+              'data/signals/weak_claims/en.txt',
+              'data/signals/completion_words/en.txt',
+              'data/signals/push_signals/en.yaml',
+              'data/signals/stop_hints/en.txt',
+              'data/signals/agent_saturation/zh.txt',
+              'data/signals/explicit_handoff/zh.txt',
+              'data/signals/user_stop_hints/zh.txt',
+          ]
+          missing = [n for n in expected if n not in names]
+          if missing: sys.exit(f'wheel 缺文件: {missing}')
+          print(f'{wheels[0]} 含全部 {len(expected)} 个关键模板 + signals ✓')
+          "
+
+      - name: Wheel smoke test - signals compile_alternation truly works
+        # v0.9.15 critical: 即便 wheel 含 signal 文件，也要 functional 验证
+        # 真能编译出 non-empty regex（防 packaging path 错 / load 失败）.
+        # codex GPT-5.5 推荐 smoke test pattern.
+        run: |
+          python -m venv /tmp/pinrule-wheel-test
+          /tmp/pinrule-wheel-test/bin/pip install dist/pinrule-*-py3-none-any.whl
+          /tmp/pinrule-wheel-test/bin/python -c "
+          from pinrule.signals import compile_alternation
+          # 验证 4 个关键 signal 真编译成 working regex
+          for sig in ('weak_claims', 'completion_words', 'push_signals', 'stop_hints'):
+              pat = compile_alternation(sig)
+              # never-match pattern '(?!)' 长度 4，真 pattern 应 >> 50
+              assert pat.pattern != '(?!)', f'{sig}: signals 没 load → never-match'
+              assert len(pat.pattern) > 50, f'{sig}: pattern 太短可能漏字眼 ({len(pat.pattern)} chars)'
+              print(f'  ✓ {sig}: pattern {len(pat.pattern)} chars')
+          print('signals compile_alternation smoke test ✓')
+          "

pinrule-0.16.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+
+# IDE
+.vscode/
+.idea/
+
+# karma 本地状态（不进仓库）
+violations.jsonl
+stats.json
+
+# Cursor IDE dogfood 资产 (含真 stdin captures 可能有 user_email 等敏感字段)
+.cursor/
+.dogfood/
+
+# OS
+.DS_Store