Skip to content

xinetzone/SpecWeave / .agents/skills/bundled-script-exit-code-ambiguity

bundled-script-exit-code-ambiguity

Verified

验证自带脚本的退出码契约时,必须区分「契约检出的 1」与「未捕获异常返回的 1」。必须使用此技能:当用户提到「退出码对了但行为不对」「Traceback 也是退出 1」「目录路径报 IsADirectoryError」「夹具只看退出码」「PASS 但其实是崩了」「异常冒充契约码」时。不用于通用夹具搭建与缺陷注入(用 skill-bundled-script-validation)、质量门掉分修复(用 skill-quality-gate-remediation)或会话取证(用 chat-session-evidence-audit)。

FileKindSize
SKILL.mdskill md10.3 KB
references/verified-case.mdmarkdown4.0 KB
scripts/assert_contract.pyscript3.3 KB

scripts/assert_contract.py

View on GitHub
#!/usr/bin/env python3
"""Assert the three-part contract of a bundled script for one contract path.

Checks, in order: exit code equals the expected value, stdout parses as JSON
(when --json is given), stderr carries no traceback, and stderr is empty
(unless the contract declares diagnostics on this path via --allow-stderr).
A case that reports the expected exit code while emitting a traceback is a
script defect, not a pass.

Exit codes
  0  every assertion for this case held
  1  at least one assertion failed (details on stderr)
  2  usage error, or the command could not be started
"""

import argparse
import json
import subprocess
import sys


def parse_args(argv):
    parser = argparse.ArgumentParser(
        description="Assert exit code, stdout shape, and stderr silence of one contract path."
    )
    parser.add_argument("--expect", type=int, required=True, help="expected exit code")
    parser.add_argument("--json", action="store_true", help="require stdout to parse as JSON")
    parser.add_argument(
        "--allow-stderr",
        action="store_true",
        help="the contract declares diagnostics on this path (a traceback is still a failure)",
    )
    parser.add_argument("--name", default="case", help="label printed in the report")
    parser.add_argument("cmd", nargs=argparse.REMAINDER, help="command to run, after --")
    args = parser.parse_args(argv)
    cmd = args.cmd[1:] if args.cmd[:1] == ["--"] else args.cmd
    if not cmd:
        parser.error("no command given; put it after --")
    return args, cmd


def check_stdout(stdout, require_json):
    if not require_json:
        return None
    if not stdout.strip():
        return "stdout: empty, expected JSON (did the process die before printing?)"
    try:
        json.loads(stdout)
    except ValueError as exc:
        return f"stdout: not JSON ({exc})"
    return None


def main(argv=None):
    args, cmd = parse_args(sys.argv[1:] if argv is None else argv)
    try:
        proc = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            encoding="utf-8",
            errors="replace",
        )
    except OSError as exc:
        print(f"cannot execute {cmd[0]}: {exc}", file=sys.stderr)
        return 2

    failures = []
    if proc.returncode != args.expect:
        failures.append(f"exit code: expected {args.expect}, got {proc.returncode}")
    stdout_problem = check_stdout(proc.stdout, args.json)
    if stdout_problem:
        failures.append(stdout_problem)
    if "Traceback (most recent call last)" in proc.stderr:
        failures.append("stderr: traceback present (untrapped exception)")
    elif not args.allow_stderr and proc.stderr.strip():
        failures.append("stderr: not empty (undeclared diagnostic)")

    if not failures:
        shape = "json" if args.json else "unchecked"
        diag = "declared" if args.allow_stderr else "empty"
        print(f"PASS {args.name}: exit={proc.returncode} stdout={shape} stderr={diag}")
        return 0

    print(f"FAIL {args.name}: exit={proc.returncode}", file=sys.stderr)
    for item in failures:
        print(f"  - {item}", file=sys.stderr)
    if proc.stderr.strip():
        print("--- captured stderr ---", file=sys.stderr)
        print(proc.stderr.rstrip(), file=sys.stderr)
    return 1


if __name__ == "__main__":
    sys.exit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall