okstra 0.196.0 → 0.197.0

package/runtime/validators/validate-implementation-plan-stages.py

@@ -21,6 +21,11 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
         sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.md_table import split_pipe_row  # noqa: E402
+from okstra_ctl.tdd_bypass import (  # noqa: E402
+    REASON_TOKEN as TDD_USER_BYPASS_TOKEN,
+    bypass_file,
+    granted_stages,
+)
 from okstra_ctl.stage_map import (  # noqa: E402
     STAGE_MAP_HEADING,
     StageMapError,
@@ -185,6 +190,15 @@ TDD_EXEMPTION = re.compile(_LABEL_PREFIX + r"TDD exemption\s*:\s*(?:\*\*)?\s*(.+
 # Profile implementation-planning.md:81 limits the exemption to these three
 # categories; any other reason (e.g. "refactor") must not waive RED/GREEN.
 TDD_EXEMPTION_ALLOWED = ("doc-only", "config-only", "pure-rename")
+# The fourth reason is not a category the plan may assert on its own: it holds
+# only while `<task-root>/qa/tdd-bypass.json` records the user's grant for that
+# stage. Every caller therefore passes the granted stage numbers in, and a plan
+# naming the token with no grant fails S10e like any arbitrary reason. Without
+# it a stage that is genuinely none of the three has no passable value and the
+# plan misdescribes itself to get through (2026-09-10, fontsninja-v3-site
+# dev-10628-3: product work already committed and conformance-proved in a prior
+# run of the same stage, filed as `config-only`).
+TDD_EXEMPTION_USER_BYPASS = TDD_USER_BYPASS_TOKEN
 TEST_CASE_CATEGORIES = ("success", "boundary", "failure")
 TEST_CASE = {
     cat: re.compile(
@@ -196,18 +210,48 @@ CONFORMANCE_TESTS = re.compile(_LABEL_PREFIX + r"Conformance tests\s*:\s*(?:\*\*
 CONFORMANCE_EXEMPTION = re.compile(_LABEL_PREFIX + r"Conformance exemption\s*:\s*(?:\*\*)?\s*\S", re.M)
 
 
-def _exemption_reason_allowed(section: str) -> bool:
-    """True when a `TDD exemption:` line is present AND its reason names an
-    allowed category (doc-only / config-only / pure-rename, case-insensitive).
-    A present-but-unlisted reason returns False so S10e can reject it."""
+def _exemption_reason_message(stage_number: int) -> str:
+    """S10e 의 거절 문구. 통과할 수 있는 값을 전부 이름으로 말한다.
+
+    사유 목록만 나열하면 세 카테고리 중 어느 것도 사실이 아닌 stage 는
+    거짓 신고 외에 길이 없다. 네 번째 값과 그 값을 얻는 명령을 함께 적어
+    다음 행동이 문구 안에 있게 한다.
+    """
+    return (
+        "S10e: 'tddExemption' reason must be one of "
+        + " / ".join(TDD_EXEMPTION_ALLOWED)
+        + f" — or `{TDD_EXEMPTION_USER_BYPASS}`, which holds only while the "
+        "user has granted it for this stage: re-run prepare with "
+        f'`--tdd-bypass "{stage_number or 1}:<reason>"` so the reason is '
+        "recorded verbatim in <task-root>/qa/tdd-bypass.json. An empty or "
+        "arbitrary reason cannot waive RED/GREEN and the three test cases"
+    )
+
+
+def _exemption_reason_allowed(
+    section: str, *, stage_number: int = 0, user_bypassed: frozenset[int] = frozenset(),
+) -> bool:
+    """True when a `TDD exemption:` line is present AND its reason is allowed.
+
+    Allowed means one of the three categories (doc-only / config-only /
+    pure-rename, case-insensitive), or `user-bypass` for a stage the user
+    granted — that grant lives outside the plan, so it is passed in.
+    A present-but-unlisted reason returns False so S10e can reject it.
+    """
     m = TDD_EXEMPTION.search(section)
     if not m:
         return False
     reason = m.group(1).lower()
+    if TDD_EXEMPTION_USER_BYPASS in reason:
+        return stage_number in user_bypassed
     return any(cat in reason for cat in TDD_EXEMPTION_ALLOWED)
 
 
-def _check_slice_tdd(text: str, stages: List[StageMapStage]) -> List[ValidationError]:
+def _check_slice_tdd(
+    text: str,
+    stages: List[StageMapStage],
+    user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """S10: each stage declares a vertical slice and follows RED→GREEN ordering.
 
     S10a — `Slice value:` line with a non-empty value.
@@ -237,11 +281,11 @@ def _check_slice_tdd(text: str, stages: List[StageMapStage]) -> List[ValidationE
                 "S10b: 'Acceptance:' line missing or empty"))
 
         if TDD_EXEMPTION.search(section):
-            if not _exemption_reason_allowed(section):
+            if not _exemption_reason_allowed(
+                section, stage_number=s.stage_number, user_bypassed=user_bypassed,
+            ):
                 errs.append(ValidationError("S10", s.stage_number,
-                    "S10e: 'TDD exemption:' reason must be one of "
-                    "doc-only / config-only / pure-rename — an arbitrary reason "
-                    "cannot waive RED/GREEN"))
+                    _exemption_reason_message(s.stage_number)))
             continue
 
         missing_cases = [
@@ -419,7 +463,9 @@ def _check_parallel_safety(
     })
 
 
-def collect_validation_errors(text: str) -> List[ValidationError]:
+def collect_validation_errors(
+    text: str, user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """All S1–S11 checks against the report text; empty list means valid.
 
     S1 (missing `## 5.5 Stage Map` heading) makes the rest unparseable, so it
@@ -437,7 +483,7 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
         return [ValidationError("S2", 0, exc.reason)]
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
-        errors.extend(_check_slice_tdd(text, stages))
+        errors.extend(_check_slice_tdd(text, stages, user_bypassed))
         errors.extend(_check_markdown_step_commands(text, stages))
         errors.extend(_check_conformance_declaration(text, stages))
         errors.extend(_check_depends_on(stages))
@@ -465,7 +511,9 @@ def _data_stage_metas(
     return rows, _stage_numbers_monotonic(rows)
 
 
-def _check_data_slice_tdd(stage: dict) -> List[ValidationError]:
+def _check_data_slice_tdd(
+    stage: dict, user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """S10c / S10e over one schema-v2 `stages[]` entry.
 
     The schema already requires `sliceValue`, `acceptance`, and — through its
@@ -479,12 +527,12 @@ def _check_data_slice_tdd(stage: dict) -> List[ValidationError]:
     number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
     if "tddExemption" in stage:
         reason = str(stage.get("tddExemption") or "").lower()
+        if TDD_EXEMPTION_USER_BYPASS in reason:
+            if number in user_bypassed:
+                return []
+            return [ValidationError("S10", number, _exemption_reason_message(number))]
         if not any(cat in reason for cat in TDD_EXEMPTION_ALLOWED):
-            return [ValidationError("S10", number,
-                "S10e: 'tddExemption' reason must be one of "
-                + " / ".join(TDD_EXEMPTION_ALLOWED)
-                + " — an empty or arbitrary reason cannot waive RED/GREEN "
-                "and the three test cases")]
+            return [ValidationError("S10", number, _exemption_reason_message(number))]
         return []
 
     steps = [s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)]
@@ -625,7 +673,9 @@ def _check_data_stage_identities(
     return errs
 
 
-def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
+def collect_data_validation_errors(
+    planning: dict, user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """The S-checks that schema v2 cannot express, over `implementationPlanning`.
 
     `collect_validation_errors` scans rendered v1 Markdown, which a v2 report
@@ -663,7 +713,7 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
         if not meta.depends_on
     }))
     for stage in stages:
-        errors.extend(_check_data_slice_tdd(stage))
+        errors.extend(_check_data_slice_tdd(stage, user_bypassed))
         number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
         for step in stage.get("stepwiseExecution") or []:
             if isinstance(step, dict):
@@ -671,26 +721,62 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     return errors
 
 
-def collect_plan_errors(plan_path: Path) -> List[ValidationError]:
+def collect_plan_errors(
+    plan_path: Path, user_bypassed: frozenset[int] | None = None,
+) -> List[ValidationError]:
     """The S-checks for one approved plan, whichever schema wrote it.
 
     A schema-v2 report keeps its stage map in the `.data.json` sidecar and
     renders no `## 5.5 Stage Map` section, so scanning its markdown reports the
     section as missing and blocks every run that approved such a plan.
     """
+    granted = (
+        user_bypassed if user_bypassed is not None
+        else user_bypassed_stages_for_plan(plan_path)
+    )
     planning = schema_v2_report(plan_path).get("implementationPlanning")
     if isinstance(planning, dict) and planning:
-        return collect_data_validation_errors(planning)
-    return collect_validation_errors(plan_path.read_text(encoding="utf-8"))
+        return collect_data_validation_errors(planning, granted)
+    return collect_validation_errors(plan_path.read_text(encoding="utf-8"), granted)
+
+
+def user_bypassed_stages_for_plan(plan_path: Path) -> frozenset[int]:
+    """이 계획이 속한 task 의 우회 원장에서 부여된 stage 번호들.
+
+    레이아웃 해석은 `RunRef.from_run_dir` 이 소유한다 — 부모를 세는 계산은
+    배치가 하나만 바뀌어도 조용히 다른 디렉터리를 가리킨다. run 디렉터리로
+    해석되지 않는 입력은 빈 집합이고, 그때는 `--tdd-bypass-ledger` 로 원장을
+    직접 넘기는 것이 경로다. 원장이 없으면 빈 집합 — 우회 없음이다.
+    """
+    from okstra_ctl.paths import RunRef
+
+    try:
+        task_root = RunRef.from_run_dir(plan_path.resolve().parent.parent).task_root
+    except (ValueError, IndexError):
+        return frozenset()
+    return frozenset(granted_stages(bypass_file(task_root)))
 
 
 def main(argv: List[str]) -> int:
     p = argparse.ArgumentParser()
     p.add_argument("--plan", required=True)
+    p.add_argument(
+        "--tdd-bypass-ledger",
+        default="",
+        dest="tdd_bypass_ledger",
+        help=(
+            "path to <task-root>/qa/tdd-bypass.json; defaults to the ledger of "
+            "the task the --plan report lives in"
+        ),
+    )
     args = p.parse_args(argv)
 
+    granted = (
+        frozenset(granted_stages(Path(args.tdd_bypass_ledger)))
+        if args.tdd_bypass_ledger else None
+    )
     try:
-        errors = collect_plan_errors(Path(args.plan))
+        errors = collect_plan_errors(Path(args.plan), granted)
     except StageMapError as exc:
         print(f"S0 stage=0: {exc.reason}", file=sys.stderr)
         return 1

package/runtime/validators/validate-run.py

@@ -41,6 +41,7 @@ from okstra_project.dirs import tasks_root as _okstra_tasks_root  # noqa: E402
 from okstra_project.resolver import resolve_architecture  # noqa: E402
 
 from okstra_ctl.conformance import (  # noqa: E402
+    conformance_result_file,
     detect_surfaces,
     exempt_stage_surface_conflicts,
     evaluate_conformance,
@@ -56,6 +57,10 @@ from okstra_ctl.dispatch_state import (  # noqa: E402
     v2_worker_state_key,
 )
 from okstra_ctl.paths import RunRef, okstra_home, project_rel  # noqa: E402
+from okstra_ctl.tdd_bypass import (  # noqa: E402
+    bypass_file as tdd_bypass_file,
+    granted_stages,
+)
 from okstra_ctl.reconcile import settle_run_row  # noqa: E402
 from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION  # noqa: E402
 from okstra_ctl.release_gate import (  # noqa: E402
@@ -1700,7 +1705,7 @@ def _load_conformance_results(qa_dir: Path, manifest: dict) -> dict:
         key = entry.get("stageKey") if isinstance(entry, dict) else None
         if not isinstance(key, str) or not key:
             continue
-        sidecar = qa_dir / f"result-{key}.json"
+        sidecar = conformance_result_file(qa_dir, key)
         if not sidecar.is_file():
             continue
         try:
@@ -6352,9 +6357,14 @@ def _plan_verify_dispatched_results(
             # critic 동수 라운드는 `kind: "critic"` 으로 나간다 — 결과 파일명은
             # 같은 `-plan-verify-r<N>-` 꼴이다. reverify 계열만 세면 동수가 있던
             # run 마다 critic 표가 "디스패치 기록 없음" 으로 오탐된다(2026-09-09,
-            # fontsninja-v3-site dev-10627 planning 002).
+            # fontsninja-v3-site dev-10627 planning 002). 계획 본문 라운드 자신의
+            # kind 인 `plan-verify-r<N>` 도 같은 이유로 센다.
             kind = str(row.get("kind") or "")
-            if not (kind.startswith("reverify-r") or kind == "critic"):
+            if not (
+                kind.startswith("reverify-r")
+                or kind.startswith("plan-verify-r")
+                or kind == "critic"
+            ):
                 continue
             name = Path(str(row.get("workerResultPath") or "")).name
             if "-plan-verify-r" not in name:
@@ -8003,13 +8013,19 @@ def _load_stage_validator():
     return mod
 
 
-def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) -> None:
+def _append_stage_data_failures(
+    data: Mapping[str, Any], failures: list[str], task_root: Path | None = None,
+) -> None:
     """Run the stage relationship checks that schema v2 cannot express.
 
     The depends-on DAG, parallel-stage file safety, RED→GREEN ordering, and
     the TDD-exemption vocabulary are relationships between stages, which a
     JSON Schema cannot state. They are enforced here, against the data.json,
     by the same validator that owns the rule vocabulary.
+
+    `tddExemption: user-bypass` is the one reason the plan cannot assert by
+    itself, so the user's grants are read from the task's own bypass ledger
+    and passed in; without the task root no stage counts as granted.
     """
     if (data or {}).get("schemaVersion") != CURRENT_REPORT_SCHEMA_VERSION:
         return  # Schema validation already rejected an unknown version.
@@ -8020,7 +8036,11 @@ def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) ->
     if mod is None:  # pragma: no cover — repo/runtime always ship the file
         failures.append(f"cannot load Stage Map validator at {_STAGE_VALIDATOR_PATH}")
         return
-    for e in mod.collect_data_validation_errors(dict(planning)):
+    granted = (
+        frozenset(granted_stages(tdd_bypass_file(task_root)))
+        if task_root is not None else frozenset()
+    )
+    for e in mod.collect_data_validation_errors(dict(planning), granted):
         failures.append(
             f"implementation-planning stage contract invalid "
             f"[{e.code} stage={e.stage}]: {e.message}"
@@ -9485,7 +9505,11 @@ def main() -> int:
                 )
                 _validate_stage_has_requirement(validation_data, failures)
             if task_type == "implementation-planning":
-                _append_stage_data_failures(validation_data, failures)
+                _append_stage_data_failures(
+                    validation_data,
+                    failures,
+                    _task_root_from_run_dir(report_path.parent.parent),
+                )
         if task_type == "improvement-discovery":
             run_dir = report_path.parent.parent
             _validate_improvement_discovery(report_path, run_dir, brief_path, failures)