okstra 0.107.1 → 0.107.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.107.1",
+  "version": "0.107.2",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.107.1",
-  "builtAt": "2026-07-01T07:21:31.825Z",
+  "package": "0.107.2",
+  "builtAt": "2026-07-01T09:21:00.281Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-team-reconcile.sh

@@ -12,8 +12,16 @@
 # are left for graceful shutdown). It no-ops when tmux is unavailable or nothing
 # is stale.
 #
-# Usage: okstra-team-reconcile.sh [--list] <team-name>
-#   --list   report what WOULD be deactivated; do not write (alias --dry-run).
+# Usage:
+#   okstra-team-reconcile.sh [--list] <team-name|team-dir|config.json>
+#   okstra-team-reconcile.sh [--list] --project-root <dir> [--fallback-team <label>]
+#   okstra-team-reconcile.sh [--list] --session-end   # reads SessionEnd JSON on stdin
+#
+#   --project-root  resolve the CURRENT live session's roster (robust to the
+#                   phase-3 lead.sessionId snapshot drifting across resume), then
+#                   reconcile and print `dismissible-member: <name>` lines.
+#   --session-end   SessionEnd-hook net: reconcile the ending session's roster.
+#   --list          report what WOULD be deactivated; do not write (alias --dry-run).
 #
 # Failures are non-fatal to the run — teardown must never block on this.
 set -u

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -218,7 +218,7 @@ These phases are governed by [team-contract](./team-contract.md). It is the cano
 Claude Code **v2.1.178 removed the `TeamCreate` / `TeamDelete` tools and the `Agent(...)` `team_name` parameter**. With `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (seeded by `okstra install` into the user's `settings.json`), every session already owns **one implicit team** from the moment it starts — there is no creation step to perform and no `team_name` to pass on dispatch. Workers spawned with `Agent(name: ...)` auto-join that implicit team. Do NOT search for, probe, or call `TeamCreate`: its absence is the expected state on every current Claude Code, NOT an "Agent Teams unavailable" signal, and is never a reason to degrade the run. There is no `select:TeamCreate` probe and no doubly-empty-select branch anymore — those keyed off a tool that no longer exists.
 
 1. Record team-state before any dispatch:
-   - `teamName` — the verbatim name from the launch prompt's gate block (`okstra-<task-key>`; implementation stage runs append `-s<N>`, single-stage final-verification appends `-fv-s<N>`). Audit/display label only — the implicit team's on-disk directory is `session-<leadSessionId-prefix>`, which run-end teardown and reconcile resolve from `lead.sessionId`, NEVER from `teamName`.
+   - `teamName` — the verbatim name from the launch prompt's gate block (`okstra-<task-key>`; implementation stage runs append `-s<N>`, single-stage final-verification appends `-fv-s<N>`). Audit/display label only — the implicit team's on-disk directory is `session-<leadSessionId-prefix>`, but run-end teardown resolves it from the CURRENT live session (see `_common-contract.md` "Run-end teammate teardown"), NOT from the phase-3 `lead.sessionId` snapshot recorded here, which drifts across resume / compaction; it is never resolved from `teamName`.
    - `teamCreate: { attempted: false, status: "implicit" }` — the audit marker that this run rides the session's implicit team (no explicit creation tool exists). A concurrent-run launch prompt instead pre-records `status: "skipped", reason: "concurrent-run"`; honor whichever the gate specifies.
 2. Verify `team-state.lead.sessionId` is populated. The `okstra.sh` exec path fills it automatically (`generate_claude_session_id` → `claude --session-id ...`). The render-only / in-session takeover path (`okstra-run` skill) auto-detects via `resolve_inproc_lead_session_id`, which is best-effort and may return empty if `~/.claude/projects/<encoded-cwd>/` is unreadable or has no jsonl yet. If `lead.sessionId` is empty at this point, write the running session's id into team-state before proceeding — Phase 7 token-usage collection depends on it and will fail with `lead jsonl not found (sessionId=)` otherwise.
 3. Decide split-pane capability, record it, then emit the phase-3 checkpoint and proceed to Phase 4. Split-pane teammates require a tmux session — this is a host capability, NOT an okstra success/failure gate, and is the only thing the removed "TeamCreate" probe should ever have been deciding:

package/runtime/prompts/lead/report-writer.md

@@ -277,7 +277,9 @@ Section numbering follows `templates/reports/final-report.template.md` exactly
 - `approach` — 그래서 어떤 작업이 필요한가 (택한 방향).
 - `justification` — 왜 이게 합리적 선택인가 (대안 대비, 근거).
 
-Every field MUST anchor its claim with at least one evidence reference — a `path:line`, a report ID (`C-001` / `F-013` / `§5.4`), or another cited source already present in this report. When the evidence is genuinely insufficient, say so explicitly (`근거 불충분 — <이유>`) instead of inventing one. `validators/validate-run.py` → `_validate_rationale_evidence` fails any field carrying neither a citation nor an insufficiency marker, so an ungrounded or fabricated rationale is rejected at validation time. Do NOT restate the Verdict Card or the §5.4 trade-off matrix verbatim — this section is the *why*, in connected prose, that those tables compress.
+Every field MUST anchor its claim with at least one evidence reference — a `path:line`, an **in-report** ID (`C-001` / `E-006` / `§5.4`), or another cited source already present in this report. When the evidence is genuinely insufficient, say so explicitly (`근거 불충분 — <이유>`) instead of inventing one. `validators/validate-run.py` → `_validate_rationale_evidence` fails any field carrying neither a citation nor an insufficiency marker, so an ungrounded or fabricated rationale is rejected at validation time.
+
+**Reader-facing prose MUST NOT cite a bare brief/worker-internal ID that this report never surfaces** — `RC-*` (reporter confirmations, defined in the brief), `RF-*` / `F-*` (findings, defined in worker-results) have no anchor in the final report, so a reader hits an opaque token with nothing to click. Either expand it inline (`the confirmed version target 1.27.47→1.27.48`) or, for an audit trail, namespace it (`claude:F-005`). **Enforced:** `_validate_no_opaque_id_references` fails a bare `RC-*` / `RF-*` / non-namespaced `F-*` appearing in `verdictCard` / `finalVerdict` / `rationale` / `clarificationItems[].statement`. (The renderer anchors + links in-report IDs of any digit width, so a surfaced `RC-4`-style id does resolve.) Do NOT restate the Verdict Card or the §5.4 trade-off matrix verbatim — this section is the *why*, in connected prose, that those tables compress.
 
 0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub.
 1. **Cross Verification Results** — 4 categories (Full / Partial / Contested / Worker-Unique) when convergence is enabled, per `convergence`. Prepend the Round History sub-table (columns: `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches | skippedWorkers`) plus a `round2SkippedReason: <value>` note, pulled verbatim from `convergence-<task-type>-<seq>.json`. Empty contested list renders as `- 합의 미달 항목 없음.`. Convergence-disabled runs use the legacy Consensus/Differences format and omit the round table.

package/runtime/prompts/profiles/_common-contract.md

@@ -55,15 +55,16 @@ profile document.
   - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). Whether there is anything to ask about is decided by the `--list` output, NOT by the lead's reading of `lead-pane.id`: an empty list → skip the question (above); the lead MUST NOT fabricate a synthetic pane list.
 - Run-end teammate teardown (shared — MUST run AFTER the pane disposition question and BEFORE `PROGRESS: complete`):
   - CC v2.1.178 removed `TeamCreate` / `TeamDelete`: this run rode the session's **implicit team** (Phase 3 recorded `teamCreate.status: "implicit"` plus the `teamName` audit label). There is no tool to delete a team — the implicit team ends when the session ends. What teardown CAN do is gracefully dismiss the worker teammates the lead spawned, so they stop showing as live members in the FleetView roster.
-  - **Whether to run this step is decided by on-disk fact.** The harness names the team directory `session-<leadSessionId-prefix>` (the `teamName` label never becomes a directory name). Resolve existence from disk: find the `~/.claude/teams/session-*/config.json` whose `leadSessionId` equals team-state `lead.sessionId`.
-    - **Matching on-disk config found, with members beyond the lead** → teammates exist; run the dismissal sequence below.
-    - **No matching on-disk config, or split-pane was off** → nothing to dismiss → silent-skip.
+  - **Whether to run this step is decided by on-disk fact, resolved at teardown time by the CURRENT live session — NOT from `team-state.lead.sessionId`.** The harness names the team directory `session-<leadSessionId-prefix>` (the `teamName` label never becomes a directory name), but `team-state.lead.sessionId` is only a phase-3 snapshot: Claude Code re-issues the session id across resume / compaction mid-run, so the live roster usually sits under a DIFFERENT `session-*` dir than the snapshot names. Resolving from the snapshot is what made split-pane teardown silently miss its own live teammates. The resolver in step 1 below keys off the live session (falling back to the snapshot dir only when the live one is absent) and prints the members to dismiss.
+    - **Resolver printed one or more `dismissible-member: <name>` lines** → teammates exist; run the dismissal sequence below.
+    - **Resolver printed `no live roster for this session`, or split-pane was off** → nothing to dismiss → silent-skip.
   - The pane disposition prompt above is the only user prompt for this cleanup decision. Do NOT ask a second teammate-only question.
   - On `아니오` / `n` / `keep` → dismiss nothing. Tell the user the teammates remain visible in FleetView/Teams until the session ends, and can be removed earlier from the Teams UI.
   - On `예` / `y` / `close` → emit `PROGRESS: phase-7-teardown dismissing teammates`, then run the sequence below. Token-usage collection MUST already be complete — it reads `~/.claude/projects/` jsonls, which dismissal never touches, but the read MUST precede teardown.
-    1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh "<resolved-config-path>"` — the on-disk `~/.claude/teams/session-<…>/config.json` resolved in the existence check above — exactly once. It flips dead-pane stale-active members to inactive, and no-ops when tmux is unavailable or nothing is stale. Do NOT loop it.
-    2. Send each confirmed-complete member a structured `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field. NEVER target the lead's own session, and never use `TaskStop` (teammates are not background tasks — `TaskStop` 404s on a member address).
+    1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"` exactly once. It resolves the live session's `~/.claude/teams/session-<live>/config.json` (falling back to the snapshot `session-<lead.sessionId-prefix>` dir only if the live one is absent), flips dead-pane stale-active members to inactive (no-op when tmux is unavailable or nothing is stale), and prints one `dismissible-member: <name>` line per non-lead member. Do NOT loop it, and do NOT hand-resolve a config path from `team-state.lead.sessionId`.
+    2. Send each printed `dismissible-member: <name>` **whose completion is confirmed** (its Result Path exists) a structured `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field. NEVER target the lead's own session, and never use `TaskStop` (teammates are not background tasks — `TaskStop` 404s on a member address).
   - Claude Code exposes no tool to delete the team or surgically remove a roster entry, so a dismissed teammate may still show as an idle pill until the session ends. Do not pretend the team was deleted. If the user wants the roster gone entirely, surface the manual action: `Teams/FleetView 에서 team <teamName> 삭제`, and if tmux panes were kept earlier also show `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`.
+  - **Enforcement / safety net.** This teardown fires after the Phase 7 validator's window, so `validate_session_conformance.py` cannot check it (it is not a required checkpoint). The net is the `SessionEnd` hook `$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end` (seeded into `settings.template.json`): when the Claude session ends it reconciles that session's roster regardless of whether this step ran, so a dead-pane member never lingers as a live pill past session end.
   - Report the outcome in one short line (e.g. `worker teammate 정리 완료`, or `stale 멤버 1명 reconcile 후 정리`) and proceed to the final `PROGRESS: complete ...` line.
 - Brief handoff contract (shared — applies whenever the run consumes a task brief produced by `okstra-brief`):
   - the brief is a **pre-discovery artifact**: it converts a domain-reporter's words (non-expert *or* developer) into expert-consumable form so this and later phases can run with zero fill-in questions to the operator. The brief is **not** authoritative on solution decisions; it is authoritative on the reporter's intent.

package/runtime/python/okstra_ctl/render_final_report.py

@@ -136,10 +136,12 @@ def _yaml_inline_list(values: list[str]) -> str:
 # reference must not silently jump to the wrong row.
 _HEADING_RE = re.compile(r"^(#{1,6})[ \t]+(.*?)[ \t]*$")
 _FENCE_RE = re.compile(r"^[ \t]*(?:```|~~~)")
-_FIRST_CELL_ID_RE = re.compile(r"^[ \t]*\*{0,2}([A-Z]{1,4}-\d{3,})\b")
+_FIRST_CELL_ID_RE = re.compile(r"^[ \t]*\*{0,2}([A-Z]{1,4}-\d{1,})\b")
 # A reference token: an ID not glued to a word char / `-` on either side and
 # not prefixed by `:` (which would make it a `<worker>:<item-id>` source ref).
-_REF_ID_RE = re.compile(r"(?<![:\w-])[A-Z]{1,4}-\d{3,}(?![\w-])")
+# `\d{1,}` (not `{3,}`): short IDs like `RC-4` are valid — the old 3-digit floor
+# silently dropped them, so they could never anchor or link.
+_REF_ID_RE = re.compile(r"(?<![:\w-])[A-Z]{1,4}-\d{1,}(?![\w-])")
 
 
 def _slugify(text: str) -> str:

package/runtime/python/okstra_ctl/team_reconcile.py

@@ -16,6 +16,13 @@ CC v2.1.178 removed ``TeamDelete``: the implicit team ends with the session and
 run-end teardown only dismisses teammates via ``shutdown_request``. Reconcile
 keeps the roster honest so a dismissed-but-dead member does not linger as a
 live pill — see _common-contract.md "Run-end teammate teardown".
+
+Roster resolution (``--project-root``) exists because ``team-state.lead.sessionId``
+is a phase-3 snapshot: Claude Code re-issues the session id across resume /
+compaction mid-run, so the live on-disk roster often sits under a DIFFERENT
+``session-*`` dir than the snapshot names. Resolving by the CURRENT live session
+(the newest jsonl under the encoded-cwd projects dir) is what makes split-pane
+teardown find the teammates it must dismiss.
 """
 from __future__ import annotations
 
@@ -26,6 +33,8 @@ import sys
 import tempfile
 from pathlib import Path
 
+from okstra_ctl.session import resolve_inproc_lead_session_id
+
 
 def live_pane_ids() -> tuple[bool, set[str]]:
     """Return ``(tmux_available, live_pane_ids)``.
@@ -66,6 +75,44 @@ def reconcile_members(config: dict, live_panes: set[str]) -> list[str]:
     return flipped
 
 
+def dismissible_members(config: dict) -> list[str]:
+    """Names of every non-lead member — the set the lead may ``shutdown_request``.
+
+    The lead further filters by confirmed-complete (result path present) before
+    dismissing; this just tells it which teammates the resolved roster holds.
+    """
+    lead = config.get("leadAgentId")
+    names: list[str] = []
+    for member in config.get("members", []):
+        if member.get("agentId") == lead:
+            continue
+        names.append(member.get("name", member.get("agentId", "?")))
+    return names
+
+
+def _team_config_for_session(session_id: str) -> Path:
+    """``~/.claude/teams/session-<prefix>/config.json`` for a session id.
+
+    The harness names the team dir with the session id's first segment (the
+    8-hex stem before the first dash), never the ``teamName`` label.
+    """
+    prefix = session_id.split("-", 1)[0]
+    return Path.home() / ".claude" / "teams" / f"session-{prefix}" / "config.json"
+
+
+def _live_team_config(project_root: Path) -> Path | None:
+    """Resolve the CURRENT live session's team config, or None when absent.
+
+    Robust to the mid-run session-id drift that strands the phase-3
+    ``lead.sessionId`` snapshot: keys off the live session, not the snapshot.
+    """
+    sid = resolve_inproc_lead_session_id(project_root)
+    if not sid:
+        return None
+    cand = _team_config_for_session(sid)
+    return cand if cand.is_file() else None
+
+
 def _config_path(team_arg: str) -> Path:
     """Resolve a team name, a team dir, or a config.json path to the config file."""
     p = Path(team_arg)
@@ -92,43 +139,126 @@ def _atomic_write(path: Path, text: str) -> None:
         raise
 
 
-def main(argv: list[str]) -> int:
-    dry_run = False
-    rest: list[str] = []
-    for arg in argv:
-        if arg in ("--list", "--dry-run"):
-            dry_run = True
-        else:
-            rest.append(arg)
-    if len(rest) != 1:
-        print("usage: okstra-team-reconcile.sh [--list] <team-name|team-dir|config.json>",
-              file=sys.stderr)
-        return 2
-
-    cfg_path = _config_path(rest[0])
-    if not cfg_path.is_file():
-        print(f"team-reconcile: no team config at {cfg_path}", file=sys.stderr)
-        return 1
+def _reconcile_config(cfg_path: Path, dry_run: bool, print_members: bool) -> int:
+    """Read, reconcile, and (unless dry-run) write back one config.json.
 
+    When ``print_members`` is set, also emit one ``dismissible-member: <name>``
+    line per non-lead member so the lead knows whom to ``shutdown_request``.
+    """
     try:
         config = json.loads(cfg_path.read_text())
     except (OSError, json.JSONDecodeError) as exc:
         print(f"team-reconcile: cannot read team config at {cfg_path}: {exc}",
               file=sys.stderr)
         return 1
+
     available, live = live_pane_ids()
     if not available:
         print("team-reconcile: tmux unavailable — skipped (no flip)")
+    else:
+        flipped = reconcile_members(config, live)
+        if flipped and dry_run:
+            print("team-reconcile (dry-run): would deactivate " + ", ".join(flipped))
+        elif flipped:
+            _atomic_write(cfg_path, json.dumps(config, indent=2, ensure_ascii=False) + "\n")
+            print(f"team-reconcile: deactivated {len(flipped)} stale member(s): "
+                  + ", ".join(flipped))
+        else:
+            print("team-reconcile: no stale-active members")
+
+    if print_members:
+        for name in dismissible_members(config):
+            print(f"dismissible-member: {name}")
+    return 0
+
+
+def _session_id_from_stdin() -> str:
+    """Extract ``session_id`` from a SessionEnd hook's JSON payload on stdin.
+
+    Returns "" when stdin is a terminal (manual invocation), empty, or not the
+    expected JSON — the caller then no-ops. The hook must never block or fail a
+    session teardown.
+    """
+    if sys.stdin.isatty():
+        return ""
+    try:
+        raw = sys.stdin.read()
+    except OSError:
+        return ""
+    if not raw.strip():
+        return ""
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return ""
+    sid = data.get("session_id") or data.get("sessionId") or ""
+    return sid if isinstance(sid, str) else ""
+
+
+def _run_resolve_and_reconcile(project_root: str, fallback_team: str, dry_run: bool) -> int:
+    """``--project-root`` mode: resolve the live roster, reconcile, list members."""
+    cfg = _live_team_config(Path(project_root))
+    if cfg is None and fallback_team:
+        fb = _config_path(fallback_team)
+        cfg = fb if fb.is_file() else None
+    if cfg is None:
+        print("team-reconcile: no live roster for this session — nothing to dismiss")
         return 0
+    print(f"team-reconcile: roster resolved at {cfg}")
+    return _reconcile_config(cfg, dry_run, print_members=True)
+
 
-    flipped = reconcile_members(config, live)
-    if not flipped:
-        print("team-reconcile: no stale-active members")
+def _run_session_end(dry_run: bool) -> int:
+    """``--session-end`` mode: reconcile the ending session's roster from the
+    SessionEnd hook payload. Safety net so a lead that skipped run-end teardown
+    still leaves no dead-pane member lingering as a live pill."""
+    sid = _session_id_from_stdin()
+    if not sid:
         return 0
-    if dry_run:
-        print("team-reconcile (dry-run): would deactivate " + ", ".join(flipped))
+    cfg = _team_config_for_session(sid)
+    if not cfg.is_file():
         return 0
+    return _reconcile_config(cfg, dry_run, print_members=False)
 
-    _atomic_write(cfg_path, json.dumps(config, indent=2, ensure_ascii=False) + "\n")
-    print(f"team-reconcile: deactivated {len(flipped)} stale member(s): " + ", ".join(flipped))
-    return 0
+
+def _parse_argv(argv: list[str]) -> tuple[bool, str, str, bool, list[str]]:
+    dry_run = False
+    project_root = ""
+    fallback_team = ""
+    session_end = False
+    rest: list[str] = []
+    it = iter(argv)
+    for arg in it:
+        if arg in ("--list", "--dry-run"):
+            dry_run = True
+        elif arg == "--project-root":
+            project_root = next(it, "")
+        elif arg == "--fallback-team":
+            fallback_team = next(it, "")
+        elif arg == "--session-end":
+            session_end = True
+        else:
+            rest.append(arg)
+    return dry_run, project_root, fallback_team, session_end, rest
+
+
+def main(argv: list[str]) -> int:
+    dry_run, project_root, fallback_team, session_end, rest = _parse_argv(argv)
+
+    if session_end:
+        return _run_session_end(dry_run)
+    if project_root:
+        return _run_resolve_and_reconcile(project_root, fallback_team, dry_run)
+
+    if len(rest) != 1:
+        print("usage: okstra-team-reconcile.sh [--list] "
+              "(<team-name|team-dir|config.json> | --project-root <dir> "
+              "[--fallback-team <label>] | --session-end)",
+              file=sys.stderr)
+        return 2
+
+    cfg_path = _config_path(rest[0])
+    if not cfg_path.is_file():
+        print(f"team-reconcile: no team config at {cfg_path}", file=sys.stderr)
+        return 1
+    return _reconcile_config(cfg_path, dry_run, print_members=False)

package/runtime/templates/reports/settings.template.json

@@ -47,6 +47,10 @@
           {
             "type": "command",
             "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh --reap"
+          },
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end"
           }
         ]
       }

package/runtime/validators/validate-run.py

@@ -1527,6 +1527,7 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
         failures.append(f"final-report data.json: {err}")
 
     _validate_rationale_evidence(data, failures)
+    _validate_no_opaque_id_references(data, failures)
 
     task_type = (data.get("header") or {}).get("taskType")
     if task_type == "final-verification":
@@ -1541,8 +1542,10 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
         _validate_requirement_coverage_covered_by(data, failures)
 
 
-# path:line (foo.service.ts:268), report ID (C-001 / F-013 / G-crit-002 / RC-1),
-# or a section reference (§5.4) — any one satisfies "this claim is anchored".
+# path:line (foo.service.ts:268), an in-report ID (C-001 / E-006 / P-004), a
+# namespaced audit ref (claude:F-005), or a §section reference (§5.4) — any one
+# satisfies "this claim is anchored". A bare brief/worker ID (RC-*/RF-*/F-*) is
+# handled separately by `_validate_no_opaque_id_references`.
 _EVIDENCE_TOKEN = re.compile(
     r"[\w./-]+\.\w+:\d+|\b[A-Z]{1,3}(?:-[a-z]+)?-\d+\b|§\s*\d")
 # Explicit "I don't know" escapes — anti-fabrication's other valid answer.
@@ -1573,12 +1576,61 @@ def _validate_rationale_evidence(data: dict, failures: list[str]) -> None:
             continue
         failures.append(
             f"final-report data.json: rationale.{field} cites no evidence "
-            f"(expected a path:line, a report ID like C-001/F-013, or a §"
+            f"(expected a path:line, an in-report ID like C-001, or a §"
             f"section reference) and gives no explicit insufficiency marker "
             f"(e.g. '근거 불충분'). Anchor the claim or state what is unknown."
         )
 
 
+# Brief/worker-internal ID families that are NOT surfaced (anchored) in the
+# final report: `RC-` reporter confirmations live in the brief, `F-`/`RF-`
+# findings live in worker-results. A reader-facing sentence citing a bare one
+# of these has no in-report target to resolve — the reader is stuck. Namespaced
+# audit citations (`claude:F-005`) are exempt via the `:` negative lookbehind.
+_OPAQUE_ID_RE = re.compile(r"(?<![:\w-])(?:RC|RF|F)-\d+(?![\w-])")
+
+
+def _reader_facing_narrative(data: dict) -> list[tuple[str, str]]:
+    """(label, text) for every reader-facing narrative string in the report —
+    the fields a human reads to act, where an unresolvable ID is most harmful."""
+    out: list[tuple[str, str]] = []
+    for section in ("verdictCard", "finalVerdict"):
+        block = data.get(section)
+        if isinstance(block, dict):
+            for field in ("finalConclusion", "nextStep"):
+                value = block.get(field)
+                if isinstance(value, str):
+                    out.append((f"{section}.{field}", value))
+    rationale = data.get("rationale")
+    if isinstance(rationale, dict):
+        for field in _RATIONALE_FIELDS:
+            value = rationale.get(field)
+            if isinstance(value, str):
+                out.append((f"rationale.{field}", value))
+    for row in data.get("clarificationItems") or []:
+        if isinstance(row, dict) and isinstance(row.get("statement"), str):
+            out.append((f"clarificationItems[{row.get('id') or '?'}].statement", row["statement"]))
+    return out
+
+
+def _validate_no_opaque_id_references(data: dict, failures: list[str]) -> None:
+    """Reader-facing prose must not cite a bare brief/worker-internal ID
+    (`RC-*`, `RF-*`, non-namespaced `F-*`) that the report never surfaces — the
+    reader has nothing to click and no definition to find. Expand it inline
+    (`the confirmed version target 1.27.47→1.27.48`) or namespace an audit
+    citation (`claude:F-005`)."""
+    for label, text in _reader_facing_narrative(data):
+        offenders = sorted({m.group(0) for m in _OPAQUE_ID_RE.finditer(text)})
+        if offenders:
+            failures.append(
+                f"final-report data.json: {label} cites brief/worker-internal "
+                f"ID(s) {', '.join(offenders)} that this report never surfaces "
+                "(no anchor to resolve them to). Expand them to plain language "
+                "on the reference, or namespace an audit citation like "
+                "`claude:F-005` — a reader cannot resolve a bare RC-/RF-/F- token."
+            )
+
+
 def _validate_implementation_planning_cross_project(data: dict, failures: list[str]) -> None:
     """타 프로젝트 의존을 DM 행(`kind == 'cross-project'`)으로 선언했다면
     `crossProjectDependencies` 에 `direction == 'upstream-precondition'` 행이