refactor: 문서 개선 중

scripts/run-ledger.py

@@ -229,15 +229,34 @@ def cmd_begin(args) -> int:
 
 
 def cmd_gate(args) -> int:
+    status = args.status or ("PASS" if args.exit_code == 0 else "FAIL")
+    if status == "PASS" and args.exit_code != 0:
+        raise Contract("PASS 관문은 exit 0 이어야 한다")
+    if status == "FAIL" and args.exit_code == 0:
+        raise Contract("FAIL 관문은 exit 0 으로 적을 수 없다")
+    if status == "UNVERIFIABLE":
+        if args.exit_code == 0:
+            raise Contract("UNVERIFIABLE 관문은 실제 대조 실패의 non-zero exit를 보존해야 한다")
+        if not (args.reason or "").strip():
+            raise Contract("UNVERIFIABLE 관문은 --reason 으로 대조하지 못한 이유를 적는다")
     with Ledger(args.ledger) as led:
         st = led.stage(args.stage)
         _require_owner(st, args.session, args.generation)
-        st.setdefault("gates", []).append({
+        gate = {
             "cmd": args.cmd, "exit": args.exit_code,
+            "status": status,
             "session": args.session or None, "generation": int(st.get("generation", 0)),
-            "at": _now()})
+            "at": _now(),
+        }
+        if args.semantic_id:
+            gate["semanticId"] = args.semantic_id
+        if args.reason:
+            gate["reason"] = args.reason
+        if args.accepted_by_project_review:
+            gate["acceptedByProjectReview"] = True
+        st.setdefault("gates", []).append(gate)
         led.save()
-        print(f"{args.stage} 관문 {len(st['gates'])}개 · 방금 것 exit={args.exit_code}"
+        print(f"{args.stage} 관문 {len(st['gates'])}개 · 방금 것 {status} exit={args.exit_code}"
               f" · {args.session or '세션 미기재'}")
     return 0
 
@@ -299,9 +318,12 @@ def cmd_status(args) -> int:
             mark = {"DONE": "✓", "SKIPPED": "–", "RUNNING": "▶", "FAILED": "✗"}.get(
                 st.get("status"), " ")
             gates = st.get("gates") or []
-            bad = [g for g in gates if g.get("exit") not in (0, "0")]
+            unverifiable = [g for g in gates if g.get("status") == "UNVERIFIABLE"]
+            bad = [g for g in gates
+                   if g.get("status") != "UNVERIFIABLE" and g.get("exit") not in (0, "0")]
             print(f"  {mark} {st['id']} {st.get('status'):<8} "
                   f"{st.get('elapsedSeconds', 0):>5}초 · 관문 {len(gates)}"
+                  + (f" (대조 불가 {len(unverifiable)})" if unverifiable else "")
                   + (f" (exit≠0 {len(bad)})" if bad else ""))
         riders = d.get("riders") or []
         if riders:
@@ -339,6 +361,10 @@ def main() -> int:
     p = sub.add_parser("gate"); p.add_argument("ledger")
     p.add_argument("--stage", required=True); p.add_argument("--cmd", required=True)
     p.add_argument("--exit", dest="exit_code", type=int, required=True)
+    p.add_argument("--semantic-id")
+    p.add_argument("--status", choices=["PASS", "UNVERIFIABLE", "FAIL"])
+    p.add_argument("--reason")
+    p.add_argument("--accepted-by-project-review", action="store_true")
     p.add_argument("--session", default=""); p.add_argument("--generation", type=int)
     p.set_defaults(fn=cmd_gate)