okstra 0.159.0 → 0.161.0

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -0,0 +1,207 @@
+"""The worker audit-sidecar contract, shared by Phase 7 and the mid-run check.
+
+Phase 7 has always enforced this post-hoc, but by then the worker session is
+gone and the only remedies left are editing the result after the fact — which
+breaks the audit chain — or failing the run. `okstra worker-audit-check` runs
+the same rules the moment a worker returns, while the worker is still listening
+and can fix its own citation. Both consumers must agree on what a violation is,
+so the rules live here rather than inside either one — the same split
+`worker_heartbeat` makes for the heartbeat cadence.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from okstra_ctl.worker_prompt_headers import EVIDENCE_LEDGER_HEADER
+
+# Worker-results filename pattern: `<worker-role>-<task-type>-<seq>.md`.
+# Every analysis-worker role name ends in `-worker` (`claude-worker`,
+# `codex-worker`, `antigravity-worker`, `report-writer-worker`), so anchor the
+# split on that suffix — otherwise `antigravity-worker-error-analysis-001.md`
+# ambiguously parses as `worker=antigravity, task=worker-error-analysis`.
+# Audit sidecars (`*-audit-*`) and errors sidecars (`.json`) are not matched here.
+_WORKER_RESULT_BASENAME_RE = re.compile(
+    r"^(?P<worker>[a-z][a-z0-9-]*-worker)-(?P<task_type>[a-z][a-z-]*?)-(?P<seq>\d{3})\.md$"
+)
+
+READING_CONFIRMATION_HEADING_RE = re.compile(
+    r"^##[ \t]+0\.[ \t]+Reading Confirmation\b", re.MULTILINE
+)
+
+_EVIDENCE_READ_RE = re.compile(
+    r"^- Evidence read: `(?P<path>[^`\n]+)`\s*$",
+    re.MULTILINE,
+)
+_FILE_LINE_CITATION_RE = re.compile(
+    r"`(?P<path>(?!https?://)[^`\n]+?):(?P<line>\d+(?:-\d+)?)`"
+)
+_EXTENSIONLESS_SOURCE_FILENAMES = frozenset(
+    {"Dockerfile", "Justfile", "Makefile", "Procfile", "Rakefile"}
+)
+
+
+def _looks_like_file_path(path: str) -> bool:
+    if (
+        not path
+        or path.startswith(("-", "$"))
+        or any(char.isspace() for char in path)
+    ):
+        return False
+    if re.fullmatch(r"[0-9a-fA-F]{7,64}", path):
+        return False
+    return (
+        "/" in path
+        or "." in Path(path).name
+        or Path(path).name in _EXTENSIONLESS_SOURCE_FILENAMES
+    )
+
+
+def _cited_file_paths(content: str) -> set[str]:
+    paths: set[str] = set()
+    for match in _FILE_LINE_CITATION_RE.finditer(content):
+        path = match.group("path")
+        if _looks_like_file_path(path):
+            paths.add(path)
+    return paths
+
+
+def _audit_evidence_read_paths(content: str) -> set[str]:
+    return {
+        match.group("path")
+        for match in _EVIDENCE_READ_RE.finditer(content)
+    }
+
+
+def _worker_prompt_path(
+    run_dir: Path,
+    worker_role: str,
+    task_type: str,
+    seq: str,
+) -> Path:
+    return run_dir / "prompts" / f"{worker_role}-prompt-{task_type}-{seq}.md"
+
+
+def _evidence_read_ledger_failures(
+    *,
+    run_dir: Path,
+    worker_role: str,
+    task_type: str,
+    seq: str,
+    result_name: str,
+    result_content: str,
+    audit_path: Path,
+) -> list[str]:
+    if worker_role == "report-writer-worker":
+        return []
+    prompt_path = _worker_prompt_path(run_dir, worker_role, task_type, seq)
+    try:
+        prompt_content = prompt_path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    if EVIDENCE_LEDGER_HEADER not in prompt_content.splitlines():
+        return []
+    try:
+        audit_content = audit_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return [f"worker audit sidecar unreadable: {audit_path.name} ({exc})"]
+
+    missing_paths = sorted(
+        _cited_file_paths(result_content) - _audit_evidence_read_paths(audit_content)
+    )
+    return [
+        f"worker `{worker_role}` result `{result_name}` cites "
+        f"`{missing_path}:line` without an Evidence read row for "
+        f"`{missing_path}` in `{audit_path.name}`"
+        for missing_path in missing_paths
+    ]
+
+
+def _result_files(run_dir: Path, task_type: str, seq: str | None, worker: str | None):
+    """Every worker-results file in *run_dir* this check owns, in name order."""
+    for path in sorted((run_dir / "worker-results").glob("*.md")):
+        if "-audit-" in path.name:
+            continue
+        match = _WORKER_RESULT_BASENAME_RE.match(path.name)
+        if match is None:
+            # Files that don't match the canonical pattern (e.g. ad-hoc notes
+            # left by the operator) are out of contract scope.
+            continue
+        if match.group("task_type") != task_type:
+            # Cross-phase artifacts shouldn't appear here; skip rather than
+            # fail to keep the check focused on the current phase.
+            continue
+        if seq is not None and match.group("seq") != seq:
+            # A prior run's artifact. Its contract was judged when it ran.
+            continue
+        if worker is not None and match.group("worker") != worker:
+            continue
+        yield path, match.group("worker"), match.group("seq")
+
+
+def check_worker_results_audit(
+    run_dir: Path,
+    task_type: str,
+    seq: str | None,
+    *,
+    worker: str | None = None,
+) -> list[str]:
+    """Every audit-sidecar contract failure among this run's worker results.
+
+    *run_dir* is `runs/<task-type>/`; `worker-results/` and `prompts/` hang off
+    it. *seq* scopes the check to one run — `worker-results/` accumulates every
+    run's artifacts, so scanning the whole directory judged a run by files it
+    did not produce. Pass ``None`` only when the seq is genuinely unknown, which
+    falls back to not filtering rather than silently checking nothing.
+
+    For each result file this checks that it carries no `## 0. Reading
+    Confirmation` heading (that block moved to the sidecar), that the matching
+    sidecar exists, and — for prompts carrying the required-v1 evidence-ledger
+    marker — that every backticked `path:line` citation has an Evidence read row.
+    """
+    failures: list[str] = []
+    if not (run_dir / "worker-results").is_dir():
+        # No worker-results directory means no analysis workers ran (e.g.
+        # `release-handoff`, which is single-lead). Nothing to enforce.
+        return failures
+
+    for path, worker_role, result_seq in _result_files(run_dir, task_type, seq, worker):
+        rel = path.name
+        try:
+            content = path.read_text()
+        except OSError as exc:
+            failures.append(f"worker-results file unreadable: {rel} ({exc})")
+            continue
+
+        if READING_CONFIRMATION_HEADING_RE.search(content) is not None:
+            failures.append(
+                f"worker-results file `{rel}` contains a `## 0. Reading "
+                f"Confirmation` heading — that block moved to the audit "
+                f"sidecar (`{worker_role}-audit-{task_type}-{result_seq}.md`). "
+                f"Remove the §0 heading + body from the main file and "
+                f"write a fresh sidecar."
+            )
+
+        audit_path = (
+            run_dir / "worker-results"
+            / f"{worker_role}-audit-{task_type}-{result_seq}.md"
+        )
+        if not audit_path.exists():
+            failures.append(
+                f"worker `{worker_role}` produced `{rel}` but no audit sidecar "
+                f"at `{audit_path.name}` — the sidecar must carry the Reading "
+                f"Confirmation block (one short line per input file). Workers "
+                f"write this in the same step as the main worker-results file."
+            )
+            continue
+
+        failures.extend(_evidence_read_ledger_failures(
+            run_dir=run_dir,
+            worker_role=worker_role,
+            task_type=task_type,
+            seq=result_seq,
+            result_name=rel,
+            result_content=content,
+            audit_path=audit_path,
+        ))
+    return failures

package/runtime/python/okstra_ctl/worker_heartbeat.py

@@ -18,6 +18,10 @@ HEARTBEAT_LINE_RE = re.compile(
     r"^-[ \t]*PROGRESS:[ \t]*(?P<stage>\S+)[ \t]+(?P<ts>\S+)[ \t]*$", re.MULTILINE
 )
 
+# 한 단계가 cadence 보다 길어질 때 워커가 append 하는 진행 라인의 접두사
+# (claude-worker.md "Heartbeat"). 뒤에 붙는 stage 이름은 원래 단계 그대로다.
+IN_STAGE_PREFIX = "in-stage:"
+
 # 계약상 cadence 는 5분. append 직전 측정한 시각과 실제 쓰기 사이 지연을 흡수하는
 # 고정 grace 60초를 더한다.
 HEARTBEAT_MAX_GAP_SECONDS = 5 * 60 + 60
@@ -48,10 +52,12 @@ def max_gap_seconds_after(stage: str) -> int:
     """*stage* 를 알린 뒤 다음 하트비트까지 허용되는 최대 공백(초).
 
     간격이 재는 것은 직전에 선언된 단계의 작업 시간이므로, 예산은 언제나
-    구간을 *여는* 단계에서 고른다."""
-    if stage in SINGLE_WRITE_STAGES:
+    구간을 *여는* 단계에서 고른다. `in-stage:<X>` 는 아직 X 안에 있다는 뜻이라
+    그 라인이 여는 구간도 여전히 X 의 일부다 — 접두사를 떼고 X 의 예산을 쓴다."""
+    opener = stage.removeprefix(IN_STAGE_PREFIX)
+    if opener in SINGLE_WRITE_STAGES:
         return SINGLE_WRITE_MAX_GAP_SECONDS
-    if stage in SYNTHESIS_STAGES:
+    if opener in SYNTHESIS_STAGES:
         return SYNTHESIS_MAX_GAP_SECONDS
     return HEARTBEAT_MAX_GAP_SECONDS
 

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -54,6 +54,14 @@ DEFAULT_LAUNCH_GRACE_SECONDS = 60
 DEFAULT_POLL_INTERVAL_SECONDS = 20.0
 DEFAULT_WAIT_TIMEOUT_SECONDS = 2400.0
 
+# A budget breach is one observation, and "slow" and "dead" are only
+# distinguishable across two. On a breach the probe re-reads the sidecar this
+# far into the future — a fraction of the stage's own budget, so a stage with a
+# longer budget also gets a longer confirmation. Measured false positives this
+# absorbs (dev-10400): `analysis` 386s against a 360s budget,
+# `data-json-write-start` 1602s against 1260s.
+DEFAULT_STALL_CONFIRM_RATIO = 0.5
+
 
 def _utc_now() -> datetime:
     return datetime.now(timezone.utc)
@@ -183,13 +191,58 @@ class ProbeTarget:
     result_path: Path | None = None
 
 
-def probe_one(target: ProbeTarget, *, now: datetime, max_idle: float,
-              launch_grace: float) -> dict:
-    if target.liveness_mode == LIVENESS_AUDIT_HEARTBEAT:
-        return probe_heartbeat(
-            target.artifact, target.dispatched_at, now, max_idle, launch_grace
-        )
-    return probe_launch(target.artifact, target.dispatched_at, now, launch_grace)
+def _confirm_window(probe: dict, stall_confirm: float | None) -> float:
+    """Seconds to wait before a budget breach becomes a verdict.
+
+    Only a breach carries ``budgetSeconds``. The other stalled shapes — a
+    sidecar with no heartbeat at all, a newest beat that predates this dispatch
+    — are not "the worker is mid-tool-call", so waiting tells us nothing new
+    about them.
+    """
+    if "budgetSeconds" not in probe:
+        return 0.0
+    if stall_confirm is not None:
+        return max(0.0, float(stall_confirm))
+    return probe["budgetSeconds"] * DEFAULT_STALL_CONFIRM_RATIO
+
+
+def probe_one(
+    target: ProbeTarget,
+    *,
+    now: datetime,
+    max_idle: float,
+    launch_grace: float,
+    stall_confirm: float | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], datetime] = _utc_now,
+) -> dict:
+    """One worker's verdict, with a budget breach confirmed before it stands.
+
+    The wait this costs is bounded by the confirmation window; what the probe
+    exists to avoid is paying ``DEFAULT_WAIT_TIMEOUT_SECONDS`` for a worker that
+    died early, and that is still never paid.
+    """
+    if target.liveness_mode != LIVENESS_AUDIT_HEARTBEAT:
+        return probe_launch(target.artifact, target.dispatched_at, now, launch_grace)
+    probe = probe_heartbeat(
+        target.artifact, target.dispatched_at, now, max_idle, launch_grace
+    )
+    if probe["state"] != "stalled":
+        return probe
+    window = _confirm_window(probe, stall_confirm)
+    if window <= 0:
+        return probe
+    sleep(window)
+    confirmed = probe_heartbeat(
+        target.artifact, target.dispatched_at, clock(), max_idle, launch_grace
+    )
+    if confirmed.get("lastHeartbeat") == probe.get("lastHeartbeat"):
+        return confirmed
+    # The question the window asks is whether the heartbeat moved, not whether
+    # the re-read is healthy on its own terms. A beat opening a stage with a
+    # smaller budget than the window we just slept reads as stale the instant it
+    # lands, which would call a worker dead for proving it is alive.
+    return {**confirmed, "state": "live", "reason": ""}
 
 
 def probe_all(
@@ -198,9 +251,15 @@ def probe_all(
     now: datetime,
     max_idle: float,
     launch_grace: float,
+    stall_confirm: float | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], datetime] = _utc_now,
 ) -> dict:
     probes = [
-        probe_one(t, now=now, max_idle=max_idle, launch_grace=launch_grace)
+        probe_one(
+            t, now=now, max_idle=max_idle, launch_grace=launch_grace,
+            stall_confirm=stall_confirm, sleep=sleep, clock=clock,
+        )
         for t in targets
     ]
     unhealthy = [p for p in probes if p["state"] in ("stalled", "did-not-launch")]
@@ -221,6 +280,7 @@ def wait_for_results(
     launch_grace: float,
     interval: float,
     timeout: float,
+    stall_confirm: float | None = None,
     clock: Callable[[], datetime] = _utc_now,
     sleep: Callable[[float], None] = time.sleep,
 ) -> dict:
@@ -239,7 +299,8 @@ def wait_for_results(
     while True:
         now = clock()
         result = probe_all(
-            targets, now=now, max_idle=max_idle, launch_grace=launch_grace
+            targets, now=now, max_idle=max_idle, launch_grace=launch_grace,
+            stall_confirm=stall_confirm, sleep=sleep, clock=clock,
         )
         pending = [
             str(t.result_path) for t in targets if not result_ready(t)
@@ -367,6 +428,15 @@ def main(argv: list[str] | None = None) -> int:
                         help="--wait poll interval in seconds")
     parser.add_argument("--timeout", type=float, default=DEFAULT_WAIT_TIMEOUT_SECONDS,
                         help="--wait deadline in seconds")
+    parser.add_argument(
+        "--stall-confirm", type=float, default=None,
+        help=(
+            "seconds to re-check a heartbeat budget breach before calling it "
+            "stalled (default: half that stage's budget; 0 disables). A slow "
+            "worker appends its next heartbeat inside this window; a dead one "
+            "does not."
+        ),
+    )
     args = parser.parse_args(argv)
 
     if len(args.team_state) != len(args.worker):
@@ -388,6 +458,7 @@ def main(argv: list[str] | None = None) -> int:
             now=_utc_now(),
             max_idle=args.max_idle,
             launch_grace=args.launch_grace,
+            stall_confirm=args.stall_confirm,
         )
         print(json.dumps(result, ensure_ascii=False, indent=2))
         # Non-zero on an unhealthy worker so a poll loop can branch on the exit
@@ -410,6 +481,7 @@ def main(argv: list[str] | None = None) -> int:
         launch_grace=args.launch_grace,
         interval=args.interval,
         timeout=args.timeout,
+        stall_confirm=args.stall_confirm,
     )
     print(json.dumps(result, ensure_ascii=False, indent=2))
     return {"completed": 0, "unhealthy": 1}.get(result["outcome"], 2)

package/runtime/schemas/final-report-v1.0.schema.json

@@ -2959,6 +2959,20 @@
       "required": ["roundCount", "gateResult", "planItems", "dissentLog"],
       "additionalProperties": false,
       "properties": {
+        "uniformVerifiers": {
+          "type": "array",
+          "description": "Verifiers whose every vote this round was one verdict. Advisory: a unanimous round is legitimate, but the gate reads as a three-way cross-check unless this sits beside it.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["worker", "verdict", "itemCount"],
+            "properties": {
+              "worker": { "type": "string", "minLength": 1 },
+              "verdict": { "type": "string", "minLength": 1 },
+              "itemCount": { "type": "integer", "minimum": 1 }
+            }
+          }
+        },
         "roundCount": { "type": "integer", "minimum": 0 },
         "gateResult": {
           "enum": [

package/runtime/schemas/final-report-v2.0.schema.json

@@ -1703,6 +1703,28 @@
       "enum": ["open", "answered", "resolved", "obsolete"]
     },
 
+    "ClarificationScopeToken": {
+      "enum": ["in-repo", "cross-repo", "new-schema", "deferrable"]
+    },
+
+    "ClarificationOption": {
+      "type": "object",
+      "required": ["role", "answer", "rationale", "scopeImpact", "addedWork", "directionChange"],
+      "additionalProperties": false,
+      "properties": {
+        "role": { "enum": ["recommended", "alternative"] },
+        "answer": { "type": "string", "minLength": 1 },
+        "rationale": { "type": "string", "minLength": 1 },
+        "scopeImpact": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/ClarificationScopeToken" }
+        },
+        "addedWork": { "type": "string", "minLength": 1 },
+        "directionChange": { "type": "string", "minLength": 1 }
+      }
+    },
+
     "WorkerStatus": {
       "enum": ["completed", "error", "timeout", "not-run", "synthesis-only"]
     },
@@ -3740,6 +3762,20 @@
       "required": ["roundCount", "gateResult", "planItems", "dissentLog"],
       "additionalProperties": false,
       "properties": {
+        "uniformVerifiers": {
+          "type": "array",
+          "description": "Verifiers whose every vote this round was one verdict. Advisory: a unanimous round is legitimate, but the gate reads as a three-way cross-check unless this sits beside it.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["worker", "verdict", "itemCount"],
+            "properties": {
+              "worker": { "type": "string", "minLength": 1 },
+              "verdict": { "type": "string", "minLength": 1 },
+              "itemCount": { "type": "integer", "minimum": 1 }
+            }
+          }
+        },
         "roundCount": { "type": "integer", "minimum": 0 },
         "gateResult": {
           "enum": [
@@ -4078,6 +4114,15 @@
       "type": "object",
       "required": ["id", "ticketId", "kind", "statement", "expectedForm", "blocks", "status"],
       "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": { "kind": { "const": "decision" } },
+            "required": ["kind"]
+          },
+          "then": { "required": ["options"] }
+        }
+      ],
       "properties": {
         "id": { "type": "string", "pattern": "^C-\\d{3,}$" },
         "ticketId": { "$ref": "#/$defs/TicketId" },
@@ -4086,7 +4131,12 @@
         "expectedForm": { "type": "string", "minLength": 1 },
         "blocks": { "$ref": "#/$defs/ClarificationBlocks" },
         "status": { "$ref": "#/$defs/ClarificationStatus" },
-        "userInput": { "type": "string" }
+        "userInput": { "type": "string" },
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "items": { "$ref": "#/$defs/ClarificationOption" }
+        }
       }
     },
 

package/runtime/skills/okstra-inspect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: okstra-inspect
 description: >-
-  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (verdict / pass); its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (error report). Also bundles cross-project okstra errors into an anonymized feedback zip (error feedback). Use it even for a bare "mark it done" or "where's the report." NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
+  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (verdict / pass); its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (error report). Also turns cross-project okstra errors into an anonymized zip (error feedback) or GitHub issues (file okstra issues), and audits run health across tasks (run audit). NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
 ---
 
 # OKSTRA Inspect
@@ -18,6 +18,8 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `cost` | `facets/cost.md` | Estimate file/read context cost for a task bundle. |
 | `errors` | `facets/errors.md` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
 | `error-zip` | `facets/error-zip.md` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
+| `error-issue` | `facets/error-issue.md` | Turn cross-project okstra anomalies into GitHub issue candidates; file the approved ones after explicit user approval. |
+| `run-audit` | `facets/run-audit.md` | Check every run's artifacts against progress invariants; report what went wrong without an error ever being logged. |
 | `recap` | `facets/recap.md` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
 
 ## Step 0: Preflight (shared)

package/runtime/skills/okstra-inspect/facets/error-issue.md

@@ -0,0 +1,77 @@
+# okstra-inspect facet — error-issue
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## error-issue
+
+Trigger phrases: "okstra error-issue", "issue candidates", "file okstra issues", "report okstra defects".
+
+Turn okstra run anomalies into GitHub issue candidates, then file the approved ones. Read-only over every target's `.okstra/`. Apart from the plan file you edit between the two commands, the only write is the GitHub issue — and that only after the user approves.
+
+**Never run `submit` without an explicit user approval in this session.** `plan` is free to run unattended; `submit` is not.
+
+### error-issue.1 — Build the plan
+
+```bash
+okstra error-issue plan --out ~/.okstra/error-issue-plan.json
+```
+
+Parse the stdout JSON: `candidateCount`, `belowGate`, `notOkstraDefect`, `conflicted`, `unreachableRuns`.
+
+`candidateCount` includes candidates whose action is already `skip`, so it is not the number of issues that will be filed. Report the filed count from the create/comment rows of the board below.
+
+### error-issue.2 — Review each candidate's classification
+
+Read the plan file. For each candidate, verify the recorded `classification` against its `signals` list. The classification was computed by `issue_signals.classify`; your job is to confirm it reads correctly against the raw evidence, not to invent a new one.
+
+If a candidate's signals do not support its classification, drop it from the plan file rather than arguing with it in prose. If deciding requires reading the raw `stderrExcerpt`, add an evidence entry and quote the line — an evidence entry always carries all three of `signal`, `value`, `source`, so write `{"signal": "<the signal it backs>", "value": "<the quoted line>", "source": "message excerpt"}`. `submit` rejects an entry missing any of the three; a two-key entry is not a lighter form of evidence, it is an unreadable one.
+
+### error-issue.3 — Present the approval board (Korean)
+
+First state the destination on its own line — `plan.json` 의 `repo` 값을 그대로 읽어 `등록 대상: <repo>` 로 적는다. 이 값은 `~/.okstra/error-issue.json` 이 덮어쓸 수 있으므로 okstra 레포라고 단정하지 않는다. CLI 가 `repo` 없는 plan 을 거부하는 이유가 바로 이것 — 목적지는 승인 화면에 반드시 있어야 할 값이다.
+
+Then show two tables, never merged into one.
+
+**등록 예정** — candidates whose action is `create` or `comment`. `title` 열은 실제로 올라갈 제목 그대로 싣는다. 그것이 없으면 "승인 화면에서 본 것과 올라가는 것이 같다"가 성립하지 않는다:
+
+| # | action | title | fingerprint | errorType / phase | 발생 | 지지 신호(`evidence`) | 기존 이슈 |
+|---|---|---|---|---|---:|---|---|
+
+**보류** — candidates whose action is already `skip`. They are NOT filed; they are shown so the human sees what was set aside. `skip` has two distinct origins and the row must say which:
+
+- **반대 신호** — `conflictingSignals` is non-empty. `classify` called it an okstra defect while another signal pointed elsewhere.
+- **이미 보고됨** — `conflictingSignals` is empty and `existingIssue` is set. An open issue already covers the last occurrence, so there is nothing new to say.
+
+| # | fingerprint | errorType / phase | 발생 | 보류 사유 | 지지 신호 | 반대 신호 / 기존 이슈 |
+|---|---|---|---:|---|---|---|
+
+**본문** — then, for every `등록 예정` row, print that candidate's `body` **whole and verbatim** in a fenced block, one block per row, labelled with the same `#`. Never elide a section. The table summarizes; the body is what actually gets posted, and "승인 화면에서 본 것과 올라가는 것이 같다" is this facet's whole claim — a title plus a signal list does not carry it.
+
+Bodies are bounded by construction: every line is derived (counts, signal values, invariant names) except the one representative message, which shares its source with the `title` in the same row. The raw error records are deliberately NOT in the body — their free text carries the reporting project's ticket ids and source filenames, and no shape rule can separate those from okstra's own vocabulary. They stay in the candidate's `records` in `plan.json` and in the `okstra error-zip` archive. If you need to vet them, read `plan.json` locally; do not paste them into the body.
+
+Then ask via `AskUserQuestion` (options: 전부 등록 / 일부만 선택 / 등록 안 함). Deselected candidates are removed from the plan file before submit.
+
+A held candidate is promoted only when the user explicitly says so, and the action you set depends on `existingIssue`:
+
+- `existingIssue` is null → set `action` to `create`.
+- `existingIssue` is set → set `action` to `comment`. **Never `create` over an existing issue** — that files a duplicate carrying the same `okstra-fingerprint` marker, and from then on `find_existing_issue` matches whichever of the two the list returns first, so every later run reports against an arbitrary one.
+
+Say which you set and why.
+
+Surface `unreachableRuns > 0` — no silent omission.
+
+### error-issue.4 — Submit
+
+Only after an explicit approval:
+
+```bash
+okstra error-issue submit --plan ~/.okstra/error-issue-plan.json
+```
+
+Report `created` / `commented` / `skipped` / `rejected` / `failed`. If `rejected > 0`, print each rejection's `reasons` verbatim — a rejection means the outbound text or the evidence failed the final gate, and it is never something to work around.
+
+If `failed > 0`, print each failure's `error` and **do not re-run `submit` on the same plan file**. A failure is a candidate that crashed or whose `gh` call errored; the candidates before it were already filed, and their `action` in the plan file still says `create`. Re-run `error-issue plan` instead — the fingerprint lookup turns the already-filed ones into `comment`/`skip`, which is the only thing that keeps a retry from filing duplicates.
+
+### error-issue.5 — Next step
+
+End with: "이 이슈를 실제로 고치려면 `/okstra-brief-gen` 에 이슈 URL 을 주고, okstra 레포에서 `okstra-run --task-type error-analysis` 로 진행하세요."

package/runtime/skills/okstra-inspect/facets/run-audit.md

@@ -0,0 +1,34 @@
+# okstra-inspect facet — run-audit
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## run-audit
+
+Trigger phrases: "okstra run-audit", "run audit", "진행 점검", "태스크들 제대로 가고 있나", "silent failures".
+
+Check every run's artifacts against progress invariants. This catches what the error log cannot: a run that never logged a failure but still ended wrong. Read-only.
+
+### run-audit.1 — Run the audit
+
+```bash
+okstra run-audit
+```
+
+### run-audit.2 — Report (Korean)
+
+Group the `violations` array by `invariant` and report one section each:
+
+| invariant | 위반 태스크 수 | 프로젝트 수 |
+|---|---:|---|
+
+Under each, list the affected `taskKey` values with their `detail` and `source`. Always cite `source` — the reader must be able to open the file the verdict came from.
+
+### run-audit.3 — Split the two outcomes
+
+State plainly which violations are this task's own state versus a repeated okstra defect:
+
+- an invariant broken in **one** task → that task's own state; tell the user what to do about that task
+- an invariant broken across **two or more** tasks → an okstra defect; point at `/okstra-inspect error-issue` to file it
+- `approval-not-forgotten` is the exception and never routes to `error-issue` no matter how far it spreads. It means a human has not approved yet, not that okstra did something wrong — `error_issue.NEVER_AN_ISSUE` drops it, so pointing the user at `error-issue` for it promises a filing that will never happen. Report it as a to-do list of tasks awaiting the user's approval instead.
+
+Never file an issue from this facet. Filing is `error-issue`'s job and it has its own approval gate.