@tw93/waza 3.25.0

package/scripts/build_metadata.py

@@ -0,0 +1,360 @@
+#!/usr/bin/env python3
+"""Generate Waza distribution metadata from a single source of truth.
+
+Source of truth:
+  - VERSION                            top-level version string (single source)
+  - skills/<name>/SKILL.md frontmatter name, description, dispatch_intent
+
+Generated files:
+  - .claude-plugin/marketplace.json    full plugin manifest
+  - README.md                          install URLs pinned to VERSION
+  - package.json                       npm/Pi package metadata pinned to VERSION
+  - scripts/setup-rule.sh              default WAZA_REF pinned to VERSION
+  - scripts/setup-statusline.sh        default WAZA_REF pinned to VERSION
+
+Modes:
+  --write  (default)  regenerate every file from source
+  --check             compare generated bytes against committed files;
+                      exit non-zero with a diff on mismatch
+
+Run as: python3 scripts/build_metadata.py [--check] [--root PATH]
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+
+from skill_frontmatter import parse_frontmatter  # noqa: E402
+
+
+# Hand-maintained marketplace constants. Kept here (not in frontmatter) because
+# they describe the Waza project itself, not any single skill.
+MARKETPLACE_TOP = {
+    "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+    "name": "waza",
+    "description": (
+        "Personal skill collection for Claude Code and Codex: think, check, "
+        "hunt, design, read, write, learn, and health for agent config and "
+        "AI maintainability audits."
+    ),
+    "owner": {
+        "name": "Tw93",
+        "email": "hitw93@gmail.com",
+    },
+}
+
+BUNDLE_DESCRIPTION = (
+    "Installs the full Waza toolkit. Registers all eight skills under the "
+    "waza namespace, callable as /waza:think, /waza:check, /waza:hunt, "
+    "/waza:design, /waza:read, /waza:write, /waza:learn, and /waza:health. "
+    "For one skill on Claude Code v2.1.143 or newer, use /plugin install "
+    "waza-<name>@waza."
+)
+
+CATEGORY = "development"
+HOMEPAGE = "https://github.com/tw93/Waza"
+
+
+def read_version(root: Path) -> str:
+    version_file = root / "VERSION"
+    if not version_file.exists():
+        raise SystemExit(f"ERROR: missing VERSION file at {version_file}")
+    version = version_file.read_text().strip()
+    if not version:
+        raise SystemExit("ERROR: VERSION file is empty")
+    return version
+
+
+def collect_skill_metadata(root: Path) -> list[dict]:
+    skill_files = sorted((root / "skills").glob("*/SKILL.md"))
+    if not skill_files:
+        raise SystemExit("ERROR: no SKILL.md files found under skills/")
+    skills: list[dict] = []
+    for path in skill_files:
+        fields = parse_frontmatter(path)
+        if fields["name"] != path.parent.name:
+            raise SystemExit(
+                f"ERROR: {path} frontmatter name={fields['name']!r} "
+                f"!= directory {path.parent.name!r}"
+            )
+        skills.append(fields)
+    return skills
+
+
+def build_marketplace(version: str, skills: list[dict]) -> dict:
+    plugins = [
+        {
+            "name": "waza",
+            "description": BUNDLE_DESCRIPTION,
+            "version": version,
+            "category": CATEGORY,
+            "source": "./",
+            "homepage": HOMEPAGE,
+        }
+    ]
+    for skill in sorted(skills, key=lambda s: s["name"]):
+        plugins.append(
+            {
+                "name": f"waza-{skill['name']}",
+                "description": skill["description"],
+                "version": version,
+                "category": CATEGORY,
+                "source": f"./skills/{skill['name']}",
+                "homepage": HOMEPAGE,
+                # `skills` field declares which subdirectories under `source`
+                # contain SKILL.md entrypoints. "./" means the source dir itself
+                # is the skill root. Present on every per-skill entry; absent
+                # on the bundle (the bundle uses Claude Code's auto-discovery).
+                "skills": ["./"],
+                "strict": False,
+            }
+        )
+    return {**MARKETPLACE_TOP, "plugins": plugins}
+
+
+def render_marketplace(marketplace: dict) -> str:
+    return json.dumps(marketplace, indent=2, ensure_ascii=False) + "\n"
+
+
+def build_package_json(version: str) -> str:
+    package = {
+        "name": "@tw93/waza",
+        "version": version,
+        "description": (
+            "Waza engineering skills for Claude Code, Codex, Pi, and "
+            "compatible coding agents."
+        ),
+        "license": "MIT",
+        "repository": {
+            "type": "git",
+            "url": "git+https://github.com/tw93/Waza.git",
+        },
+        "homepage": "https://github.com/tw93/Waza#readme",
+        "keywords": [
+            "pi-package",
+            "agent-skills",
+            "waza",
+            "claude-code",
+            "codex",
+        ],
+        "files": [
+            "LICENSE",
+            "README.md",
+            "rules",
+            "scripts",
+            "skills",
+            "!**/__pycache__/**",
+            "!**/*.pyc",
+        ],
+        "publishConfig": {
+            "access": "public",
+        },
+        "pi": {
+            "skills": [
+                "./skills",
+            ],
+        },
+    }
+    return json.dumps(package, indent=2, ensure_ascii=False) + "\n"
+
+
+ROUTING_TABLE_START = "<!-- routing-table:start -->"
+ROUTING_TABLE_END = "<!-- routing-table:end -->"
+
+
+def render_dispatcher(template: str, skills: list[dict]) -> str:
+    rows = ["| Intent | Skill | File |", "|--------|-------|------|"]
+    for skill in sorted(skills, key=lambda s: s["name"]):
+        intent = skill.get("dispatch_intent") or ""
+        if not intent:
+            raise SystemExit(
+                f"ERROR: skill {skill['name']} missing dispatch_intent in frontmatter"
+            )
+        rows.append(f"| {intent} | {skill['name']} | `skills/{skill['name']}/SKILL.md` |")
+    table = "\n".join(rows)
+    block = f"{ROUTING_TABLE_START}\n{table}\n{ROUTING_TABLE_END}"
+    if ROUTING_TABLE_START not in template or ROUTING_TABLE_END not in template:
+        raise SystemExit(
+            "ERROR: dispatcher template is missing routing-table markers"
+        )
+    pattern = re.compile(
+        re.escape(ROUTING_TABLE_START) + r".*?" + re.escape(ROUTING_TABLE_END),
+        re.DOTALL,
+    )
+    return pattern.sub(block, template)
+
+
+# Matches both pinned (v3.24.0) and unpinned (main) install URLs so the
+# generator can rewrite either form to the current VERSION.
+README_INSTALL_URL_RE = re.compile(
+    r"raw\.githubusercontent\.com/tw93/Waza/(?:main|v\d+\.\d+\.\d+)/scripts/"
+)
+README_SWAP_TAG_RE = re.compile(r"swap `v\d+\.\d+\.\d+` for `main`")
+WAZA_REF_RE = re.compile(r'WAZA_REF="\$\{WAZA_REF:-(?:main|v\d+\.\d+\.\d+)\}"')
+
+
+def render_readme(current: str, version: str) -> str:
+    pinned = f"raw.githubusercontent.com/tw93/Waza/v{version}/scripts/"
+    current = README_INSTALL_URL_RE.sub(pinned, current)
+    return README_SWAP_TAG_RE.sub(f"swap `v{version}` for `main`", current)
+
+
+def render_script_ref(current: str, version: str) -> str:
+    return WAZA_REF_RE.sub(f'WAZA_REF="${{WAZA_REF:-v{version}}}"', current)
+
+
+def diff(label: str, expected: str, actual: str) -> str:
+    return "".join(
+        difflib.unified_diff(
+            actual.splitlines(keepends=True),
+            expected.splitlines(keepends=True),
+            fromfile=f"committed:{label}",
+            tofile=f"generated:{label}",
+        )
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=ROOT,
+        help="Repository root (default: parent of scripts/)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Compare generated bytes to committed files; exit non-zero on drift.",
+    )
+    args = parser.parse_args()
+    root = args.root.resolve()
+
+    version = read_version(root)
+    skills = collect_skill_metadata(root)
+    marketplace = build_marketplace(version, skills)
+    rendered = render_marketplace(marketplace)
+    package_rendered = build_package_json(version)
+
+    target = root / ".claude-plugin" / "marketplace.json"
+    package_json = root / "package.json"
+    package_actual = package_json.read_text() if package_json.exists() else ""
+    readme = root / "README.md"
+    readme_actual = readme.read_text() if readme.exists() else ""
+    readme_rendered = render_readme(readme_actual, version)
+    ref_scripts = [
+        root / "scripts" / "setup-rule.sh",
+        root / "scripts" / "setup-statusline.sh",
+    ]
+    script_pairs = []
+    for script in ref_scripts:
+        actual = script.read_text() if script.exists() else ""
+        script_pairs.append((script, actual, render_script_ref(actual, version)))
+
+    dispatcher_template = root / "scripts" / "dispatcher-template.md"
+    dispatcher_target = root / "scripts" / "dispatcher.md"
+    if not dispatcher_template.exists():
+        raise SystemExit(f"ERROR: missing dispatcher template at {dispatcher_template}")
+    dispatcher_actual = (
+        dispatcher_target.read_text() if dispatcher_target.exists() else ""
+    )
+    dispatcher_rendered = render_dispatcher(dispatcher_template.read_text(), skills)
+
+    if args.check:
+        actual = target.read_text() if target.exists() else ""
+        drift = False
+        if actual != rendered:
+            print(
+                f"DRIFT: {target.relative_to(root)} is out of sync with "
+                f"VERSION + SKILL.md frontmatter.\n"
+                f"Run scripts/build_metadata.py (no flags) to regenerate.",
+                file=sys.stderr,
+            )
+            sys.stderr.write(diff("marketplace.json", rendered, actual))
+            drift = True
+        if readme_actual != readme_rendered:
+            print(
+                f"DRIFT: README.md install URLs are not pinned to v{version}.\n"
+                f"Run scripts/build_metadata.py (no flags) to regenerate.",
+                file=sys.stderr,
+            )
+            sys.stderr.write(diff("README.md", readme_rendered, readme_actual))
+            drift = True
+        if package_actual != package_rendered:
+            print(
+                f"DRIFT: package.json is out of sync with VERSION v{version} "
+                f"and Pi package metadata.\n"
+                f"Run scripts/build_metadata.py (no flags) to regenerate.",
+                file=sys.stderr,
+            )
+            sys.stderr.write(diff("package.json", package_rendered, package_actual))
+            drift = True
+        for script, actual, rendered_script in script_pairs:
+            if actual != rendered_script:
+                label = script.relative_to(root).as_posix()
+                print(
+                    f"DRIFT: {label} default WAZA_REF is not pinned to v{version}.\n"
+                    f"Run scripts/build_metadata.py (no flags) to regenerate.",
+                    file=sys.stderr,
+                )
+                sys.stderr.write(diff(label, rendered_script, actual))
+                drift = True
+        if dispatcher_actual != dispatcher_rendered:
+            label = dispatcher_target.relative_to(root).as_posix()
+            print(
+                f"DRIFT: {label} routing table is out of sync with "
+                f"SKILL.md dispatch_intent frontmatter.\n"
+                f"Run scripts/build_metadata.py (no flags) to regenerate.",
+                file=sys.stderr,
+            )
+            sys.stderr.write(diff(label, dispatcher_rendered, dispatcher_actual))
+            drift = True
+        if drift:
+            return 1
+        print(f"ok: {target.relative_to(root)} matches generator")
+        print(f"ok: README.md install URLs pinned to v{version}")
+        print(f"ok: package.json pinned to v{version}")
+        print(f"ok: installer defaults pinned to v{version}")
+        print(f"ok: {dispatcher_target.relative_to(root)} matches generator")
+        return 0
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(rendered)
+    print(f"wrote: {target.relative_to(root)} ({len(rendered)} bytes)")
+    if package_actual != package_rendered:
+        package_json.write_text(package_rendered)
+        print(f"wrote: package.json (pinned version to v{version})")
+    else:
+        print(f"ok: package.json already pinned to v{version}")
+    if readme_actual != readme_rendered:
+        readme.write_text(readme_rendered)
+        print(f"wrote: README.md (pinned install URLs to v{version})")
+    else:
+        print(f"ok: README.md install URLs already pinned to v{version}")
+    for script, actual, rendered_script in script_pairs:
+        if actual != rendered_script:
+            script.write_text(rendered_script)
+            print(f"wrote: {script.relative_to(root)} (default WAZA_REF=v{version})")
+        else:
+            print(f"ok: {script.relative_to(root)} default WAZA_REF already pinned")
+    if dispatcher_actual != dispatcher_rendered:
+        dispatcher_target.write_text(dispatcher_rendered)
+        print(
+            f"wrote: {dispatcher_target.relative_to(root)} "
+            f"({len(dispatcher_rendered)} bytes)"
+        )
+    else:
+        print(f"ok: {dispatcher_target.relative_to(root)} already matches generator")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_routing_drift.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Verify dispatcher routing table and RESOLVER.md cover every skill.
+
+Both files must reference the same set of skill names found under
+`skills/*/SKILL.md`. Treated as a sanity tripwire alongside the codegen in
+`build_metadata.py`; cheap enough to keep even after routing tables become
+generated.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SKILL_REF_RE = re.compile(r"skills/([a-z][a-z0-9_-]*)/SKILL\.md")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent,
+        help="Repository root (default: parent of scripts/)",
+    )
+    args = parser.parse_args()
+    root = args.root.resolve()
+
+    expected = {
+        p.parent.name for p in (root / "skills").glob("*/SKILL.md")
+    }
+    if not expected:
+        print("ERROR: no skills found under skills/*/SKILL.md", file=sys.stderr)
+        return 1
+
+    dispatcher = set(
+        SKILL_REF_RE.findall((root / "scripts" / "dispatcher.md").read_text())
+    )
+    resolver = set(
+        SKILL_REF_RE.findall((root / "skills" / "RESOLVER.md").read_text())
+    )
+
+    drift = False
+
+    missing_dispatcher = expected - dispatcher
+    if missing_dispatcher:
+        print(
+            "ROUTING DRIFT: skills missing from scripts/dispatcher.md: "
+            f"{sorted(missing_dispatcher)}",
+            file=sys.stderr,
+        )
+        drift = True
+
+    missing_resolver = expected - resolver
+    if missing_resolver:
+        print(
+            f"ROUTING DRIFT: skills missing from RESOLVER.md: {sorted(missing_resolver)}",
+            file=sys.stderr,
+        )
+        drift = True
+
+    stale_dispatcher = dispatcher - expected
+    if stale_dispatcher:
+        print(
+            f"ROUTING DRIFT: stale skill refs in scripts/dispatcher.md: {sorted(stale_dispatcher)}",
+            file=sys.stderr,
+        )
+        drift = True
+
+    if drift:
+        return 1
+
+    print(
+        f"ok: routing consistent across {len(expected)} skills (scripts/dispatcher.md + RESOLVER.md)"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/dispatcher-template.md

@@ -0,0 +1,43 @@
+---
+name: waza
+description: 'Dispatcher for Waza engineering skills: think (architecture/handoff), design (artifact-grounded UI), check (review/release gates), hunt (runtime debugging/regression), write (prose/release copy), learn (research), read (URL/PDF fetch), health (agent config and AI maintainability audit).'
+---
+
+# Waza: Engineering Skills Dispatcher
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+You have eight skills available. Match the user's intent to the right skill, read the matching section below, and execute it.
+
+## Routing Table
+
+<!-- routing-table:start -->
+<!-- routing-table:end -->
+
+## How This Works
+
+1. Read the user's message and match it to a skill from the table above.
+2. Read the matched skill section in full.
+3. Execute that skill's instructions exactly.
+
+If the message could match multiple skills, use these disambiguation rules:
+
+1. Most specific wins: `/design` is more specific than `/think` for UI decisions.
+2. URL in message: start with `/read`. If the content is research material, chain to `/learn`.
+3. Code already done vs. code broken: done/PR -> `/check`; error/broken -> `/hunt`.
+4. Config/maintainability vs. code: Codex/Claude misbehaving, hooks/MCP, `/health` token usage, AI coding code rot, unclear context, missing verification, or stale verifier output -> `/health`; user code errors -> `/hunt`.
+5. Release action vs. release prose: commit/tag/publish/push/release reactions/close issue -> `/check`; write release notes/changelog text -> `/write`.
+6. Screenshot taste vs. screenshot regression: visual taste complaint -> `/design`; broken render/state/generated output or used-to-work evidence -> `/hunt`.
+7. From scratch vs. editing: new long-form output -> `/learn`; existing draft to polish -> `/write`.
+8. "Judge this" + error -> `/hunt`; "judge this" + should we keep it -> `/think`.
+9. Still ambiguous: read both skills' "Not for" sections; use exclusion. If still unclear, ask the user.
+
+## Path Resolution
+
+In this distribution, sub-skill scripts live at `skills/{name}/scripts/`. Resolve all relative paths from this file's directory, not from a personal home-directory skill cache.
+
+## Chaining
+
+Skills chain manually, not automatically. Each skill completes and waits for the user's next action.
+
+Common chains: `/think` -> implement approved plan -> `/check` | `/hunt` -> fix -> `/check` -> release/push/issue follow-through | `/read` -> `/learn` -> `/write`

package/scripts/dispatcher.md

@@ -0,0 +1,53 @@
+---
+name: waza
+description: 'Dispatcher for Waza engineering skills: think (architecture/handoff), design (artifact-grounded UI), check (review/release gates), hunt (runtime debugging/regression), write (prose/release copy), learn (research), read (URL/PDF fetch), health (agent config and AI maintainability audit).'
+---
+
+# Waza: Engineering Skills Dispatcher
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+You have eight skills available. Match the user's intent to the right skill, read the matching section below, and execute it.
+
+## Routing Table
+
+<!-- routing-table:start -->
+| Intent | Skill | File |
+|--------|-------|------|
+| Code review, before merge, release gates, generated artifacts, safety sinks, publish/push/reaction follow-through, triage issues/PRs, project-wide code-quality audit scorecard | check | `skills/check/SKILL.md` |
+| UI, component, page, visual interface, frontend, artifact-grounded screenshot aesthetic complaint | design | `skills/design/SKILL.md` |
+| Codex/Claude/Pi ignoring instructions, agent config audit, hooks/MCP broken, health token usage, AI coding code rot, hotspot ownership, unclear context, missing verification, stale verifier output | health | `skills/health/SKILL.md` |
+| Error, crash, regression, screenshot-reported defect, test failure, stale cache, runtime boundary, why broken | hunt | `skills/hunt/SKILL.md` |
+| Deep research, unfamiliar domain, compile sources into output | learn | `skills/learn/SKILL.md` |
+| Any URL or PDF to fetch, read this, fetch this page | read | `skills/read/SKILL.md` |
+| New feature, architecture, how should I design this, value judgment, executable plan, handoff | think | `skills/think/SKILL.md` |
+| Writing, editing prose, polish, release notes, launch/social copy, remove AI tone | write | `skills/write/SKILL.md` |
+<!-- routing-table:end -->
+
+## How This Works
+
+1. Read the user's message and match it to a skill from the table above.
+2. Read the matched skill section in full.
+3. Execute that skill's instructions exactly.
+
+If the message could match multiple skills, use these disambiguation rules:
+
+1. Most specific wins: `/design` is more specific than `/think` for UI decisions.
+2. URL in message: start with `/read`. If the content is research material, chain to `/learn`.
+3. Code already done vs. code broken: done/PR -> `/check`; error/broken -> `/hunt`.
+4. Config/maintainability vs. code: Codex/Claude misbehaving, hooks/MCP, `/health` token usage, AI coding code rot, unclear context, missing verification, or stale verifier output -> `/health`; user code errors -> `/hunt`.
+5. Release action vs. release prose: commit/tag/publish/push/release reactions/close issue -> `/check`; write release notes/changelog text -> `/write`.
+6. Screenshot taste vs. screenshot regression: visual taste complaint -> `/design`; broken render/state/generated output or used-to-work evidence -> `/hunt`.
+7. From scratch vs. editing: new long-form output -> `/learn`; existing draft to polish -> `/write`.
+8. "Judge this" + error -> `/hunt`; "judge this" + should we keep it -> `/think`.
+9. Still ambiguous: read both skills' "Not for" sections; use exclusion. If still unclear, ask the user.
+
+## Path Resolution
+
+In this distribution, sub-skill scripts live at `skills/{name}/scripts/`. Resolve all relative paths from this file's directory, not from a personal home-directory skill cache.
+
+## Chaining
+
+Skills chain manually, not automatically. Each skill completes and waits for the user's next action.
+
+Common chains: `/think` -> implement approved plan -> `/check` | `/hunt` -> fix -> `/check` -> release/push/issue follow-through | `/read` -> `/learn` -> `/write`

package/scripts/package-skill.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT="${1:-"$ROOT/dist/waza.zip"}"
+case "$OUT" in
+  /*) ;;
+  *) OUT="$ROOT/$OUT" ;;
+esac
+
+mkdir -p "$(dirname "$OUT")"
+rm -f "$OUT"
+
+cd "$ROOT"
+
+MANIFEST="$(mktemp)"
+FILTERED_MANIFEST="$(mktemp)"
+STAGE="$(mktemp -d)"
+trap 'rm -f "$MANIFEST" "$FILTERED_MANIFEST"; rm -rf "$STAGE"' EXIT
+
+git ls-files --cached --others --exclude-standard > "$MANIFEST"
+
+# Default-deny: only paths matching packaging.allowlist ship. Structural
+# excludes (per-skill SKILL.md, __pycache__, etc.) live inside the filter.
+python3 "$ROOT/scripts/packaging_filter.py" "$ROOT/packaging.allowlist" \
+  < "$MANIFEST" > "$FILTERED_MANIFEST"
+
+tar -cf - -T "$FILTERED_MANIFEST" | (cd "$STAGE" && tar -xf -)
+
+# Dispatcher body is codegen output: scripts/dispatcher.md. Source of truth is
+# scripts/dispatcher-template.md plus SKILL.md frontmatter; regenerate with
+# `make regenerate` if the template or any dispatch_intent changes.
+if [ ! -f "$ROOT/scripts/dispatcher.md" ]; then
+  echo "ERROR: scripts/dispatcher.md missing; run 'make regenerate' first" >&2
+  exit 1
+fi
+cp "$ROOT/scripts/dispatcher.md" "$STAGE/SKILL.md"
+
+find skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort | while IFS= read -r path; do
+  skill="$(basename "$(dirname "$path")")"
+  {
+    printf '\n---\n\n# SKILL: %s\n\n' "$skill"
+    awk 'BEGIN{skip=0} /^---$/{if(NR==1){skip=1;next} if(skip){skip=0;next}} !skip' "$path"
+  } >> "$STAGE/SKILL.md"
+done
+
+perl -0pi -e 's#`skills/([a-z][a-z0-9_-]*)/SKILL\.md`#the **$1** section below#g' "$STAGE/SKILL.md"
+find "$STAGE/skills" -type d -empty -delete 2>/dev/null || true
+
+(cd "$STAGE" && find . -type f | sed 's#^\./##' | sort | zip -q "$OUT" -@)
+
+if ! zipinfo -1 "$OUT" | awk '$0 == "SKILL.md" { found = 1 } END { exit found ? 0 : 1 }'; then
+  echo "ERROR: root SKILL.md missing from $OUT" >&2
+  exit 1
+fi
+
+SKILL_COUNT="$(zipinfo -1 "$OUT" | awk '$0 ~ /(^|\/)SKILL\.md$/ { count++ } END { print count + 0 }')"
+if [ "$SKILL_COUNT" -ne 1 ]; then
+  echo "ERROR: expected exactly one SKILL.md in $OUT, found $SKILL_COUNT" >&2
+  exit 1
+fi
+
+SIZE=$(wc -c < "$OUT" | tr -d ' ')
+echo "OK: wrote $OUT (${SIZE} bytes)"
+
+# Post-package validation lives in scripts/validate_package.py so it's
+# py_compile-checked in CI and unit-testable.
+VALIDATE_DIR="$(mktemp -d)"
+trap 'rm -rf "$VALIDATE_DIR"' EXIT
+unzip -q "$OUT" -d "$VALIDATE_DIR"
+python3 "$ROOT/scripts/validate_package.py" "$VALIDATE_DIR"

package/scripts/packaging_filter.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Filter stdin paths through packaging.allowlist. Default-deny."""
+
+import fnmatch
+import re
+import sys
+from pathlib import Path
+
+EXCLUDE_RE = re.compile(
+    r"(^skills/[^/]+/SKILL\.md$"
+    r"|(^|/)__pycache__/"
+    r"|\.pyc$"
+    r"|(^|/)\.DS_Store$)"
+)
+
+
+def load_patterns(path: Path) -> list[str]:
+    patterns = []
+    for raw in path.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        patterns.append(line)
+    return patterns
+
+
+def allowed(path: str, patterns: list[str]) -> bool:
+    for pat in patterns:
+        if pat.endswith("/**"):
+            prefix = pat[:-3]
+            if path == prefix or path.startswith(prefix + "/"):
+                return True
+        elif fnmatch.fnmatch(path, pat):
+            return True
+    return False
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: packaging_filter.py <allowlist-path>", file=sys.stderr)
+        return 2
+    patterns = load_patterns(Path(sys.argv[1]))
+    for line in sys.stdin:
+        path = line.rstrip("\n")
+        if not path:
+            continue
+        if EXCLUDE_RE.search(path):
+            continue
+        if allowed(path, patterns):
+            print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())