Skip to content

NocodeMrLi/mini-program-engineering-skill-suite

mini-program-engineering-suite

Unverified

Orchestrate evidence-first engineering for WeChat and other mini programs from a vague idea or existing repository through project discovery, product specification, architecture, implementation, debugging, device adaptation, verification, and release readiness. Use when users ask to build a mini program from zero to one, take over an existing mini-program project, deliver a cross-stage feature, diagnose project status, coordinate development and testing, or judge whether a mini program is ready to upload or release. Enforces fact discovery, change boundaries, stage gates, evidence-calibrated status, sensitive-information redaction, and continuity after side questions.

scripts/drift_watch.py

View on GitHub
#!/usr/bin/env python3
"""Deterministic drift detection orchestration (the detect stage).

Wraps platform_drift's L0/L1 checks for every platforms/<name>/ directory:
- detection is always deterministic here: fingerprints only, no LLM calls
  (``--no-llm`` documents this explicitly; there is no L2 path in this tool);
- findings become one GitHub issue per actionable rule via ``--emit-issues``
  (uses the repository's Platform rule drift template fields);
- a missing or unreadable rule map fails closed (exit 2).

L2 extraction and consistency review live in drift_audit.py. That stage runs
in CI with the AGENT_API_* secrets configured by the author (see
.github/workflows/drift-watch.yml) or locally with any CLI engine. A passing
scheduled audit can flow into the facts-only PR/auto-merge path; without
secrets, the workflow degrades to detection-only.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import subprocess
import sys
import urllib.error
import urllib.request
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Sequence

sys.path.insert(0, str(Path(__file__).resolve().parent))

import platform_drift  # noqa: E402
from platform_drift import check_rule, load_fact_annotations, load_json  # noqa: E402


class L2Blocked(Exception):
    """Raised instead of running an LLM extraction when deterministic mode forbids it."""


def deterministic_check(platform_root: Path) -> dict[str, Any]:
    """Run L0/L1 for one platform; L2 is blocked so the path stays token-free."""

    def blocked_run_agent(cwd, prompt):  # noqa: ANN001, ANN202
        raise L2Blocked()

    original_run_agent = platform_drift.run_agent
    platform_drift.run_agent = blocked_run_agent
    try:
        rule_map = load_json(platform_root / "rule-map.json")
        annotations = load_fact_annotations(platform_root / "facts.md")
        results = []
        for rule in rule_map["rules"]:
            try:
                outcome = check_rule(rule, annotations, rule_map["allowed_domains"], force_l2=False)
            except L2Blocked:
                # L1 says the fingerprint changed (or was never recorded) and L2 is
                # forbidden here: surface it as actionable without any model call.
                outcome = {
                    "rule_id": rule["id"],
                    "state": "fingerprint-changed",
                    "reason": "l1-fingerprint-mismatch-or-unrecorded",
                    "url": rule["official"]["url"],
                    "checked_at_utc": utc_now(),
                }
            results.append(outcome)
    finally:
        platform_drift.run_agent = original_run_agent
    counts: dict[str, int] = {}
    for item in results:
        counts[item["state"]] = counts.get(item["state"], 0) + 1
    return {
        "platform": rule_map["platform"],
        "checked_at_utc": utc_now(),
        "rule_count": len(results),
        "counts": counts,
        "results": results,
    }

USER_AGENT = "mini-program-engineering-suite-drift-watch/1.0 (weekly CI; low frequency)"
REQUEST_TIMEOUT_SECONDS = 30


def utc_now() -> str:
    return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")


def platform_dirs(root: Path, only: str | None) -> list[Path]:
    platforms = root / "platforms"
    if not platforms.is_dir():
        return []
    dirs = []
    for candidate in sorted(p for p in platforms.iterdir() if p.is_dir() and (p / "rule-map.json").is_file()):
        rule_map = json.loads((candidate / "rule-map.json").read_text(encoding="utf-8"))
        # manual-only platforms (client-rendered SPA docs) cannot be observed by
        # deterministic fingerprints; watching them weekly would only create noise.
        if rule_map.get("detection") == "manual-only":
            continue
        dirs.append(candidate)
    if only:
        dirs = [p for p in dirs if p.name == only]
    return dirs


def manual_only_platforms(root: Path) -> list[Path]:
    """Every platform whose rule-map declares detection=manual-only."""
    platforms = root / "platforms"
    if not platforms.is_dir():
        return []
    result = []
    for candidate in sorted(p for p in platforms.iterdir() if p.is_dir() and (p / "rule-map.json").is_file()):
        rule_map = json.loads((candidate / "rule-map.json").read_text(encoding="utf-8"))
        if rule_map.get("detection") == "manual-only":
            result.append(candidate)
    return result


FACT_VERIFIED = re.compile(r"verified=(\d{4}-\d{2}-\d{2})")


def manual_only_entry(platform_dir: Path) -> dict[str, Any]:
    """One report entry for a platform deterministic detection cannot observe.

    These platforms must STAY VISIBLE in the report with state
    not-automatically-observable (audit P2-02): dropping them silently made
    actionable_count=0 read as "all three platforms have no drift" while two
    of them were never checked.
    """
    facts_path = platform_dir / "facts.md"
    verified_dates: list[str] = []
    if facts_path.is_file():
        verified_dates = FACT_VERIFIED.findall(facts_path.read_text(encoding="utf-8"))
    rule_map = json.loads((platform_dir / "rule-map.json").read_text(encoding="utf-8"))
    urls = sorted({rule.get("official", {}).get("url", "") for rule in rule_map.get("rules", []) if rule.get("official", {}).get("url")})
    return {
        "platform": rule_map.get("platform", platform_dir.name),
        "state": "not-automatically-observable",
        "reason": "manual-only platform: client-rendered docs defeat deterministic fingerprinting",
        "rule_count": len(rule_map.get("rules", [])),
        "last_manual_verification": max(verified_dates) if verified_dates else None,
        "manual_verification_entry_points": urls,
        "next_step": "maintainer opens each official URL and re-verifies verify_points manually",
        "checked_at_utc": utc_now(),
    }


DETECTION_ACTIONABLE = {"fingerprint-changed", "unverifiable"}
AUDIT_ACTIONABLE = {"fingerprint-changed", "unverifiable", "updated", "conflicting"}


def actionable(results: list[dict[str, Any]], states: set[str] | None = None) -> list[dict[str, Any]]:
    """Filter results needing attention; CI detection and full audits use different vocabularies."""
    return [item for item in results if item["state"] in (states or DETECTION_ACTIONABLE)]


def gh_available() -> bool:
    return bool(os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN"))


def existing_open_issues(title_prefix: str, include_closed: bool = False) -> set[str]:
    """Return titles of existing drift issues matching the prefix.

    Detection issues default to open-only so a future same-rule drift can still
    notify maintainers after an older drift issue was closed. Audit verdict
    issues may opt into closed-state dedup: closing a resolved "no actionable
    drift" issue used to erase the dedup key, so the next weekly run re-opened
    a same-titled duplicate (#19 after #9).
    """
    state = "all" if include_closed else "open"
    result = subprocess.run(
        ["gh", "issue", "list", "--state", state, "--json", "title", "--limit", "500", "--search", f"in:title {title_prefix}"],
        capture_output=True, check=False, text=True,
    )
    if result.returncode:
        # Older gh versions / appliances without --search: fall back to the
        # plain state listing so dedup keeps the requested open/all semantics.
        result = subprocess.run(
            ["gh", "issue", "list", "--state", state, "--json", "title", "--limit", "500"],
            capture_output=True, check=False, text=True,
        )
    if result.returncode:
        return set()
    try:
        return {item["title"] for item in json.loads(result.stdout)}
    except json.JSONDecodeError:
        return set()


def emit_issues(report: dict[str, Any], repo: str | None) -> int:
    """Open one issue per actionable rule; idempotent against open duplicates.

    Returns 1 when any issue creation failed so CI surfaces a broken
    notification chain instead of silently skipping it.
    """
    if not gh_available():
        print(json.dumps({"emit_issues": "skipped", "reason": "no-github-token"}, ensure_ascii=False))
        return 0
    # Keep deterministic detection alerts open-only: closed historical drift
    # issues must not suppress a genuinely new same-rule drift in a later week.
    existing = existing_open_issues("[Drift]")
    opened = 0
    failed: list[str] = []
    for platform_block in report["platforms"]:
        for item in actionable(platform_block["results"]):
            title = f"[Drift] {platform_block['platform']}: {item['rule_id']} -> {item['state']}"
            if title in existing:
                continue
            body = (
                f"Automated weekly drift watch (deterministic L0/L1 only).\n\n"
                f"- Platform: {platform_block['platform']}\n"
                f"- Rule id: {item['rule_id']}\n"
                f"- State: {item['state']}\n"
                f"- Source: {item.get('url', 'n/a')}\n"
                f"- Checked at (UTC): {item.get('checked_at_utc')}\n"
                f"- Detail: {item.get('error') or item.get('reason', 'fingerprint changed vs facts.md')}\n\n"
                f"Next step (maintainer, local): run L2 extraction and the consistency reviewer:\n"
                f"```bash\n"
                f"python3 scripts/platform_drift.py platforms/{platform_block['platform']} --rule {item['rule_id']} --proposal-out /tmp/proposal.json\n"
                f"python3 scripts/review_drift_proposal.py /tmp/proposal.json --platform-root platforms/{platform_block['platform']} --drift-report /tmp/drift.json\n"
                f"```\n"
                f"The Saturday audit now applies only PROPOSAL_CONSISTENT_WITH_EXTRACTION proposals through a "
                f"facts-only PR with auto-merge enabled; DO_NOT_APPLY findings stay issue-only."
            )
            command = ["gh", "issue", "create", "--title", title, "--body", body, "--label", "drift"]
            if repo:
                command += ["--repo", repo]
            result = subprocess.run(command, capture_output=True, check=False, text=True)
            if result.returncode == 0:
                opened += 1
            else:
                failed.append(item["rule_id"])
                print(f"issue-create-failed:{item['rule_id']}:{result.stderr.strip()[:200]}")
    print(json.dumps({"emit_issues": "done", "opened": opened, "failed": failed}, ensure_ascii=False))
    return 1 if failed else 0


def run(root: Path, only: str | None, no_llm: bool) -> dict[str, Any] | None:
    dirs = platform_dirs(root, only)
    manual = manual_only_platforms(root)
    if only:
        # Explicit scope: manual-only entries narrow to the named platform.
        manual = [d for d in manual if d.name == only]
    if not dirs and not manual:
        return None
    # Detection in this tool is deterministic by construction; the flag is kept
    # for CLI compatibility and the mode field always states the truth.
    report: dict[str, Any] = {
        "generated_at_utc": utc_now(),
        "mode": "deterministic",
        "llm_stage": "drift_audit.py (detection never calls engines)",
        # Coverage accounting (audit P2-02): actionable_count=0 must never be
        # readable as "no platform drifted" when manual-only platforms were
        # never deterministically checked. They stay in the report.
        "platform_total": len(dirs) + len(manual),
        "automatically_checked": len(dirs),
        "manual_only": len(manual),
        "platforms": [deterministic_check(d) for d in dirs],
        "manual_only_platforms": [manual_only_entry(d) for d in manual],
    }
    if only:
        # An explicit --platform-dir narrows THIS run's scope; the counters then
        # describe the narrowed scope, and skipped_platforms records what was
        # left out so the narrowing can never hide a platform silently.
        included = {d.name for d in dirs} | {d.name for d in manual}
        all_platforms = {
            p.name for p in (root / "platforms").iterdir()
            if p.is_dir() and (p / "rule-map.json").is_file()
        }
        report["skipped_platforms"] = sorted(all_platforms - included)
    report["actionable_count"] = sum(len(actionable(p["results"])) for p in report["platforms"])
    return report


def explicit_manual_only_message(root: Path, only: str | None) -> str | None:
    """Clear guidance when --platform-dir names a manual-only platform.

    The flag used to fall through to no-platform-dirs (exit 2), which reads
    like a tooling error instead of the truth: this platform is deliberately
    not deterministically observable (audit P2-02).
    """
    if not only:
        return None
    platform_root = root / "platforms" / only
    rule_map_path = platform_root / "rule-map.json"
    if not rule_map_path.is_file():
        return None
    try:
        rule_map = json.loads(rule_map_path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError):
        return None
    if rule_map.get("detection") != "manual-only":
        return None
    entry = manual_only_entry(platform_root)
    return json.dumps(
        {
            "platform": only,
            "status": "not-automatically-observable",
            "reason": entry["reason"],
            "rule_count": entry["rule_count"],
            "last_manual_verification": entry["last_manual_verification"],
            "manual_verification_entry_points": entry["manual_verification_entry_points"],
            "next_step": entry["next_step"],
        },
        ensure_ascii=False, indent=2, sort_keys=True,
    )


def main(argv: Sequence[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--platform-dir", help="Check only platforms/<name> (path or name)")
    parser.add_argument("--no-llm", action="store_true", help="Deterministic L0/L1 only (CI default)")
    parser.add_argument("--output", type=Path, help="Write the JSON report here")
    parser.add_argument("--report", type=Path, help="Read a previous report (for --emit-issues)")
    parser.add_argument("--emit-issues", action="store_true", help="Open GitHub issues for actionable findings")
    parser.add_argument("--repo", help="Optional repo (owner/name) for gh commands")
    args = parser.parse_args(argv)

    if args.emit_issues:
        # Fresh detection run in the same invocation: write/read our own report
        # (the CI detect step passes --output + --emit-issues together; requiring
        # a separate --report file made every first run fail with report-missing).
        only = None
        if args.platform_dir:
            only = Path(args.platform_dir).name
        report = run(Path.cwd(), only, args.no_llm)
        if report is None:
            print(json.dumps({"error": "no-platform-dirs"}, ensure_ascii=False))
            return 2
        if args.output:
            args.output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
            print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
        emit_rc = emit_issues(report, args.repo)
        # Propagate both failure modes: actionable findings AND notification
        # failures must make the job reflect them (issue-create failures used
        # to be swallowed).
        if emit_rc:
            return emit_rc
        return 1 if report["actionable_count"] else 0

    only = None
    if args.platform_dir:
        only = Path(args.platform_dir).name
    report = run(Path.cwd(), only, args.no_llm)
    if report is None:
        # A manual-only platform named explicitly gets structured guidance, not
        # a generic no-platform-dirs error (audit P2-02).
        manual_message = explicit_manual_only_message(Path.cwd(), only)
        if manual_message:
            print(manual_message)
            return 3
        print(json.dumps({"error": "no-platform-dirs"}, ensure_ascii=False))
        return 2
    if args.output:
        args.output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
    # Exit 1 when anything is actionable so CI shows the job as needing attention.
    return 1 if report["actionable_count"] else 0


if __name__ == "__main__":
    raise SystemExit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall