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)。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.3 KB |
| references/verified-case.md | markdown | 4.0 KB |
| scripts/assert_contract.py | script | 3.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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 466k | Updated | Claude CodeCodex | Verified | Install |
| 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: 466k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |