NocodeMrLi/mini-program-engineering-skill-suite
mini-program-engineering-suite
VerifiedOrchestrate 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/release_recommendation.py
View on GitHub#!/usr/bin/env python3
"""Recommend whether the current tree deserves a release, and at which level.
Deterministic and zero-LLM-cost: classifies commits since the last tag by the
paths they touch. Output is exactly one of RECOMMEND_RELEASE (with a level),
MANUAL_VERIFICATION_REQUIRED, or HOLD, always with reasons. The author makes
the final call.
manual-only platform policy (platforms/README.md): major releases require
re-verification of every alipay/douyin fact; minor releases require it when
the last verification is older than 90 days or when platform facts / release
governance changed; patch releases only when related facts changed, a user
report arrived, or the platform shifted. Overdue verification downgrades the
recommendation to MANUAL_VERIFICATION_REQUIRED — it never passes silently.
"""
from __future__ import annotations
import argparse
import json
import re
import subprocess
import sys
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any, Sequence
from evidence_signature import SignatureError, verify_signed_document
LEVELS = ("patch", "minor", "major")
LEVEL_RANK = {"patch": 0, "minor": 1, "major": 2}
MANUAL_ONLY_PLATFORMS = ("alipay", "douyin")
VERIFICATION_MAX_AGE_DAYS = 90
FACT_ANNOTATION = re.compile(
r"<!--\s*fact:\s*\S+\s+verified=(?P<verified>[^\s]+)\s+source=\S+\s+digest=\S+\s*-->"
)
# Conventional-commit breaking markers: a subject like "feat!:" or any
# "BREAKING CHANGE" mention classifies the whole release as major.
BREAKING_SUBJECT = re.compile(r"BREAKING[ -]CHANGE|^\w+!:", re.IGNORECASE)
# New tooling CAPABILITY (feat:) is a compatible addition -> minor; tooling
# fixes (fix:/chore:/test:/refactor:) stay patch (audit P1-02 five classes:
# metadata / behavior-body / tooling-fix / compatible-addition / breaking).
FEATURE_SUBJECT = re.compile(r"^(feat|add|新增)\b", re.IGNORECASE)
# Root SKILL.md frontmatter lines that are release METADATA, not behavior:
# bumping version/last_reviewed must not force a minor release (audit P1-02).
ROOT_SKILL_METADATA_LINE = re.compile(r"^[+-]\s*(?:version|last_reviewed):")
# Path prefixes that classify the character of a change. Checked in order of severity.
# VERSION is release metadata (its own class); root SKILL.md starts in
# "behavior" but is reclassified to "metadata" when its diff only touches
# version/last_reviewed lines (see root_skill_change_is_metadata_only).
PATH_CLASSES: tuple[tuple[tuple[str, ...], str], ...] = (
(("SKILL.md", "skills/", "shared/"), "behavior"),
(("scripts/", "install.sh", ".github/", "tests/", "agents/", "references/"), "tooling"),
(("platforms/",), "data"),
(("VERSION",), "metadata"),
(("README", "CHANGELOG", "LICENSE", "COMPATIBILITY", "EVALUATIONS"), "docs"),
(("assets/",), "assets"),
)
def parse_semver(tag: str) -> tuple[int, int, int] | None:
"""Parse v<major>.<minor>.<patch>; None for anything else."""
body = tag[1:] if tag.startswith("v") else tag
parts = body.split(".")
if len(parts) != 3:
return None
try:
values = tuple(int(part) for part in parts)
except ValueError:
return None
return values # type: ignore[return-value]
def semver_bump(baseline: str, candidate: str) -> str | None:
"""Return patch/minor/major for baseline->candidate; None when not a strict bump."""
base = parse_semver(baseline)
cand = parse_semver(candidate)
if base is None or cand is None or cand <= base:
return None
if cand[0] != base[0]:
return "major"
if cand[1] != base[1]:
return "minor"
return "patch"
def release_tags_sorted(root: Path) -> list[str]:
"""All v<x.y.z> tags sorted by semver (ascending)."""
result = subprocess.run(
["git", "-C", str(root), "tag", "--list", "v*"],
capture_output=True, check=False, text=True,
)
parsed: list[tuple[tuple[int, int, int], str]] = []
for line in result.stdout.splitlines():
tag = line.strip()
value = parse_semver(tag) if tag else None
if value is not None:
parsed.append((value, tag))
return [tag for _, tag in sorted(parsed)]
def root_skill_change_is_metadata_only(root: Path, commit_hash: str) -> bool:
"""True when this commit's root SKILL.md diff only moves version metadata.
The behavior class otherwise fires on ANY root SKILL.md edit, so a pure
version bump was misclassified as a behavior change and forced minor
releases (audit P1-02: v3.1.9 was released as patch while the gate
summary said minor).
"""
diff = git(root, "show", "--format=", "--unified=0", commit_hash, "--", "SKILL.md")
changed = [
line
for line in diff.splitlines()
if line[:1] in "+-" and not line.startswith(("+++", "---"))
]
if not changed:
return True
return all(ROOT_SKILL_METADATA_LINE.match(line) for line in changed)
def commit_paths_are_metadata_only(root: Path, commit_hash: str, paths: list[str]) -> bool:
"""True when this commit's root SKILL.md edit only moves release metadata.
The release-prep commit bumps VERSION + root SKILL.md frontmatter and often
carries tooling/docs edits in the same commit. The QUESTION this answers is
narrow: did the BEHAVIOR-classified content (root SKILL.md) actually change
behaviorally? If SKILL.md only moved version/last_reviewed lines, its
behavior class is reclassified to metadata even when the same commit also
touches scripts or docs — those keep their own classes (audit P1-02).
"""
if not any(path == "SKILL.md" for path in paths):
return False
return root_skill_change_is_metadata_only(root, commit_hash)
def load_downgrade_override(root: Path, candidate_tag: str, required_level: str) -> dict[str, Any] | None:
"""Load and validate a structured manual downgrade (release-override.json).
A downgrade may lower the required level by exactly one step (major->minor
or minor->patch), must name THIS candidate tag, and must carry a reason and
an independent signer. Anything else is rejected (returns None and the
original level stands) — never a silent pass.
"""
path = root / "release-override.json"
if not path.is_file():
return None
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError):
return {"accepted": False, "problems": ["override-unreadable"]}
if not isinstance(data, dict):
return {"accepted": False, "problems": ["override-not-object"]}
problems: list[str] = []
try:
signer_key_id = verify_signed_document(
data,
root / ".github" / "release-evidence" / "trusted-signers.pem",
expected_key_id="release-evaluation-2026-08-31",
)
except SignatureError as exc:
signer_key_id = None
problems.append(f"override-{exc}")
target = data.get("to")
allowed = {"major": "minor", "minor": "patch"}
if not isinstance(data.get("reason"), str) or not data["reason"].strip():
problems.append("override-reason-missing")
if not isinstance(data.get("signed_by"), str) or not data["signed_by"].strip():
problems.append("override-signer-missing")
else:
try:
candidate_author = git(root, "show", "-s", "--format=%ae", candidate_tag).strip()
except ValueError:
candidate_author = ""
if candidate_author and data["signed_by"].strip().casefold() == candidate_author.casefold():
problems.append("override-signer-not-independent")
if data.get("candidate_tag") != candidate_tag:
problems.append("override-candidate-tag-mismatch")
if data.get("from") != required_level or target != allowed.get(required_level):
problems.append("override-not-one-step-downgrade")
if problems:
return {"accepted": False, "problems": problems}
return {
"accepted": True,
"from": required_level,
"to": target,
"reason": data["reason"].strip(),
"signed_by": data["signed_by"].strip(),
"signer_key_id": signer_key_id,
"candidate_tag": candidate_tag,
}
def git(root: Path, *args: str) -> str:
result = subprocess.run(
["git", "-C", str(root), *args], capture_output=True, check=False, text=True
)
if result.returncode:
raise ValueError(f"git-{'-'.join(args[:1])}-failed:{result.stderr.strip()[:200]}")
return result.stdout
def last_tag(root: Path, before: str | None = None) -> str | None:
"""Newest tag, optionally strictly BEFORE a given rev.
With before=None this is the plain "most recent tag" (HEAD-relative). With
before="<candidate>^" it returns the last tag that precedes the candidate's
parent — the true baseline for a release checkout, where HEAD sits ON the
candidate tag and a plain describe would return the candidate itself
(the P0 bypass: candidate..HEAD = empty -> HOLD -> gate skipped).
"""
# Source snapshots are not release baselines. Match only known semantic
# release tags so an annotated review tag cannot hide behavioral changes.
release_tags = release_tags_sorted(root)
if not release_tags:
return None
args = ["git", "-C", str(root), "describe", "--tags", "--abbrev=0"]
args.extend(f"--match={tag}" for tag in release_tags)
if before is not None:
args.append(before)
result = subprocess.run(args, capture_output=True, check=False, text=True)
return result.stdout.strip() if result.returncode == 0 else None
def head_commit(root: Path) -> str | None:
result = subprocess.run(
["git", "-C", str(root), "rev-parse", "HEAD"],
capture_output=True, check=False, text=True,
)
return result.stdout.strip() if result.returncode == 0 else None
def tag_commit(root: Path, tag: str) -> str | None:
result = subprocess.run(
["git", "-C", str(root), "rev-parse", f"{tag}^{{}}"],
capture_output=True, check=False, text=True,
)
return result.stdout.strip() if result.returncode == 0 else None
def is_shallow_repository(root: Path) -> bool:
result = subprocess.run(
["git", "-C", str(root), "rev-parse", "--is-shallow-repository"],
capture_output=True,
check=False,
text=True,
)
if result.returncode:
raise ValueError(f"git-shallow-check-failed:{result.stderr.strip()[:200]}")
return result.stdout.strip() == "true"
def classify_commit(paths: list[str]) -> str:
"""Pick the most significant class among the commit's touched paths (kept for callers that want one label)."""
ranking = {"behavior": 5, "tooling": 3, "data": 2, "metadata": 1, "docs": 1, "assets": 1}
best = "docs"
for label in classify_commit_classes(paths):
if ranking[label] > ranking[best]:
best = label
return best
def classify_commit_classes(paths: list[str]) -> set[str]:
"""Return EVERY class the commit touches, not just the highest.
A commit editing scripts/ AND platforms/alipay/facts.md is both tooling
and data; keeping only "tooling" silently dropped the data trigger for
manual verification (codex probe).
"""
classes: set[str] = set()
for path in paths:
for prefixes, label in PATH_CLASSES:
if path.startswith(prefixes):
classes.add(label)
break
return classes
def collect_commits(root: Path, tag: str | None) -> list[dict[str, Any]]:
# git emits: <boundary><hash><sep><subject>\n<file>\n<file>\n per commit with --name-only,
# so each block starts with its header and carries its own file list.
separator = "@@FIELD@@"
boundary = "@@COMMIT@@"
log_format = f"{boundary}%H{separator}%s"
raw = git(root, "log", "--name-only", f"--format={log_format}", *(["%s..HEAD" % tag] if tag else []))
commits: list[dict[str, Any]] = []
for block in raw.split(boundary):
lines = [line for line in block.strip().splitlines() if line.strip()]
if not lines or separator not in lines[0]:
continue
header = lines[0].split(separator)
if len(header) < 2:
continue
commits.append({"hash": header[0][:8], "subject": header[1], "paths": lines[1:]})
return commits
PLATFORM_TOKEN = r"(?:alipay(?:\s*/\s*douyin)?|douyin(?:\s*/\s*alipay)?)"
PLATFORM_VERIFICATION_RE = re.compile(
PLATFORM_TOKEN
+ r"\s+facts\s+人工核验于\s*(?P<date>\d{4}-\d{2}-\d{2})"
+ r"(?:\s*\([^)]*tag[::]\s*(?P<tag>[v0-9.]+)[^)]*\))?",
re.IGNORECASE,
)
def changelog_verification_evidence(root: Path, since_tag: str | None) -> dict[str, dict[str, str | None]]:
"""Parse per-platform manual-verification evidence from this cycle's CHANGELOG.
Returns {platform: {date, tag}}. A single douyin line must never satisfy
alipay (the global-boolean bug, codex sixth audit); a tag that does not
equal the candidate tag is not evidence for this release; the evidence
date must also match every facts.md verified date for that platform.
"""
changelog = root / "CHANGELOG.md"
empty: dict[str, dict[str, str | None]] = {}
if not changelog.is_file():
return empty
text = changelog.read_text(encoding="utf-8")
if since_tag:
version = since_tag.lstrip("v")
# match the version header with or without a trailing suffix
# ("## 3.1.6 - date" or "## 3.1.6\n"); a bare "## 3.1.6 " with a
# trailing space missed headers written without one.
for marker in (f"\n## {version} ", f"\n## {version}\n"):
idx = text.find(marker)
if idx > 0:
text = text[: idx + 1]
break
else:
first = text.find("\n## ")
if first >= 0:
second = text.find("\n## ", first + 1)
text = text[first:second] if second > 0 else text[first:]
evidence: dict[str, dict[str, str | None]] = {}
for m in PLATFORM_VERIFICATION_RE.finditer(text):
entry = {"date": m.group("date"), "tag": m.group("tag")}
matched = m.group(0).lower()
for platform in MANUAL_ONLY_PLATFORMS:
if platform in matched:
evidence[platform] = dict(entry)
return evidence
def _valid_utc_date(value: str | None) -> bool:
if not value:
return False
try:
datetime.strptime(value, "%Y-%m-%d")
return True
except ValueError:
return False
def manual_verification_status(
root: Path,
level: str,
classes: dict[str, int],
since_tag: str | None = None,
candidate_tag: str | None = None,
) -> dict[str, Any]:
"""Check manual-only platform fact verification against the release policy.
Evidence is per-platform, from THIS cycle's CHANGELOG block, and must
carry the candidate tag (option a). Checks per platform:
- evidence exists for THIS platform (a douyin line never covers alipay)
- evidence tag == candidate tag when a candidate is supplied
- evidence date is a valid UTC date
- every facts.md verified date for the platform == evidence date
Level rules: major requires both platforms; minor requires platforms that
are stale (>90d) or touched by this release (data class); patch requires
platforms whose facts this release touches.
"""
now = datetime.now(timezone.utc)
evidence = changelog_verification_evidence(root, since_tag)
details: dict[str, Any] = {}
required = False
for platform in MANUAL_ONLY_PLATFORMS:
facts_path = root / "platforms" / platform / "facts.md"
if not facts_path.is_file():
# Platform directory absent in this tree (fixture or trimmed repo):
# no facts to verify. Structural completeness (all bundled platforms
# present) is enforced by validate_suite's rule-map/facts binding,
# not by the verification gate.
details[platform] = {"status": "no-facts-file", "needs_verification": False,
"why": ["platform not present in this tree"]}
continue
verified_dates = [
m.group("verified")
for m in FACT_ANNOTATION.finditer(facts_path.read_text(encoding="utf-8"))
]
unknown = [v for v in verified_dates if v == "unknown"]
dated = []
for value in verified_dates:
try:
dated.append(datetime.strptime(value, "%Y-%m-%d").replace(tzinfo=timezone.utc))
except ValueError:
continue
oldest = min(dated) if dated else None
# does this release REQUIRE verification for this platform?
must_verify = False
trigger = ""
if level == "major":
must_verify = True
trigger = "major release requires both manual-only platforms"
elif level == "minor":
if classes.get("data"):
must_verify = True
trigger = "this release touches platform fact data"
elif oldest is None or now - oldest > timedelta(days=VERIFICATION_MAX_AGE_DAYS):
must_verify = True
trigger = f"last verification older than {VERIFICATION_MAX_AGE_DAYS} days"
elif classes.get("data"):
must_verify = True
trigger = "this release touches platform fact data"
if not must_verify:
details[platform] = {
"needs_verification": False,
"why": ["no verification trigger for this platform at this level"],
"unknown_count": len(unknown),
"oldest_verified": oldest.date().isoformat() if oldest else None,
}
continue
why: list[str] = [trigger]
ev = evidence.get(platform)
if ev is None:
why.append(f"no {platform} evidence line in this cycle's CHANGELOG")
else:
if candidate_tag and ev.get("tag") != candidate_tag:
why.append(f"evidence tag {ev.get('tag')} != candidate {candidate_tag}")
if not _valid_utc_date(ev.get("date")):
why.append("evidence date is not a valid UTC date")
# every fact's verified date must equal the evidence date
mismatched = [v for v in verified_dates if v != ev.get("date")]
if mismatched:
why.append(f"{len(mismatched)} fact(s) verified date != evidence date {ev.get('date')}")
if unknown:
why.append(f"{len(unknown)} fact(s) still verified=unknown")
needs = bool(why[1:]) or bool(unknown)
if needs:
required = True
details[platform] = {
"needs_verification": needs,
"why": why,
"unknown_count": len(unknown),
"oldest_verified": oldest.date().isoformat() if oldest else None,
}
return {"required": required, "platforms": details, "evidence": evidence}
def recommend(root: Path | str, min_data_changes: int, candidate_tag: str | None = None) -> dict[str, Any]:
root = Path(root)
baseline_tag: str | None
# Every recommendation mode needs real history. Without this common guard,
# no-candidate callers (notably drift_audit in Actions) treat a depth-1
# checkout as a root commit, classify the entire tree, and falsely report
# history_complete=true.
if is_shallow_repository(root):
return {
"recommendation": "MANUAL_VERIFICATION_REQUIRED",
"level": None,
"reasons": ["shallow repository history is incomplete; fetch full history and tags"],
"tag": candidate_tag,
"baseline_tag": None,
"commit_count": 0,
"classes": {},
"history_complete": False,
"manual_verification": {"required": True, "platforms": {}, "evidence": {}},
}
if candidate_tag:
# Release checkout: HEAD sits on the candidate tag. The baseline must be
# the tag BEFORE the candidate (via its parent), never the candidate
# itself; and HEAD must actually be the candidate commit.
candidate_commit = tag_commit(root, candidate_tag)
current_head = head_commit(root)
if candidate_commit is None:
return {"recommendation": "MANUAL_VERIFICATION_REQUIRED", "level": None,
"reasons": [f"candidate tag {candidate_tag} not found in repository"],
"tag": candidate_tag, "baseline_tag": None, "commit_count": 0, "classes": {},
"history_complete": True,
"manual_verification": {"required": True, "platforms": {}, "evidence": {}}}
if current_head != candidate_commit:
return {"recommendation": "MANUAL_VERIFICATION_REQUIRED", "level": None,
"reasons": [f"HEAD {str(current_head)[:8]} != candidate tag commit {candidate_commit[:8]}"],
"tag": candidate_tag, "baseline_tag": None, "commit_count": 0, "classes": {},
"history_complete": True,
"manual_verification": {"required": True, "platforms": {}, "evidence": {}}}
baseline_tag = last_tag(root, before=f"{candidate_tag}^") or last_tag(root, before=candidate_tag)
if baseline_tag == candidate_tag:
baseline_tag = None
if baseline_tag is None:
return {
"recommendation": "MANUAL_VERIFICATION_REQUIRED",
"level": None,
"reasons": ["no preceding release tag found for candidate; release history is incomplete"],
"tag": candidate_tag,
"baseline_tag": None,
"commit_count": 0,
"classes": {},
"history_complete": False,
"manual_verification": {"required": True, "platforms": {}, "evidence": {}},
}
tag = baseline_tag
else:
tag = last_tag(root)
commits = collect_commits(root, tag)
if not commits:
if candidate_tag:
# A candidate release with zero commits since baseline is anomalous
# (double-tagged or mis-sequenced): must block, not HOLD-through.
return {"recommendation": "MANUAL_VERIFICATION_REQUIRED", "level": None,
"reasons": ["no commits between baseline tag and candidate tag"],
"tag": tag, "baseline_tag": tag, "commit_count": 0, "classes": {},
"history_complete": True,
"manual_verification": {"required": True, "platforms": {}, "evidence": {}}}
return {"recommendation": "HOLD", "level": None, "reasons": ["no-commits-since-last-tag"], "tag": tag,
"baseline_tag": None, "commit_count": 0, "classes": {}, "history_complete": True}
classes: dict[str, int] = {}
for commit in commits:
# Full class SET per commit: a scripts+facts commit counts as both
# tooling and data, so the data trigger for manual verification cannot
# be swallowed by the higher-ranked label (codex probe).
commit_classes = classify_commit_classes(commit["paths"])
# Release-metadata-only commits (VERSION + root SKILL.md frontmatter
# version bump) are reclassified to metadata, not behavior (P1-02).
if "behavior" in commit_classes:
if commit_paths_are_metadata_only(root, commit["hash"], commit["paths"]):
commit_classes.discard("behavior")
commit_classes.add("metadata")
# Conventional breaking markers upgrade the whole release to major.
if BREAKING_SUBJECT.search(commit.get("subject") or ""):
commit_classes.add("breaking")
# A tooling commit that ADDS capability (feat:) is a compatible
# addition (minor); tooling fixes stay fix-class (patch).
if "tooling" in commit_classes and FEATURE_SUBJECT.match(commit.get("subject") or ""):
commit_classes.add("feature")
for label in commit_classes:
classes[label] = classes.get(label, 0) + 1
# Explicit breaking changes always mean major.
if classes.get("breaking"):
level = "major"
reasons = [f"{classes['breaking']} commit(s) carry breaking-change markers"]
elif classes.get("behavior"):
level = "minor"
reasons = [f"{classes['behavior']} commit(s) touch skill text, guardrails, or the root skill (behavior changes)"]
elif classes.get("feature"):
level = "minor"
reasons = [f"{classes['feature']} commit(s) add compatible tooling capability (feat)"]
elif classes.get("tooling"):
level = "patch"
reasons = [f"{classes['tooling']} commit(s) fix scripts, installer, CI, or tests (tooling fixes)"]
elif classes.get("data"):
if classes["data"] < min_data_changes:
return {
"recommendation": "HOLD",
"level": None,
"reasons": [
f"only {classes['data']} data-only commit(s) since {tag or 'start'}; "
f"threshold is {min_data_changes}; accumulate more or release on demand"
],
"tag": tag, "baseline_tag": tag, "commit_count": len(commits), "classes": classes,
"history_complete": True,
}
level = "patch"
reasons = [f"{classes['data']} commit(s) of platform fact data only; no behavior or methodology changes"]
else:
# Version-metadata-only commits (VERSION bump + root SKILL.md
# version/last_reviewed) release as patch (audit P1-02).
if classes.get("metadata"):
level = "patch"
reasons = [f"{classes['metadata']} commit(s) touch release metadata only (VERSION / frontmatter version fields)"]
else:
return {
"recommendation": "HOLD",
"level": None,
"reasons": ["only documentation/asset changes; release on demand, not required"],
"tag": tag, "baseline_tag": tag, "commit_count": len(commits), "classes": classes,
"history_complete": True,
}
# --- SemVer consistency (audit P1-02): the RECOMMENDED level must match
# the candidate tag's real increment over the baseline. A release whose
# actual increment is SMALLER than required blocks; a larger increment is
# allowed (a patch-worthy change shipped as minor is safe, not silent).
semver: str | None = None
required_level: str = level
downgrade: dict[str, Any] | None = None
if candidate_tag:
semver = semver_bump(tag, candidate_tag) if tag else None
if semver is None:
return {
"recommendation": "MANUAL_VERIFICATION_REQUIRED",
"level": level,
"reasons": [
f"candidate tag {candidate_tag} is not a strict semver bump of baseline {tag or 'none'} "
"(equal, lower, or non-semver); release blocked"
],
"tag": tag, "baseline_tag": tag, "commit_count": len(commits), "classes": classes,
"history_complete": True,
"semver_bump": None,
"required_level": level,
"manual_verification": {"required": True, "platforms": {}, "evidence": {}},
}
if LEVEL_RANK[semver] < LEVEL_RANK[level]:
downgrade = load_downgrade_override(root, candidate_tag, level)
if downgrade is None or not downgrade.get("accepted"):
return {
"recommendation": "MANUAL_VERIFICATION_REQUIRED",
"level": level,
"reasons": [
f"semver bump {semver} is lower than required level {level}; "
"provide a structured one-step downgrade (release-override.json with reason and "
"independent signer) or retag at the required level"
] + (downgrade or {}).get("problems", []),
"tag": tag, "baseline_tag": tag, "commit_count": len(commits), "classes": classes,
"history_complete": True,
"semver_bump": semver,
"required_level": level,
"override": downgrade,
"manual_verification": {"required": True, "platforms": {}, "evidence": {}},
}
required_level = downgrade["to"]
base_result = {
"tag": tag,
"baseline_tag": tag,
"commit_count": len(commits),
"classes": classes,
"history_complete": True,
"semver_bump": semver,
"required_level": required_level,
}
if downgrade and downgrade.get("accepted"):
base_result["override"] = downgrade
verification = manual_verification_status(root, level, classes, since_tag=tag, candidate_tag=candidate_tag)
if verification["required"]:
return {
"recommendation": "MANUAL_VERIFICATION_REQUIRED",
"level": level,
"reasons": reasons + [
f"{platform}: {'; '.join(detail['why'])}"
for platform, detail in verification["platforms"].items()
if detail.get("needs_verification")
],
**base_result,
"manual_verification": verification,
}
return {
"recommendation": "RECOMMEND_RELEASE",
"level": level,
"reasons": reasons,
**base_result,
"manual_verification": verification,
}
def main(argv: Sequence[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("root", nargs="?", type=Path, default=Path("."), help="Repository root")
parser.add_argument("--min-data-changes", type=int, default=1, help="Minimum data commits for a patch release")
parser.add_argument("--candidate-tag", help="Tag being released (e.g. v3.1.7); verification evidence must carry this tag")
parser.add_argument("--format", choices=("json", "text"), default="text")
args = parser.parse_args(argv)
try:
report = recommend(args.root.resolve(), args.min_data_changes, candidate_tag=args.candidate_tag)
except ValueError as exc:
print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
return 2
if args.format == "json":
print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
else:
head = f"{report['recommendation']}" + (f" ({report['level']})" if report.get("level") else "")
print(head)
for reason in report["reasons"]:
print(f"- {reason}")
print(f"- since tag: {report.get('tag') or 'none'}; commits: {report.get('commit_count', 0)}; classes: {report.get('classes', {})}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |