@tw93/waza 3.25.0 → 3.28.0

package/scripts/skill_checks.py

@@ -25,10 +25,32 @@ URL_PREFIXES = ("http://", "https://", "mailto:", "ftp://", "tel:", "data:")
 SEP_RE = re.compile(r'^[\s|:\-]+$')
 PERSONAL_PATH_PATTERN = re.compile(r'/(?:Users|home)/[A-Za-z0-9._-]+/')
 SKILL_REF_RE = re.compile(r'skills/([a-z][a-z0-9_-]*)/SKILL\.md')
+# Quoted user-utterance triggers in rules/waza-routing.md. Covers straight ("),
+# curly (U+201C/D), and CJK corner brackets (「」 U+300C/D, 『』 U+300E/F) so a
+# Chinese phrase in 「」 is checked just like one in straight quotes.
+QUOTED_PHRASE_RE = re.compile(
+    r'"([^"]+)"'
+    r'|\u201c([^\u201d]+)\u201d'
+    r'|\u300c([^\u300d]+)\u300d'
+    r'|\u300e([^\u300f]+)\u300f'
+)
+PROJECT_RITUAL_RE = re.compile(r'\b(?:Sparkle|MAS|Homebrew tap|Xcode scheme)\b', re.IGNORECASE)
+PRIVATE_CONTEXT_RE = re.compile(
+    r'(?:\.codex/(?:sessions|memories)|rollout_summaries/|'
+    r'thread_id|rollout_path|session_meta|owner/private-repo|'
+    r'private[-_/](?:repo|project|tool)|internal[-_/](?:repo|project|tool))',
+    re.IGNORECASE,
+)
+FORCED_GITHUB_TOOL_RE = re.compile(
+    r'(?:Use\s+`?gh`?\s+CLI\s+for\s+all\s+GitHub\s+interactions|'
+    r'for\s+all\s+GitHub\s+interactions,\s+not\s+MCP\s+or\s+raw\s+API)',
+    re.IGNORECASE,
+)
 
 DURABLE_CONTEXT_SKILLS = {"think", "check", "hunt", "design", "write", "health"}
 
 NINJA_PREFIX = "Prefix your first line with 🥷 inline, not as its own paragraph."
+OUTCOME_CONTRACT_FIELDS = ("Outcome:", "Done when:", "Evidence:", "Output:")
 
 # Attribution strings that indicate AI co-authorship leaked into tracked files.
 ATTRIBUTION_PATTERNS = (
@@ -226,6 +248,26 @@ def check_description_conformance(skill_descriptions: dict[str, str]):
         print(f"ok: description {skill} ({length} chars)")
 
 
+def check_outcome_contract(skill_files: list[Path]):
+    """Keep skill entrypoints outcome-first instead of process-heavy."""
+    for path in skill_files:
+        text = path.read_text()
+        if "## Outcome Contract" not in text:
+            fail(
+                f"MISSING OUTCOME CONTRACT: {path}\n"
+                f"  Skill entrypoints must name outcome, done state, evidence, and output before detailed workflow."
+            )
+        section = text.split("## Outcome Contract", 1)[1]
+        section = section.split("\n## ", 1)[0]
+        missing = [field for field in OUTCOME_CONTRACT_FIELDS if field not in section]
+        if missing:
+            fail(
+                f"INCOMPLETE OUTCOME CONTRACT: {path}\n"
+                f"  Missing fields: {', '.join(missing)}"
+            )
+        print(f"ok: outcome contract {path.parent.name}")
+
+
 def check_durable_context_and_paths(root: Path, skill_files: list[Path]):
     """Durable context rules must stay portable and evidence-bound.
 
@@ -283,6 +325,53 @@ def check_durable_context_and_paths(root: Path, skill_files: list[Path]):
         print(f"ok: durable context preflight for {skill}")
 
 
+def check_portable_skill_surface(root: Path, markdown_paths: list[Path]):
+    """Guard Waza's public skill surface against private/project-specific drift.
+
+    Waza skills should teach transferable workflow behavior. Project-specific
+    release rituals and platform products are warning signals, while
+    one-machine paths and platform-forcing commands are hard portability failures.
+    """
+    scan_paths = list(markdown_paths)
+    scan_paths.extend(sorted((root / "rules").glob("*.md")))
+    agents = root / "AGENTS.md"
+    if agents.exists():
+        scan_paths.append(agents)
+
+    seen: set[Path] = set()
+    warning_paths: list[str] = []
+    for path in scan_paths:
+        if path in seen or not path.exists():
+            continue
+        seen.add(path)
+        rel = path.relative_to(root)
+        text = path.read_text()
+        if "~/Downloads" in text:
+            fail(
+                f"NON-PORTABLE DEFAULT SAVE PATH: {rel}\n"
+                f"  Use a user-specified directory, project scratch path, or session temp directory."
+            )
+        if FORCED_GITHUB_TOOL_RE.search(text):
+            fail(
+                f"FORCED GITHUB TOOLING IN GENERIC SURFACE: {rel}\n"
+                f"  GitHub projects may prefer gh, but Waza must derive platform tools from project context."
+            )
+        if PRIVATE_CONTEXT_RE.search(text):
+            fail(
+                f"PRIVATE PROJECT OR SESSION CONTEXT IN PORTABLE SURFACE: {rel}\n"
+                f"  Public skills and rules must not copy private project names, session paths, "
+                f"memory paths, rollout metadata, support vendors, or thread identifiers."
+            )
+        if PROJECT_RITUAL_RE.search(text):
+            warning_paths.append(rel.as_posix())
+    if warning_paths:
+        print(
+            "warn: project-specific names or platform products in portable surface "
+            f"({', '.join(warning_paths[:8])})"
+        )
+    print("ok: portable skill surface")
+
+
 def check_resolver(root: Path, skill_names: set[str]):
     """Every skill must be referenced from skills/RESOLVER.md.
 
@@ -390,7 +479,13 @@ def check_no_root_skill(root: Path):
 def check_rules_files_present(root: Path):
     """Required shared rule files outside skills/ that the per-skill ref check
     doesn't cover."""
-    required = ["english.md", "chinese.md", "anti-patterns.md", "durable-context.md"]
+    required = [
+        "english.md",
+        "chinese.md",
+        "anti-patterns.md",
+        "durable-context.md",
+        "waza-routing.md",
+    ]
     for name in required:
         path = root / "rules" / name
         if not path.exists():
@@ -398,6 +493,139 @@ def check_rules_files_present(root: Path):
     print(f"ok: rules/ files present ({', '.join(required)})")
 
 
+def check_anti_patterns_contract(root: Path):
+    """Keep shared anti-pattern rules generic and mechanically sane."""
+    path = root / "rules" / "anti-patterns.md"
+    if not path.exists():
+        fail(f"MISSING ANTI-PATTERNS: expected {path}")
+
+    text = path.read_text()
+    if re.search(r"\bWaza\b", text):
+        fail(
+            "ANTI-PATTERN PROJECT NAME LEAK: rules/anti-patterns.md\n"
+            "  Anti-pattern rules are shared behavior. Keep row wording generic, "
+            "without repo or product names."
+        )
+
+    stale_terms = (
+        "Private rule leak",
+        "Project fact promoted to global skill",
+        "public Waza rules",
+        "reusable Waza skill",
+        "Keep Waza generic",
+    )
+    for term in stale_terms:
+        if term in text:
+            fail(
+                f"ANTI-PATTERN STALE SPECIALIZATION: {term!r}\n"
+                "  Merge private-context and project-fact cases into one generic public-surface rule."
+            )
+
+    rows: list[tuple[int, str]] = []
+    for line in text.splitlines():
+        if not line.startswith("| ") or line.startswith("|---"):
+            continue
+        cells = [cell.strip() for cell in line.strip("|").split("|")]
+        if not cells or not cells[0].isdigit():
+            continue
+        rows.append((int(cells[0]), cells[1] if len(cells) > 1 else ""))
+
+    expected_numbers = list(range(1, len(rows) + 1))
+    actual_numbers = [number for number, _pattern in rows]
+    if actual_numbers != expected_numbers:
+        fail(
+            "ANTI-PATTERN NUMBERING DRIFT: rules/anti-patterns.md\n"
+            f"  Expected contiguous numbering {expected_numbers}; got {actual_numbers}."
+        )
+
+    pattern_names: dict[str, int] = {}
+    for number, pattern in rows:
+        key = pattern.lower()
+        if key in pattern_names:
+            fail(
+                "ANTI-PATTERN DUPLICATE NAME: rules/anti-patterns.md\n"
+                f"  Rows {pattern_names[key]} and {number} both use {pattern!r}."
+            )
+        pattern_names[key] = number
+
+    print("ok: anti-patterns contract")
+
+
+def check_waza_routing_skills(root: Path, skill_names: set[str]):
+    """rules/waza-routing.md routing table must enumerate exactly the skills
+    under skills/. Structural drift only -- trigger phrases stay hand-tuned."""
+    path = root / "rules" / "waza-routing.md"
+    if not path.exists():
+        return
+    listed: set[str] = set()
+    for line in path.read_text().splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.split("|")]
+        if len(cells) < 3:
+            continue
+        name = cells[1]
+        # Skip table header (literal "skill") and separator rows ("---").
+        if name == "skill" or set(name) <= {"-", ":"}:
+            continue
+        if re.fullmatch(r"[a-z][a-z0-9_-]*", name):
+            listed.add(name)
+    missing = skill_names - listed
+    extra = listed - skill_names
+    if missing:
+        fail(
+            "WAZA ROUTING MISSING SKILLS: rules/waza-routing.md table omits: "
+            f"{', '.join(sorted(missing))}"
+        )
+    if extra:
+        fail(
+            "WAZA ROUTING STALE SKILLS: rules/waza-routing.md lists skills "
+            f"not in skills/: {', '.join(sorted(extra))}"
+        )
+    print(f"ok: rules/waza-routing.md skills match ({len(listed)} skills)")
+
+
+def check_waza_routing_triggers(root: Path):
+    """Quoted user-utterance triggers in rules/waza-routing.md must be grounded.
+
+    The routing table's prose stays hand-tuned, but any phrase in quotes is a
+    claim about what a user literally types. Each quoted phrase (split on '/',
+    whitespace-normalized) must appear in the matching skill's when_to_use, so
+    the routing hint can never advertise a trigger no skill actually claims.
+    Unquoted wording is intentionally free and is not checked here.
+    """
+    path = root / "rules" / "waza-routing.md"
+    if not path.exists():
+        return
+    norm = lambda s: re.sub(r"\s+", "", s)  # noqa: E731
+    for line in path.read_text().splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.split("|")]
+        if len(cells) < 3:
+            continue
+        skill = cells[1]
+        if not re.fullmatch(r"[a-z][a-z0-9_-]*", skill):
+            continue
+        skill_md = root / "skills" / skill / "SKILL.md"
+        if not skill_md.exists():
+            continue  # missing skill dir is check_waza_routing_skills' job
+        when = norm(parse_frontmatter(skill_md)["when_to_use"])
+        for match in QUOTED_PHRASE_RE.finditer(cells[2]):
+            quoted = next(g for g in match.groups() if g is not None)
+            for seg in quoted.split("/"):
+                seg_norm = norm(seg)
+                if seg_norm and seg_norm not in when:
+                    fail(
+                        f"WAZA ROUTING UNGROUNDED TRIGGER: rules/waza-routing.md "
+                        f"row '{skill}' quotes {seg!r}, but it is absent from "
+                        f"skills/{skill}/SKILL.md when_to_use.\n"
+                        f"  Quote only phrases a user actually types; align the "
+                        f"phrase with when_to_use or add it to when_to_use."
+                    )
+    print("ok: rules/waza-routing.md quoted triggers grounded")
+
+
 def check_readme_install_command(root: Path):
     """README must show the default install command users can copy-paste."""
     readme = root / "README.md"
@@ -410,7 +638,67 @@ def check_readme_install_command(root: Path):
             f"README INSTALL COMMAND: README.md must include {expected!r}\n"
             f"  Waza's public install path depends on this exact string."
         )
-    print("ok: README installs nested skills")
+    expected_pi = "pi install npm:@tw93/waza"
+    if expected_pi not in text:
+        fail(
+            f"README PI INSTALL COMMAND: README.md must include {expected_pi!r}\n"
+            f"  The Pi package install path depends on this exact string."
+        )
+    expected_agents = {
+        "Antigravity": "npx skills add tw93/Waza -a antigravity -g -y",
+        "Antigravity CLI": "npx skills add tw93/Waza -a antigravity-cli -g -y",
+        "OpenCode": "npx skills add tw93/Waza -a opencode -g -y",
+    }
+    for label, command in expected_agents.items():
+        if command not in text:
+            fail(
+                f"README {label.upper()} INSTALL COMMAND: README.md must "
+                f"include {command!r}\n"
+                f"  Waza's documented agent support depends on this exact string."
+            )
+    expected_installers = {
+        "setup-rule": "https://github.com/tw93/Waza/releases/latest/download/setup-rule.sh",
+        "setup-statusline": "https://github.com/tw93/Waza/releases/latest/download/setup-statusline.sh",
+    }
+    for label, url in expected_installers.items():
+        if url not in text:
+            fail(
+                f"README {label.upper()} URL: README.md must include {url!r}\n"
+                f"  Installer snippets should follow the latest release asset "
+                f"without per-release README churn."
+            )
+    print(
+        "ok: README installs nested skills, Pi package, Antigravity, OpenCode, "
+        "and latest installer assets"
+    )
+
+
+def check_release_workflow_npm_surface(root: Path):
+    """GitHub releases must publish the npm package that Pi consumes."""
+    workflow = root / ".github" / "workflows" / "release.yml"
+    if not workflow.exists():
+        fail(f"MISSING RELEASE WORKFLOW: expected {workflow}")
+    text = workflow.read_text()
+    required = {
+        "npm publish": "publishes @tw93/waza during release",
+        "npm view @tw93/waza": "re-reads the npm registry after publish",
+        "id-token: write": "allows npm trusted publishing through GitHub OIDC",
+        "node-version: 24": "uses a Node/npm runtime that supports trusted publishing",
+        "package-manager-cache: false": "keeps release publish jobs from caching credentials or package state",
+        "github.event.release.tag_name": "checks the GitHub release tag",
+        "package.json').pi.skills[0]": "checks Pi package metadata",
+        "dist-tags.latest": "confirms the npm latest dist-tag",
+        "scripts/setup-rule.sh": "uploads the rule installer as a latest release asset",
+        "scripts/setup-statusline.sh": "uploads the statusline installer as a latest release asset",
+    }
+    missing = [label for label, reason in required.items() if label not in text]
+    if missing:
+        fail(
+            "RELEASE WORKFLOW NPM SURFACE: .github/workflows/release.yml "
+            "must publish and verify @tw93/waza for Pi installs.\n"
+            + "\n".join(f"  missing {label!r}: {required[label]}" for label in missing)
+        )
+    print("ok: release workflow publishes npm package and installer assets")
 
 
 def check_english_coaching_guard(root: Path):

package/scripts/statusline.sh

@@ -88,8 +88,8 @@ read_highwater() {
 
 # apply_hw: compares live vs high-water marks for a single counter (5h or 7d).
 # Mutates four caller-scope globals by name (no return, by design):
-#   applied_pct, applied_reset       — values to render in the statusline now
-#   applied_hw_pct, applied_hw_reset — values to persist back to highwater.json
+#   applied_pct, applied_reset       : values to render in the statusline now
+#   applied_hw_pct, applied_hw_reset : values to persist back to highwater.json
 # Caller must read these immediately after the call; the next invocation
 # clobbers them. Side effect is intentional: bash can't return composite values
 # cleanly, and threading four out-params through every call site was worse.
@@ -132,18 +132,10 @@ apply_hw() {
     applied_hw_reset="$hw_reset"
     return
   fi
-  if [ "$hw_ok" = "0" ] || [ "$live_pct" -gt "$hw_pct" ] 2>/dev/null; then
-    applied_pct="$live_pct"
-    applied_reset="$live_reset"
-    applied_hw_pct="$live_pct"
-    applied_hw_reset="$live_reset"
-    return
-  fi
-
-  applied_pct="$hw_pct"
-  applied_reset="${live_reset:-$hw_reset}"
-  applied_hw_pct="$hw_pct"
-  applied_hw_reset="$hw_reset"
+  applied_pct="$live_pct"
+  applied_reset="$live_reset"
+  applied_hw_pct="$live_pct"
+  applied_hw_reset="$live_reset"
 }
 
 write_highwater() {

package/scripts/validate_package.py

@@ -49,7 +49,7 @@ def main() -> int:
 
     # The packager rewrites `skills/<name>/SKILL.md` references to the inlined
     # section name. Any stragglers indicate a regex bug in the rewriter.
-    for skill in ("check", "think"):
+    for skill in EXPECTED_SKILLS:
         if f"skills/{skill}/SKILL.md" in text:
             print(
                 "POST-PACKAGE ERROR: root SKILL.md still contains nested "

package/scripts/verify_skills.py

@@ -23,6 +23,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from skill_frontmatter import fail  # noqa: E402
 from skill_checks import (  # noqa: E402
+    check_anti_patterns_contract,
     check_attribution_leak,
     check_description_conformance,
     check_durable_context_and_paths,
@@ -30,13 +31,18 @@ from skill_checks import (  # noqa: E402
     check_marketplace,
     check_markdown_links,
     check_no_root_skill,
+    check_outcome_contract,
+    check_portable_skill_surface,
     check_readme_install_command,
+    check_release_workflow_npm_surface,
     check_references,
     check_resolver,
     check_rules_files_present,
     check_skill_files,
     check_table_pipes,
     check_trigger_overlap,
+    check_waza_routing_skills,
+    check_waza_routing_triggers,
     collect_all_md,
 )
 
@@ -65,6 +71,7 @@ def main() -> int:
     skill_files, skill_descriptions, skill_keywords = check_skill_files(root)
     skill_names = set(skill_descriptions)
     check_description_conformance(skill_descriptions)
+    check_outcome_contract(skill_files)
     if (root / "rules" / "durable-context.md").exists():
         check_durable_context_and_paths(root, skill_files)
 
@@ -85,12 +92,17 @@ def main() -> int:
     check_references(root, skill_files)
     resolver_path = check_resolver(root, skill_names)
     all_md = collect_all_md(root, skill_names, resolver_path)
+    check_portable_skill_surface(root, all_md)
     check_markdown_links(root, all_md)
     check_table_pipes(root, all_md)
     check_no_root_skill(root)
     check_trigger_overlap(skill_keywords)
     check_rules_files_present(root)
+    check_anti_patterns_contract(root)
+    check_waza_routing_skills(root, skill_names)
+    check_waza_routing_triggers(root)
     check_readme_install_command(root)
+    check_release_workflow_npm_surface(root)
     check_english_coaching_guard(root)
     check_attribution_leak(root)
     return 0

package/skills/RESOLVER.md

@@ -2,9 +2,9 @@
 
 ## Shared Output Marker
 
-所有技能都沿用同一个输出约定：首行内联带上 `🥷`，不要单独起段。这个约定写在各自的 `SKILL.md` 里，`verify-skills.sh` 也会校验它。
+所有技能都沿用同一个输出约定：首行内联带上 `🥷`，不要单独起段。这个约定写在各自的 `SKILL.md` 里，`scripts/verify_skills.py` 也会校验它。
 
-触发词到技能的路由表。Claude Code 通过每个 SKILL.md 的 `description` 自动匹配，这份文档是给人看的集中索引，也是 `verify-skills.sh` 的校验依据。改 SKILL.md 的适用范围时，同步改这里。
+触发词到技能的路由表。Claude Code 通过每个 SKILL.md 的 `description` 自动匹配，这份文档是给人看的集中索引，也是 `scripts/verify_skills.py` 的校验依据。改 SKILL.md 的适用范围时，同步改这里。
 
 > **Read the skill file before acting.** 两个技能都可能匹配时，两个都读。它们设计成可串联（例：`/think` → 实现 → `/check`）。
 
@@ -38,7 +38,7 @@
 | 触发 | 技能 |
 |------|------|
 | 消息含 http(s) URL / 任何网页链接 / PDF 路径 / "看一下这个", "读一下这个" | `skills/read/SKILL.md` |
-| 写作 / 改稿 / 润色 / 去 AI 味（中英文） / 推特推文 / 社交媒体文案 / launch copy / release notes 文案 | `skills/write/SKILL.md` |
+| 写作 / 改稿 / 润色 / 去 AI 味（中英文） / 本地化文案 / 多语言产品文案 / 推特推文 / 社交媒体文案 / launch copy / release notes 文案 | `skills/write/SKILL.md` |
 | 文档审阅 / 白皮书 / release notes prose 审核 / "审稿" / "check this document" | `skills/write/SKILL.md` (Document Review Mode) |
 | 深度研究一个陌生领域 / 六阶段研究到成稿 / 一批材料沉淀成文章 | `skills/learn/SKILL.md` |
 
@@ -59,19 +59,19 @@
 
 ## Chaining（常见串联）
 
-技能之间的转换需要用户手动触发，不会自动串联。每个技能完成后会停下来，等你决定下一步。
+技能之间默认不自动串联。每个技能完成后会停下来，等用户决定下一步，除非当前请求或项目公开上下文已经明确授权后续动作（例如 "implement this plan", "review then ship if green", "triage and close"）。
 
 - `/think` 出方案 → **用户说"实现"** → 实施 → **用户说"/check"** → `/check` 把关
 - `/think` 出可执行计划 → **用户说"Implement the plan / 可以干 / 直接改"** → 按计划实施，不重新争论方向
 - `/hunt` 修复 issue → **用户说"发布 / push / 关闭 issue"** → `/check` 做发布前检查和收尾
-- `/read` 取回多篇 URL → **用户说"/learn"** → `/learn` 综合成文
+- `/read` 取回多篇 URL → **用户说"/learn"** → `/learn` 综合成文；如果同一回合已经明确要求总结或分析，`/read` fetch 后直接满足该请求
 - `/learn` 出初稿 → **用户说"/write"** → `/write` 去 AI 味
 - `/hunt` 定位根因 → **用户说"修"** → 修完 → **用户说"/check"** → `/check` 确认没副作用
 - `/health` 发现 skill 配置问题 → **用户说"修"** → 修完 → **用户说"/health"** → 再跑一次 `/health`
 
 ## Latent vs Deterministic
 
-Waza 的技能都是 fat skill（Markdown 判断），底层的确定性约束走 `scripts/verify-skills.sh` 和 `rules/*.md`。新加能力时先问：
+Waza 的技能都是 fat skill（Markdown 判断），底层的确定性约束走 `scripts/verify_skills.py` 和 `rules/*.md`。新加能力时先问：
 
 - 需要判断 / 适应场景 / 追问用户？→ skill
 - 同入同出 / 只是校验和列举？→ script 或 rule
@@ -83,8 +83,8 @@ Waza 的技能都是 fat skill（Markdown 判断），底层的确定性约束
 通用程序员能力沉淀在 Waza。遇到具体项目时，先从公开项目上下文提炼约束，再执行对应技能：
 
 - `code-review` / `/check` -> 从 diff、README、manifest、CI、release notes 中提炼验证命令、生成物、风险、safety sinks 和发布规则。
-- `github-ops` -> 复用 `skills/check/SKILL.md` 的 Triage Mode，并从 issue/PR 现场确认 repo、发布状态和回复语言。
-- `release` -> 从项目公开发布文档、脚本和 CI 中确认前置条件、产物和验证命令。
+- GitHub issue/PR/release intents -> 由 `skills/check/SKILL.md` 处理。目标是 GitHub 时优先使用 `gh` 或可用的 GitHub 工具；非 GitHub 平台按项目公开上下文选择对应 CLI/API。
+- Release/publish intents -> 由 `skills/check/SKILL.md` 从项目公开发布文档、脚本和 CI 中确认前置条件、产物和验证命令。
 
 本地 durable memory / preview 可以作为可选私有上下文来理解用户偏好、旧决策和可迁移模式；它不属于公开项目约束，且必须用当前代码、日志、测试、文档或远端状态重新验证。