pi-anchorloop 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wei Hung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# pi-anchorloop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[繁體中文](README.zh-TW.md)
+
+Agent workflow skills and loop extensions for [pi](https://github.com/earendil-works/pi). Every main task type enters through its own skill, picks a playbook, and runs one shared loop: **Align → Anchor → Act → Verify**.
+
+## Skills
+
+```text
+anchorloop            core loop · principles · playbooks: autonomous-run, pause, pickup
+├─ answering     explain · compare
+├─ investigating research · diagnose
+├─ inspecting    diff-review · qa-release
+├─ coding        bug-fix · feature · refactoring · perf · prototype  (+ Mini SDD)
+├─ writing       draft · tighten · comments
+└─ solid-loop    apply-friction · author-skill · bootstrap
+shared           grilling · domain-modeling · human-feedback · agent-terse
+```
+
+- **`anchorloop`** holds what is true for every task type: restate the task, pick the entry's playbook and copy its steps into `todo`, state a `Reality anchor:` before the first change, work in small increments deleting before adding, verify against the anchor, and record friction notes. The Reflexive pass hands friction notes to `solid-loop`. `PRINCIPLES.md` names the principles playbooks cite and the user can steer with. The lifecycle playbooks cover unattended runs, clean pauses, and picking up a prior run.
+- **Entry skills** each name the anchor for their task type and index their playbooks. A playbook has an ownership line, numbered steps, and a `Reply:` line that sets what the final report contains.
+- **Shared skills** are called by entries: `grilling` for user-owned decisions, `domain-modeling` for terms and ADRs, `human-feedback` for reactions to working output, `agent-terse` for text only agents read: briefs, reports, and agent messages.
+
+## Extensions
+
+| File | What it does |
+| --- | --- |
+| `pi/anchor-gate.ts` | Shows one warning per user message when `write` or `edit` runs before the assistant states `Reality anchor:`; the call still goes through. `.md`, `.txt`, and `.html` files, `scratch/`, `docs/specs/`, and temp files outside the project pass silently. Edits made through `bash` are not checked. |
+| `pi/decision-tool.ts` | The `anchorloop_decision` tool appends single-line, spreadsheet-safe rows to a decision trail TSV, or a `start` row when a run picks up another run's trail. |
+| `pi/second-thought.ts` | Before a run that called `write`, `edit`, or `bash` settles, asks Jev (TypeSafe's typed-decision model, through pi's classifier registry) whether the final reply shows the request met, which review tier it needs, and its quality. Jev also says whether the reply is a checkpoint that hands work back to the user; a reply that only acknowledges, reports progress, or waits gets no reminder. At a checkpoint, when quality < 1.5 or the tier is `full`, it adds one visible advisory message and one continuation per run; the agent may disagree and finish. When only done < 0.25, the message is shown without a continuation. The request is the latest message the user typed; messages extensions send (intercom, monitor wakes) do not replace it. A run such a message starts is sent with `trigger: wake` and that message, and is judged on what it asks; its checkpoint question adds that a reply to a routine check the wake asked for (status, health, load, progress of running work) is not a checkpoint. A run that called `MonitorCreate`, `LoopCreate`, `goal_wait`, or a `subagent` tool is waiting on a wake and is not judged. Only the request, the trigger, the wake message, and the final reply are sent. Without a TypeSafe key it records `unknown` and does nothing. In a subagent session (`PI_SUBAGENT_ID` from pi-herdr-agents, or `PI_SUBAGENT_CHILD` from pi-subagents) it registers nothing, since the agent that spawned it judges the result. |
+| `pi/validate-tool-use.ts` | After each `write` or `edit`, validates the file in-process (`pi/support/validators.ts`, a port of `hooks/validators/`) and appends suggestions for `SKILL.md`, instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `rules/`), and `docs/specs/` artifacts. Needs no Python; the Python validators in `hooks/` remain for `validate_all.py` and the parity test. |
+| `pi/ttsr.ts` | A port of oh-my-pi's Time Traveling Stream Rules. A Markdown rule in `~/.pi/agent/rules/` or `<project>/.pi/rules/` whose frontmatter has a `condition` regex is watched during the run. A match in streamed assistant text aborts the response, drops it, and retries with the rule injected; a match in tool arguments (the command for `bash`, the new text for `write` and `edit`) blocks the call with the rule as its reason. Frontmatter fields follow oh-my-pi: `condition`, `scope` (`text`, `thinking`, `tool`, `tool:bash`, `tool:edit(*.ts)`), `globs`, and `interruptMode` (`always`, `prose-only`, `tool-only`, `never`), plus `repeatMode` (`once` or `after-gap`) and `repeatGap`. A rule fires once per session by default. `astCondition`, `question`, and `agents` are not supported; a rule that uses them is skipped and reported. `/ttsr` lists the loaded rules. |
+
+## Install
+
+Install the npm package `pi-anchorloop`; it is the recommended way to use anchorloop:
+
+```bash
+pi install npm:pi-anchorloop
+```
+
+A local checkout loads in place, so edits take effect on `/reload`:
+
+```bash
+pi install /path/to/anchorloop
+```
+
+## Develop
+
+```bash
+uv run python hooks/validate_all.py .   # skills, rules, and durable specs
+uv run --with pytest pytest -q          # validators and the pi extensions (needs node)
+```
+
+## Acknowledgments
+
+- [pstack](https://github.com/backnotprop/pstack) by Lauren Tan (MIT), mirror revision `e44668c` of [cursor/plugins](https://github.com/cursor/plugins/tree/main/pstack), and its port [pstack-claude](https://github.com/michael-denyer/pstack-claude) by Michael Denyer (MIT): task-type playbooks, named principles, the lifecycle playbooks, the decision trail, the closed review gate, fresh-subagent hand-off, and evidence grades.
+- [google-research/harness2](https://github.com/google-research/harness2) (Apache-2.0), revision `1cfe254`: solid-loop's placement test, cheapest-mechanism order, and declining a lesson without a before/after contrast.
+- [mattpocock/skills](https://github.com/mattpocock/skills) (MIT): grilling, domain-modeling, the diff review, the prototype playbook, and the feature playbook's interface checks.
+- [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) (Apache-2.0), revision `bad48a0`: the terse voice in `agent-terse`.
+- HumanLayer's [show-me](https://github.com/humanlayer/skills/tree/main/plugins/show-me) (MIT): the views in `answering`.
+- [oh-my-pi](https://github.com/can1357/oh-my-pi): Time Traveling Stream Rules.
+
+Ported files credit their sources in their own footers.

package/README.zh-TW.md

@@ -0,0 +1,64 @@
+# pi-anchorloop
+
+[English](README.md)
+
+給 [pi](https://github.com/earendil-works/pi) 用的 agent 工作流程 skill 和循環 extension。每一種主要任務都從自己的 skill 進來，選一本 playbook，然後跑同一個循環：**Align → Anchor → Act → Verify**。
+
+## Skill
+
+```text
+anchorloop            核心循環 · 原則 · playbook：autonomous-run、pause、pickup
+├─ answering     explain · compare
+├─ investigating research · diagnose
+├─ inspecting    diff-review · qa-release
+├─ coding        bug-fix · feature · refactoring · perf · prototype（+ Mini SDD）
+├─ writing       draft · tighten · comments
+└─ solid-loop    apply-friction · author-skill · bootstrap
+共用             grilling · domain-modeling · human-feedback · agent-terse
+```
+
+- **`anchorloop`** 放每一種任務都成立的做法：重述任務、選入口的 playbook 並把步驟抄進 `todo`、第一筆修改前寫出 `Reality anchor:`、以小步前進且先刪後加、依 anchor 驗證，並記下 friction note。Reflexive pass 會把 friction note 交給 `solid-loop`。`PRINCIPLES.md` 列出 playbook 引用的原則，使用者也可以用這些名稱中途修正方向。三本生命週期 playbook 處理無人看管的執行、乾淨的暫停，以及接手前一輪的工作。
+- **入口 skill** 各自寫出這類任務的 anchor，並列出自己的 playbook。每本 playbook 先用一句話說明它負責什麼，接著是編號步驟，最後一行 `Reply:` 規定回報要包含什麼。
+- **共用 skill** 由入口呼叫：`grilling` 處理使用者要做的決定，`domain-modeling` 處理術語和 ADR，`human-feedback` 處理對成品的反應，`agent-terse` 處理只給 agent 讀的文字：任務 brief、回報、agent 之間的訊息。
+
+## Extension
+
+| 檔案 | 作用 |
+| --- | --- |
+| `pi/anchor-gate.ts` | 使用者最新一則訊息之後，assistant 還沒寫出 `Reality anchor:` 就執行 `write` 或 `edit` 時，每則訊息顯示一次警告，但不擋下呼叫。`.md`、`.txt`、`.html` 檔、`scratch/`、`docs/specs/` 和專案外的暫存檔不警告。透過 `bash` 改檔不在檢查範圍內。 |
+| `pi/decision-tool.ts` | `anchorloop_decision` 工具把一筆決策寫進 TSV 決策軌跡，每筆只佔一行，用試算表開啟也安全；接手別人的軌跡時寫一筆 `start`。 |
+| `pi/second-thought.ts` | 呼叫過 `write`、`edit` 或 `bash` 的執行結束前，透過 pi 的 classifier registry 問 Jev（TypeSafe 的型別化決策模型）：最後的回覆有沒有證明需求已達成、需要哪一級 review、品質如何。Jev 也會判斷這則回覆是不是提醒點，也就是把工作交回給使用者的地方；只是確認收到、回報進度或等待中的回覆不提醒。在提醒點上，quality < 1.5 或 review 是 `full` 時，加一則看得到的提醒並讓 agent 多跑一輪，每輪最多一次；agent 可以不同意，直接結束。只有 done < 0.25 時，只顯示提醒，不多跑一輪。需求是使用者最新打的訊息；extension 送進來的訊息（intercom、monitor 喚醒）不會取代它。由這類訊息開始的那一輪，會連同 `trigger: wake` 和那則訊息一起送出，依那則訊息要求的事評估；這時的提醒點問題會多說明：回覆喚醒訊息要求的例行檢查（狀態、健康、負載、還在跑的工作進度）不算提醒點。呼叫過 `MonitorCreate`、`LoopCreate`、`goal_wait` 或 `subagent` 類工具的執行是在等喚醒，不評估。只送出需求、trigger、喚醒訊息和最後的回覆。沒有 TypeSafe key 時記為 `unknown`，不做任何事。在 subagent session 裡（pi-herdr-agents 的 `PI_SUBAGENT_ID`，或 pi-subagents 的 `PI_SUBAGENT_CHILD`）完全不啟用，結果交給派出它的 agent 判斷。 |
+| `pi/validate-tool-use.ts` | 每次 `write` 或 `edit` 後在行程內驗證該檔（`pi/support/validators.ts`，移植自 `hooks/validators/`），替 `SKILL.md`、指令檔（`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`rules/`）和 `docs/specs/` 產出物附上建議。不需要 Python；`hooks/` 的 Python 驗證器仍供 `validate_all.py` 和對照測試使用。 |
+| `pi/ttsr.ts` | 移植自 oh-my-pi 的 Time Traveling Stream Rules。`~/.pi/agent/rules/` 或 `<專案>/.pi/rules/` 裡 frontmatter 帶有 `condition` regex 的 Markdown 規則，會在執行過程中被監看。assistant 串流文字命中時，中斷回應、丟棄那段輸出，並注入規則後重試；工具參數命中時（`bash` 看指令，`write`／`edit` 看新寫入的文字），直接擋下呼叫，以規則內容作為理由。frontmatter 欄位沿用 oh-my-pi：`condition`、`scope`（`text`、`thinking`、`tool`、`tool:bash`、`tool:edit(*.ts)`）、`globs`、`interruptMode`（`always`、`prose-only`、`tool-only`、`never`），另加 `repeatMode`（`once` 或 `after-gap`）與 `repeatGap`。預設每條規則每個 session 只觸發一次。不支援 `astCondition`、`question`、`agents`，用到的規則會被跳過並回報。`/ttsr` 列出已載入的規則。 |
+
+## 安裝
+
+建議安裝 npm 套件 `pi-anchorloop` 來使用 anchorloop：
+
+```bash
+pi install npm:pi-anchorloop
+```
+
+本機 checkout 會直接載入，改完 `/reload` 就生效：
+
+```bash
+pi install /path/to/anchorloop
+```
+
+## 開發
+
+```bash
+uv run python hooks/validate_all.py .   # 檢查 skill、規則與 durable spec
+uv run --with pytest pytest -q          # 驗證器與 pi extension 的測試（需要 node）
+```
+
+## 致謝
+
+- Lauren Tan 的 [pstack](https://github.com/backnotprop/pstack)（MIT），鏡像 repo 的版本 `e44668c`，上游是 [cursor/plugins](https://github.com/cursor/plugins/tree/main/pstack)；以及 Michael Denyer 的移植版 [pstack-claude](https://github.com/michael-denyer/pstack-claude)（MIT）：依任務類型分的 playbook、具名原則、生命週期 playbook、決策軌跡、獨立審查前不放行的關卡、交接給新 subagent，以及證據分級。
+- [google-research/harness2](https://github.com/google-research/harness2)（Apache-2.0），版本 `1cfe254`：solid-loop 的放置判斷、最便宜機制的順序，以及沒有前後對照就不寫成教訓。
+- [mattpocock/skills](https://github.com/mattpocock/skills)（MIT）：grilling、domain-modeling、diff review、prototype playbook，以及 feature playbook 的介面檢查。
+- [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)（Apache-2.0），revision `bad48a0`：`agent-terse` 的精簡寫法。
+- HumanLayer 的 [show-me](https://github.com/humanlayer/skills/tree/main/plugins/show-me)（MIT）：`answering` 的呈現方式。
+- [oh-my-pi](https://github.com/can1357/oh-my-pi)：Time Traveling Stream Rules。
+
+移植來的檔案在各自的頁尾註明出處。

package/hooks/validate_tool_use.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Validator entrypoint called by the pi extension in pi/validate-tool-use.ts.
+
+Reads {"tool_input": {"file_path": ...}, "cwd": ...} on stdin, validates the
+edited file against skill compactness, direct expected behavior, and durable
+review standards, and prints {"additionalContext": ...} when it has advice.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from validators.durable_validator import check_durable_spec
+from validators.rule_validator import check_rules_file
+from validators.skill_validator import check_skill_advisories, check_skill_md
+from validators.utils import extract_file_path_from_payload
+
+
+def run_validation(path: Path) -> list[str]:
+    """Route file to appropriate validator based on path and filename."""
+    warnings: list[str] = []
+    name = path.name.lower()
+    path_str = str(path).replace("\\", "/")
+
+    # 1. SKILL.md
+    if name == "skill.md":
+        warnings.extend(check_skill_md(path))
+        warnings.extend(check_skill_advisories(path))
+
+    # 2. Rule and instruction files
+    elif name in ("agents.md", "claude.md", "gemini.md") or "/rules/" in path_str:
+        warnings.extend(check_rules_file(path))
+
+    # 3. Durable spec artifacts
+    elif "/docs/specs/" in path_str and name.endswith(".md"):
+        warnings.extend(check_durable_spec(path))
+
+    return warnings
+
+
+def main() -> None:
+    try:
+        raw_input = sys.stdin.read()
+        if not raw_input.strip():
+            sys.exit(0)
+        data = json.loads(raw_input)
+    except Exception:
+        # Never block execution if input parsing fails
+        sys.exit(0)
+
+    try:
+        file_path_str = extract_file_path_from_payload(data)
+        if not file_path_str:
+            print(json.dumps({}))
+            sys.exit(0)
+
+        cwd_str = data.get("cwd", "")
+        cwd = Path(cwd_str) if cwd_str else Path.cwd()
+        target_path = Path(file_path_str)
+        if not target_path.is_absolute():
+            target_path = cwd / target_path
+
+        if not target_path.exists():
+            print(json.dumps({}))
+            sys.exit(0)
+
+        warnings = run_validation(target_path)
+        if warnings:
+            try:
+                rel = target_path.relative_to(cwd)
+            except ValueError:
+                rel = target_path
+
+            lines = "\n".join(f"  - {w}" for w in warnings)
+            msg = f"⚠ [anchorloop] Validation suggestions for {rel}:\n{lines}"
+            print(json.dumps({"additionalContext": msg}))
+        else:
+            print(json.dumps({}))
+
+    except Exception as e:
+        sys.stderr.write(f"anchorloop hook error: {e}\n")
+        print(json.dumps({}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/validators/__init__.py

@@ -0,0 +1 @@
+"""Anchorloop validators package."""

package/hooks/validators/constants.py

@@ -0,0 +1,47 @@
+"""Constants for skill, rule, and durable spec validation."""
+
+# Allowed fields in SKILL.md YAML frontmatter
+SKILL_ALLOWED_FIELDS = frozenset({"name", "description"})
+
+# Maximum recommended lines for a self-contained SKILL.md before progressive disclosure (official standard: 300 lines)
+SKILL_MAX_RECOMMENDED_LINES = 300
+
+# Defensive phrasing patterns to discourage (encourage stating expected behavior directly)
+DEFENSIVE_PATTERNS = [
+    r"never under any circumstances",
+    r"under no circumstances",
+    r"you must never ever",
+    r"do not under any condition",
+    r"strict red line",
+    r"absolute red line",
+    r"prohibited at all costs",
+    r"zero tolerance for any",
+    r"absolutely forbidden to ever",
+    r"無限多的紅線",
+    r"千萬不要",
+    r"嚴禁在任何情況下",
+    r"絕對不可",
+]
+
+# Red-line advisories: markers are counted against a budget of max(MIN_BUDGET, lines * DENSITY).
+# Existing skills peak at 0.067 markers per line, so the budget fires only on clear inflation.
+RED_LINE_MARKERS = (
+    r"\b(never|must not|do not|don't|forbidden|barred|prohibited|avoid)\b"
+    r"|不要|禁止|不得|不准|嚴禁"
+)
+RED_LINE_MIN_BUDGET = 3
+RED_LINE_DENSITY = 0.10
+# Emphatic capitals are matched case-sensitively and need a reason on the same or next line.
+EMPHATIC_WORDS = r"\b(NEVER|ALWAYS|MUST NOT|MUST|FORBIDDEN|DO NOT)\b"
+REASON_WORDS = r"\b(because|otherwise|so that|since)\b|否則|因為|以免"
+
+# Essential core rules to check during durable pre-flight
+CORE_RULES = [
+    "Traditional Chinese communication",
+    "English instructions and prompts",
+    "Direct statement of expected behavior without defensive phrasing",
+    "Anchorloop reality anchor named before first production edit",
+]
+
+# Standard verification result states
+VALID_VERIFICATION_RESULTS = {"pass", "fail", "unknown"}

package/hooks/validators/durable_validator.py

@@ -0,0 +1,89 @@
+"""Validator for Durable artifacts and reviews in docs/specs/*/."""
+
+import re
+from pathlib import Path
+
+from .constants import DEFENSIVE_PATTERNS, VALID_VERIFICATION_RESULTS
+from .utils import find_defensive_phrases
+
+
+def check_decision_md(path: Path) -> list[str]:
+    """Check decision.md for required structure and pre-flight skill/rule readiness."""
+    warnings: list[str] = []
+    text = path.read_text(encoding="utf-8")
+
+    # Check for decision table
+    if not re.search(r"\|\s*Question\s*\|\s*Answer\s*\|\s*Basis\s*\|\s*Status\s*\|", text, re.IGNORECASE):
+        warnings.append("decision.md should include a Question | Answer | Basis | Status table.")
+
+    # Check for pre-flight readiness (core rules)
+    lower = text.lower()
+    if "rule" not in lower and "readiness" not in lower and "prerequisite" not in lower and "core" not in lower:
+        warnings.append(
+            "confirm core rules readiness before implementation; note readiness in decision.md."
+        )
+
+    return warnings
+
+
+def check_spec_md(path: Path) -> list[str]:
+    """Check spec.md for approval status and reality anchor definition."""
+    warnings: list[str] = []
+    text = path.read_text(encoding="utf-8")
+
+    # Status header
+    if not re.search(r"Status:\s*(proposed|approved)", text, re.IGNORECASE):
+        warnings.append("spec.md must declare 'Status: proposed' or 'Status: approved' at the top.")
+
+    # Reality anchor declaration
+    if "reality anchor" not in text.lower() and "anchor" not in text.lower():
+        warnings.append("spec.md should name the chosen reality anchor and its checkpoint.")
+
+    return warnings
+
+
+def check_verification_md(path: Path) -> list[str]:
+    """Check verification.md for standard evidence rows and adjustment-focused reviews."""
+    warnings: list[str] = []
+    text = path.read_text(encoding="utf-8")
+
+    # 1. Standard Requirement | Evidence | Result table
+    table_match = re.search(r"\|\s*Requirement\s*\|\s*Evidence\s*\|\s*Result\s*\|", text, re.IGNORECASE)
+    if not table_match:
+        warnings.append(
+            "verification.md must include a 'Requirement | Evidence | Result' table."
+        )
+    else:
+        # Check that results use valid states (excluding the table header)
+        result_rows = re.findall(r"\|\s*[^|]+\s*\|\s*[^|]+\s*\|\s*([a-zA-Z]+)\s*\|", text)
+        invalid_results = [
+            r.lower() for r in result_rows 
+            if r.lower() not in VALID_VERIFICATION_RESULTS and r.lower() != "result"
+        ]
+        if invalid_results:
+            warnings.append(
+                f"invalid verification Result values found: {', '.join(set(invalid_results))}. "
+                "Result must be one of: pass, fail, unknown."
+            )
+
+    # 2. Review of newly added rules or skills (tuning vs defensive vocabulary)
+    found_defensive = find_defensive_phrases(text, DEFENSIVE_PATTERNS)
+    if found_defensive:
+        warnings.append(
+            f"detected defensive wording in verification/review: {', '.join(found_defensive)}. "
+            "Reviews of new rules and skills must focus on adjustment and tuning, not adding defensive red lines."
+        )
+
+    return warnings
+
+
+def check_durable_spec(path: Path) -> list[str]:
+    """Route durable spec file to specific validator."""
+    name = path.name.lower()
+    if name == "decision.md" or name == "requirements.md":
+        return check_decision_md(path)
+    elif name == "spec.md":
+        return check_spec_md(path)
+    elif name == "verification.md":
+        return check_verification_md(path)
+    return []

package/hooks/validators/rule_validator.py

@@ -0,0 +1,42 @@
+"""Validator for rule and instruction files (AGENTS.md, CLAUDE.md, rules/*.md, rules/*.rules)."""
+
+from pathlib import Path
+
+from .constants import DEFENSIVE_PATTERNS
+from .utils import find_defensive_phrases
+
+
+def check_rules_file(path: Path) -> list[str]:
+    """Check rule files for direct expected behavior and anti-bloat."""
+    warnings: list[str] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception as e:
+        return [f"failed to read rule file: {e}"]
+
+    # 1. Defensive phrasing detection
+    found_patterns = find_defensive_phrases(text, DEFENSIVE_PATTERNS)
+    if found_patterns:
+        warnings.append(
+            f"detected defensive wording: {', '.join(found_patterns)}. "
+            "State desired behavior directly; modern models do not need excessive red lines."
+        )
+
+    # 2. Rule proliferation / bloat check
+    lines = [line.strip() for line in text.splitlines() if line.strip() and not line.strip().startswith("#")]
+    if len(lines) > 200:
+        warnings.append(
+            f"rule file has {len(lines)} non-empty lines. Consider consolidating into higher-level principles "
+            "or separating into specialized modules rather than accumulating micro-rules."
+        )
+
+    # 3. Check for Simplified Chinese common distinctive characters
+    # (Simple heuristic check for characters exclusively used in Simplified Chinese)
+    simplified_chinese_chars = "为这就从时会过发对门书见长经说样开"
+    found_sc = [c for c in simplified_chinese_chars if c in text]
+    if found_sc:
+        warnings.append(
+            f"possible Simplified Chinese detected ({''.join(found_sc[:5])}). Always use Traditional Chinese."
+        )
+
+    return warnings

package/hooks/validators/skill_validator.py

@@ -0,0 +1,144 @@
+"""Validator for SKILL.md files focusing on compactness and direct expected behavior."""
+
+import re
+from collections import Counter
+from pathlib import Path
+
+from .constants import (
+    DEFENSIVE_PATTERNS,
+    EMPHATIC_WORDS,
+    REASON_WORDS,
+    RED_LINE_DENSITY,
+    RED_LINE_MARKERS,
+    RED_LINE_MIN_BUDGET,
+    SKILL_ALLOWED_FIELDS,
+    SKILL_MAX_RECOMMENDED_LINES,
+)
+from .utils import (
+    extract_markdown_links,
+    find_defensive_phrases,
+    parse_frontmatter,
+    strip_code,
+)
+
+
+def check_skill_md(path: Path) -> list[str]:
+    """Run streamlining and standardization checks on a SKILL.md file."""
+    warnings: list[str] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception as e:
+        return [f"failed to read SKILL.md: {e}"]
+
+    skill_dir = path.parent
+    lines = text.splitlines()
+
+    # 1. Frontmatter check
+    fields = parse_frontmatter(text)
+    if fields is None:
+        warnings.append("missing or invalid YAML frontmatter (--- ... ---)")
+    else:
+        extra_fields = sorted(set(fields.keys()) - SKILL_ALLOWED_FIELDS)
+        if extra_fields:
+            warnings.append(f"extra frontmatter fields: {', '.join(extra_fields)}")
+
+        if "name" not in fields or not fields["name"].strip():
+            warnings.append("missing required frontmatter field: 'name'")
+
+        # The regex parser accepts what pi's YAML parser rejects, and pi then skips the whole skill.
+        for key in ("name", "description"):
+            raw = next((line.split(":", 1)[1].strip() for line in lines[1:] if line.startswith(f"{key}:")), "")
+            if raw and raw[0] not in "\"'|>" and (": " in raw or " #" in raw):
+                warnings.append(f"quote the {key}: YAML reads an unquoted ': ' or ' #' as syntax, and pi skips the skill")
+
+        if "description" not in fields or not fields["description"].strip():
+            warnings.append("missing required frontmatter field: 'description'")
+        else:
+            desc = fields["description"]
+            if "use when" not in desc.lower():
+                warnings.append("description should specify trigger criteria (include 'Use when...')")
+
+    # 2. Compactness check (streamlined skills)
+    if len(lines) > SKILL_MAX_RECOMMENDED_LINES:
+        has_references = (skill_dir / "references").is_dir()
+        if not has_references:
+            warnings.append(
+                f"skill has {len(lines)} lines (exceeds recommended {SKILL_MAX_RECOMMENDED_LINES}). "
+                "Move detailed guidelines or templates to references/ to keep SKILL.md streamlined."
+            )
+
+    # 3. Broken markdown links, followed through every Markdown file SKILL.md reaches
+    root = skill_dir.resolve()
+    reached: dict[Path, str] = {path.resolve(): text}
+    linked: set[Path] = set()
+    pending = [path.resolve()]
+    while pending:
+        source = pending.pop()
+        for link in extract_markdown_links(reached[source]):
+            target = (source.parent / link).resolve()
+            if not target.exists():
+                where = "" if source == path.resolve() else f" (in {source.relative_to(root).as_posix()})"
+                warnings.append(f"broken local link: {link}{where}")
+                continue
+            linked.add(target)
+            if target.suffix == ".md" and target.is_relative_to(root) and target not in reached:
+                reached[target] = target.read_text(encoding="utf-8")
+                pending.append(target)
+
+    # 4. Orphaned files check
+    corpus = "\n".join(reached.values())
+    for f in skill_dir.rglob("*"):
+        if f == path or f.is_dir():
+            continue
+        rel = f.relative_to(skill_dir).as_posix()
+        if not (f.resolve() in linked or rel in corpus or f.name in corpus):
+            warnings.append(f"orphaned file not referenced in SKILL.md: {rel}")
+
+    # 5. Defensive phrasing check
+    found_patterns = find_defensive_phrases(text, DEFENSIVE_PATTERNS)
+    if found_patterns:
+        warnings.append(
+            f"detected defensive anti-pattern(s): {', '.join(found_patterns)}. "
+            "State expected behavior directly rather than constructing defensive red lines."
+        )
+
+    return warnings
+
+
+def check_skill_advisories(path: Path) -> list[str]:
+    """Red-line advisories for the author; they never count as validation failures."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        return []
+
+    body = strip_code(text)
+    lines = body.splitlines()
+    advisories: list[str] = []
+
+    # 1. Budget: red lines are earned by an observed failure, so their count stays small.
+    markers = len(re.findall(RED_LINE_MARKERS, body, re.IGNORECASE))
+    budget = max(RED_LINE_MIN_BUDGET, int(sum(1 for line in lines if line.strip()) * RED_LINE_DENSITY))
+    if markers > budget:
+        advisories.append(
+            f"{markers} red-line markers exceed the budget of {budget}. Keep a red line only when an "
+            "observed failure backs it, and delete the rest."
+        )
+
+    # 2. Reasoned: an emphatic word carries its reason on the same or next line.
+    # 3. Once: an emphatic word is spent a single time.
+    seen: Counter[str] = Counter()
+    for number, line in enumerate(lines, start=1):
+        for word in re.findall(EMPHATIC_WORDS, line):
+            seen[word] += 1
+            window = " ".join(lines[number - 1 : number + 1])
+            if not re.search(REASON_WORDS, window, re.IGNORECASE):
+                advisories.append(
+                    f"line {number}: emphatic '{word}' has no reason beside it. "
+                    "State the consequence, or drop the emphasis."
+                )
+    for word, count in seen.items():
+        if count > 1:
+            advisories.append(f"emphatic '{word}' appears {count} times. Spend emphasis once, on the rule that causes real damage.")
+
+    return advisories

package/hooks/validators/utils.py

@@ -0,0 +1,71 @@
+"""Utility functions for validators."""
+
+import re
+
+
+def parse_frontmatter(text: str) -> dict[str, str] | None:
+    """Parse YAML frontmatter from markdown text using regex."""
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end == -1:
+        return None
+    block = text[3:end].strip()
+    result: dict[str, str] = {}
+    current_key = None
+    current_val: list[str] = []
+
+    for line in block.splitlines():
+        if not line.strip() or line.strip().startswith("#"):
+            continue
+        # Check for top-level key: value
+        match = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
+        if match and not line.startswith(" "):
+            if current_key is not None:
+                result[current_key] = "\n".join(current_val).strip().strip("\"'")
+            current_key = match.group(1)
+            raw_val = match.group(2).strip()
+            current_val = [raw_val] if raw_val else []
+        elif current_key is not None:
+            current_val.append(line.strip())
+
+    if current_key is not None:
+        result[current_key] = "\n".join(current_val).strip().strip("\"'")
+
+    return result
+
+
+def extract_markdown_links(text: str) -> list[str]:
+    """Extract local markdown link targets [label](target)."""
+    # Strip inline code and fenced code blocks
+    stripped = re.sub(r"```[\s\S]*?```", "", text)
+    stripped = re.sub(r"`[^`\n]+`", "", stripped)
+    # Match markdown links: [label](target)
+    matches = re.findall(r"\[(?:[^\]]*)\]\(([^)#\s]+)(?:#[^)]*)?\)", stripped)
+    # Filter out web URLs, mailto, etc.
+    local_links = [m for m in matches if not re.match(r"^[a-zA-Z]+://", m) and not m.startswith("mailto:")]
+    return local_links
+
+
+def strip_code(text: str) -> str:
+    """Blank out fenced and inline code while keeping line numbers stable."""
+    stripped = re.sub(r"```[\s\S]*?```", lambda m: "\n" * m.group(0).count("\n"), text)
+    return re.sub(r"`[^`\n]+`", "", stripped)
+
+
+def find_defensive_phrases(text: str, patterns: list[str]) -> list[str]:
+    """Find defensive phrasing anti-patterns outside code blocks."""
+    stripped = strip_code(text)
+    found: list[str] = []
+    for pattern in patterns:
+        if re.search(pattern, stripped, re.IGNORECASE):
+            found.append(pattern)
+    return found
+
+
+def extract_file_path_from_payload(payload: dict) -> str | None:
+    """Extract the edited file path from the pi extension payload's tool_input.file_path."""
+    tool_input = payload.get("tool_input", {})
+    if isinstance(tool_input, dict) and tool_input.get("file_path"):
+        return str(tool_input["file_path"])
+    return None