okstra 0.149.0 → 0.151.0

package/runtime/python/okstra_ctl/report_translation.py

@@ -0,0 +1,469 @@
+"""Which final-report strings a translator may rewrite, and how to apply them.
+
+The data.json is authored in English and is the SSOT for every downstream
+consumer. The human HTML is the one artifact that renders in the reader's
+language, so a translation arrives as a sidecar keyed by JSON Pointer and is
+overlaid at render time. Nothing here mutates the SSOT.
+
+Classification is by leaf key name, and the split is not "prose vs. term" —
+the translator is told to leave a term in English when English reads better.
+The line drawn here is **load-bearing vs. displayed**: a value the renderer
+feeds into a CSS class, a label-table lookup, or an anchor id cannot change
+without breaking the page, so it never reaches the translator. Everything a
+reader merely reads is offered, and the translator decides.
+
+When a key name carries load-bearing values in even one place, it counts as
+structural everywhere. Missing a translation leaves English on the page;
+translating an anchor id breaks the link.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Iterator, Mapping, NamedTuple
+
+# Values the renderer reads as text and nothing else.
+PROSE_KEYS = frozenset({
+    "acceptance",
+    "alternativesConsidered",
+    "approach",
+    "approvalDisposition",
+    "approvalEvidence",
+    "behavior",
+    "blastRadius",
+    "blockReason",
+    "blockedReason",
+    "body",
+    "briefEvidence",
+    "carryIn",
+    "causeSummary",
+    "change",
+    "check",
+    "claim",
+    "condition",
+    "confirmingSignal",
+    "conformanceExemption",
+    "consequences",
+    "constraint",
+    "context",
+    "coreReason",
+    "decision",
+    "declinedFixRecommendations",
+    "description",
+    "details",
+    "disagreement",
+    "discrepancy",
+    "disproveWith",
+    "environmentSetup",
+    "escalationTrigger",
+    "evidence",
+    "evidenceRequired",
+    "exemptionReaffirm",
+    "exemptionReason",
+    "exitContract",
+    "exitContractSummary",
+    "expected",
+    "expectedBehaviorAfter",
+    "expectedForm",
+    "expectedOutcome",
+    "expectedResult",
+    "failureHandling",
+    "finalConclusion",
+    "headline",
+    "howToStart",
+    "hypothesis",
+    "item",
+    "justification",
+    "label",
+    "mitigation",
+    "motivation",
+    "name",
+    "need",
+    "nextStep",
+    "noVariationRationale",
+    "notApplicableReason",
+    "note",
+    "observableFailure",
+    "observed",
+    "option",
+    "outcome",
+    "outputSummary",
+    "performed",
+    "planItem",
+    "position",
+    "problem",
+    "question",
+    "rationale",
+    "readyWhen",
+    "reason",
+    "rejectedSummary",
+    "rejectingSignal",
+    "requiredDecision",
+    "requiredWork",
+    "requirement",
+    "resolution",
+    "responsibility",
+    "rolloutCost",
+    "routingRecommendation",
+    "selfFixNote",
+    "stageTitle",
+    "stageValidation",
+    "statement",
+    "suggestedAction",
+    "summary",
+    "supersededStatement",
+    "symptom",
+    "systemInterpretation",
+    "testCaseBoundary",
+    "testCaseFailure",
+    "testCaseSuccess",
+    "testCoverageCost",
+    "text",
+    "title",
+    "topic",
+    "trigger",
+    "triggerSignal",
+    "userChoice",
+    "userInput",
+    "verification",
+    "verificationMethod",
+    "verificationSignal",
+    "workingAssumption",
+})
+
+# Values something other than the reader depends on: a CSS class, a label-table
+# key, an anchor id, a path the reader clicks, a command they paste, or a quote
+# that must stay verbatim to be evidence at all.
+STRUCTURAL_KEYS = frozenset({
+    "action",             # implementation.py: _FILE_ACTIONS lookup key
+    "adapter",
+    "affectedId",
+    "affectedTarget",
+    "area",               # slug-shaped ('scan-coverage')
+    "artifact",
+    "baseBranch",
+    "baseRefSha",
+    "baseSha",
+    "boundary",
+    "branchName",
+    "canonical",
+    "capturedHeadSha",
+    "carriedForwardFromSeq",
+    "carryJson",
+    "clarificationId",
+    "claudeCode",
+    "collectorBranch",
+    "command",
+    "commandOrObservation",
+    "commandOrTest",
+    "commitListQuote",
+    "complexity",
+    "componentId",
+    "confidence",
+    "conformanceTests",
+    "coveredBy",
+    "createdAt",
+    "cycle",
+    "dataStore",
+    "date",
+    "dependsOn",
+    "diffSummaryQuote",
+    "direction",
+    "dispatches",
+    "executorWorktreePath",
+    "existingPrUrl",
+    "externalSystem",
+    "featureId",
+    "field",
+    "file",
+    "files",
+    "followUpPhase",
+    "fromComponentId",
+    "fromTaskKey",
+    "fullSha",
+    "gitDiffStat",
+    "gitStatusShort",
+    "h1c",
+    "h2",
+    "id",
+    "impact",             # 'high' / 'medium' alongside prose
+    "impactKind",
+    "implementationBaseRef",
+    "implementationOption",
+    "independentValidationRerun",
+    "injectedAs",
+    "input",
+    "interfaceKind",
+    "interfaces",
+    "itemId",
+    "kind",               # feature_analysis.py: _FLOW_KINDS lookup key
+    "leadModel",
+    "leadingCauseId",
+    "lens",               # enum_label("lens")
+    "lines",
+    "linkedWork",
+    "match",
+    "model",
+    "newTaskId",
+    "number",
+    "okstraVersion",
+    "output",
+    "outputTail",
+    "owner",
+    "ownerComponentId",
+    "path",
+    "planFile",
+    "planStep",
+    "prepItemId",
+    "project",
+    "projectId",
+    "raw",
+    "rawStat",
+    "readBoundary",
+    "readOnlyCommandLog",
+    "relatedIds",
+    "relation",
+    "replacedInTest",
+    "replacedWith",
+    "reportPath",
+    "requestKind",
+    "requestPath",
+    "requestVerbatim",    # the user's own words, quoted as evidence
+    "requestedValue",
+    "reversibility",
+    "risk",               # tone-{{ row.risk }} class; an enum on ProjectHotspot
+    "role",
+    "rollbackCommand",
+    "runManifest",
+    "runSeq",
+    "scope",              # 'PF-001' alongside prose
+    "sections",
+    "shortSha",
+    "signature",
+    "singleTicket",
+    "skippedWorkers",
+    "sliceValue",
+    "slug",
+    "source",             # enum_label("rejectionSource") and evidence ids
+    "sourceCommit",
+    "sourceFile",
+    "sourceImpactId",
+    "sourceSection",
+    "status",             # CSS class + enum_label("coverage")
+    "styleLintTypecheck",
+    "subject",            # commit subject, must stay verbatim
+    "symbol",
+    "symptomVerbatim",
+    "target",
+    "targetReport",
+    "taskGroup",
+    "taskId",
+    "taskKey",
+    "taskType",
+    "tddEvidence",
+    "tddExemption",
+    "terminal",
+    "toComponentId",
+    "toTaskKey",
+    "url",
+    "verdictTokenQuote",
+    "verifier",
+    "version",
+    "worker",
+    "workerRole",
+    "worktreePath",
+    "writeBoundary",
+})
+
+
+class UnclassifiedKeys(ValueError):
+    """A schema string field belongs to neither set."""
+
+
+# A key name says what a field is *for*; these say what one value actually is.
+# `evidence` is the largest prose bucket in a real report and also holds bare
+# `src/server.ts:33` citations — the key cannot separate them, the value can.
+_MACHINE_CHARS = re.compile(r"^[A-Za-z0-9_.:@/\\#-]+$")
+_LOWER_TOKEN = re.compile(r"^[a-z][a-z0-9]*([-_][a-z0-9]+)*$")
+_FILE_EXTENSION = re.compile(r"\.[A-Za-z0-9]{1,6}$")
+_LINE_NUMBER = re.compile(r":\d+$")
+
+
+def is_translatable_value(text: str) -> bool:
+    """Whether one value is prose rather than a citation or a token.
+
+    Anything with whitespace is prose. A single run of ASCII path characters
+    is not, once it carries a directory separator, a file extension, or a line
+    number — and neither is a bare lowercase token, which is how an enum reads.
+    """
+    value = text.strip()
+    if not value:
+        return False
+    if any(char.isspace() for char in value):
+        return True
+    if not _MACHINE_CHARS.match(value):
+        return True
+    if "/" in value or "\\" in value:
+        return False
+    if _FILE_EXTENSION.search(value) or _LINE_NUMBER.search(value):
+        return False
+    return _LOWER_TOKEN.match(value) is None
+
+
+def escape_token(token: str) -> str:
+    """Escape one JSON Pointer reference token (RFC 6901)."""
+    return token.replace("~", "~0").replace("/", "~1")
+
+
+def unescape_token(token: str) -> str:
+    return token.replace("~1", "/").replace("~0", "~")
+
+
+def _walk(node: Any, pointer: str, key: str) -> Iterator[tuple[str, str]]:
+    if isinstance(node, Mapping):
+        for child_key, value in node.items():
+            yield from _walk(value, f"{pointer}/{escape_token(str(child_key))}", str(child_key))
+    elif isinstance(node, (list, tuple)):
+        for index, value in enumerate(node):
+            # An array element inherits the key that named the array, so
+            # `evidence: [...]` translates each entry.
+            yield from _walk(value, f"{pointer}/{index}", key)
+    elif isinstance(node, str) and key in PROSE_KEYS and is_translatable_value(node):
+        yield pointer, node
+
+
+def extract(data: Mapping[str, Any]) -> dict[str, str]:
+    """Map every translatable pointer to the English text at it.
+
+    The translator fills in this map rather than authoring pointers, so a
+    sidecar cannot cite a path the document does not have.
+    """
+    return dict(_walk(data, "", ""))
+
+
+class OverlayReport(NamedTuple):
+    applied: int
+    # Pointers the extractor offered that the sidecar left untranslated. They
+    # render in English — a partial translation is a readable page, not a
+    # failure — but a silent fallback is how a half-empty sidecar ships
+    # unnoticed, so the count is reported.
+    untranslated: tuple[str, ...]
+    # Pointers the sidecar carries that do not resolve to a string here. A
+    # sidecar written against a different report.
+    unresolved: tuple[str, ...]
+
+
+def _resolve_parent(data: Any, pointer: str) -> tuple[Any, str | int] | None:
+    tokens = [unescape_token(t) for t in pointer.split("/")[1:]]
+    if not tokens:
+        return None
+    node = data
+    for token in tokens[:-1]:
+        if isinstance(node, Mapping) and token in node:
+            node = node[token]
+        elif isinstance(node, list) and token.isdigit() and int(token) < len(node):
+            node = node[int(token)]
+        else:
+            return None
+    last = tokens[-1]
+    if isinstance(node, Mapping) and isinstance(node.get(last), str):
+        return node, last
+    if isinstance(node, list) and last.isdigit() and int(last) < len(node):
+        return (node, int(last)) if isinstance(node[int(last)], str) else None
+    return None
+
+
+def overlay(
+    data: Mapping[str, Any], strings: Mapping[str, str]
+) -> tuple[dict[str, Any], OverlayReport]:
+    """Return a deep copy of ``data`` with the sidecar's strings substituted."""
+    import copy
+
+    out = copy.deepcopy(dict(data))
+    applied = 0
+    unresolved: list[str] = []
+    for pointer, text in strings.items():
+        target = _resolve_parent(out, pointer)
+        if target is None or not isinstance(text, str) or not text:
+            unresolved.append(pointer)
+            continue
+        parent, key = target
+        parent[key] = text
+        applied += 1
+    untranslated = tuple(sorted(set(extract(data)) - set(strings)))
+    return out, OverlayReport(applied, untranslated, tuple(sorted(unresolved)))
+
+
+# Above this share of Hangul, the prose was authored in Korean rather than
+# quoting some. Measured across real reports: Korean-authored ones sit at
+# 35-38%, English ones that quote a Korean brief or a worker's Korean phrase
+# reach 8% at most. The gap is wide enough that no threshold inside it is
+# delicate. Only the strings `extract` offers are counted — a verbatim quote of
+# the user's request is structural and never reaches this.
+HANGUL_PROSE_LIMIT = 0.20
+
+
+def hangul_share(data: Mapping[str, Any]) -> tuple[float, int]:
+    """Return the Hangul share of the report's authored prose, and its length."""
+    text = "".join(extract(data).values())
+    if not text:
+        return 0.0, 0
+    hangul = sum(1 for char in text if "가" <= char <= "힣")
+    return hangul / len(text), len(text)
+
+
+def prose_is_english(data: Mapping[str, Any]) -> bool:
+    """Whether the data.json was authored in English, as the SSOT contract requires.
+
+    The report language names what the human HTML renders in, not what the
+    worker writes. A worker that authors Korean anyway hands every later phase,
+    validator and agent a record in a language they do not read.
+    """
+    share, _ = hangul_share(data)
+    return share < HANGUL_PROSE_LIMIT
+
+
+def _schema_string_keys(schema: Mapping[str, Any], *, enums: bool) -> set[str]:
+    found: set[str] = set()
+
+    def walk(node: Any) -> None:
+        if not isinstance(node, Mapping):
+            return
+        if node.get("type") == "object":
+            for key, child in (node.get("properties") or {}).items():
+                if isinstance(child, Mapping) and child.get("type") == "string":
+                    if ("enum" in child) == enums:
+                        found.add(str(key))
+                elif isinstance(child, Mapping) and enums and "enum" in child:
+                    # An enum with no declared type is still an enum.
+                    found.add(str(key))
+                walk(child)
+        elif node.get("type") == "array":
+            walk(node.get("items") or {})
+        for combinator in ("oneOf", "anyOf", "allOf"):
+            for branch in node.get(combinator) or []:
+                walk(branch)
+
+    for definition in (schema.get("$defs") or {}).values():
+        walk(definition)
+    walk(schema)
+    return found
+
+
+def schema_string_keys(schema: Mapping[str, Any]) -> set[str]:
+    """Every leaf key in the schema whose value is a free-form string.
+
+    The drift guard compares this against the two sets above, so adding a
+    report field forces a decision about whether a translator may touch it.
+    """
+    return _schema_string_keys(schema, enums=False)
+
+
+def schema_enum_keys(schema: Mapping[str, Any]) -> set[str]:
+    """Every leaf key the schema constrains to an enum, anywhere.
+
+    A name can be an enum in one definition and free prose in another —
+    `risk` is `high|medium|low` on a hotspot and a sentence on a risk row.
+    The renderer reaches for the same name either way (`tone-{{ row.risk }}`),
+    so one enum occurrence makes the name structural everywhere.
+    """
+    return _schema_string_keys(schema, enums=True)

package/runtime/python/okstra_ctl/report_views.py

@@ -132,12 +132,23 @@ def _infer_run_meta_from_path(path: Path) -> dict:
     return {"task_type": m.group("task_type"), "seq": m.group("seq")} if m else {}
 
 
+# 리포트 헤더는 이 값들을 인라인 코드로 렌더한다 (`- Task Type: \`x\``). 마커를
+# 벗기지 않으면 백틱이 sidecar 파일명과 frontmatter 로 새고, 다음 run 의
+# clarification 캐리인이 `user-response-<task-type>-<seq>.md` 매칭에 실패한다.
+_INLINE_CODE_VALUE_RE = re.compile(r"^`(?P<value>.+)`$")
+
+
+def _strip_inline_code(value: str) -> str:
+    m = _INLINE_CODE_VALUE_RE.match(value)
+    return m.group("value").strip() if m else value
+
+
 def _infer_run_meta_from_body(text: str) -> dict:
     found: dict[str, str] = {}
     for label, key in (("Task Key", "task_key"), ("Task Type", "task_type")):
         m = re.search(rf"^- {label}:\s*(\S.*?)\s*$", text, re.MULTILINE)
         if m:
-            found[key] = m.group(1)
+            found[key] = _strip_inline_code(m.group(1))
     return found
 
 
@@ -145,9 +156,14 @@ def infer_run_meta(report_path: Path, *, task_key: Optional[str] = None,
                    task_type: Optional[str] = None, seq: Optional[str] = None,
                    source_report: Optional[str] = None) -> RunMeta:
     """Derive a ``RunMeta`` from a final-report path/body, honouring any
-    explicit override. Single reference point for BOTH the HTML view render
-    script and the in-session user-response writer, so sidecar match keys
-    (task_type/seq/source-report) never drift between the two paths."""
+    explicit override.
+
+    Used by the schema-v1 HTML view render script and by the in-session
+    user-response writer. Schema-v2 resolves its own ``HtmlRunMeta`` from the
+    data.json header instead, so the sidecar match keys (task_type/seq/
+    source-report) this produces must agree with that header — the sidecar
+    name the v2 HTML advertises is the one the next run's carry-in looks for.
+    """
     text = report_path.read_text(encoding="utf-8")
     inferred = {**_infer_run_meta_from_path(report_path), **_infer_run_meta_from_body(text)}
     return RunMeta(
@@ -1194,9 +1210,7 @@ def analysis_review_context(src_md_path: Path) -> AnalysisReviewContext | None:
     return AnalysisReviewContext(selector_ids=tuple(sorted(found)))
 
 
-def plan_approval_context(
-    src_md_path: Path, src_text: str
-) -> PlanApprovalContext | None:
+def plan_approval_context(src_md_path: Path) -> PlanApprovalContext | None:
     """implementation-planning 보고서 + sibling data.json 의 optionCandidates 가
     있을 때만 컨텍스트를 만든다. planning 여부는 task-type 문자열이 아니라
     data.json 의 ``implementationPlanning`` 키(SSOT)로 판정한다 — renderer 와
@@ -1209,7 +1223,7 @@ def plan_approval_context(
     state = plan_approval_state(data)
     if state is None:
         return None
-    scan = scan_approval_gate(src_text)
+    scan = scan_approval_gate(src_md_path)
     blocker_ids = state.blocker_ids
     reason = state.disabled_reason
     if scan.unreadable_reason:
@@ -1418,7 +1432,7 @@ def render_html_view(
             "re-render the report so §1 matches the schema before generating "
             "the HTML view."
         )
-    approval_ctx = plan_approval_context(src_md_path, src_text)
+    approval_ctx = plan_approval_context(src_md_path)
     analysis_review_ctx = analysis_review_context(src_md_path)
     reader_ctx = reader_dashboard_context(src_md_path, src_text, approval_ctx)
     has_clarifications = report_has_clarification_items(src_text)

package/runtime/python/okstra_ctl/run.py

@@ -434,7 +434,7 @@ def _validate_approved_plan(path: str) -> None:
     _validate_data_json_approval_consistency(p, markdown_approved=True)
     # frontmatter approved == true 상태. §1 Clarification Items 의
     # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
-    scan = scan_approval_gate(body)
+    scan = scan_approval_gate(p)
     if scan.unreadable_reason:
         raise PrepareError(
             f"approved plan §1 approval gate could not be read: {path}\n"

package/runtime/python/okstra_ctl/user_response.py

@@ -24,7 +24,7 @@ from okstra_ctl.report_views import (
 from okstra_ctl.report_view_artifacts import user_responses_dir_for_report
 from okstra_ctl.listing import list_runs, absolute_final_report_path
 from okstra_ctl.clarification_items import (
-    parse_clarification_rows,
+    read_clarification_rows,
     scan_open_user_input,
     section_1_present_but_unparsed,
     _section_1_slice,
@@ -320,9 +320,14 @@ def load_authoritative_analysis_review(
         if _analysis_review_matches_with_valid_created_at(text):
             attached.append(f"\n## {sidecar.name}\n\n{text.strip()}\n")
     if not attached:
-        raise UserResponseError(
-            "existing review sidecar has no ANALYSIS REVIEW block"
-        )
+        # `sidecar_name` matches every user-response sidecar for this run, not
+        # just review ones — recording a clarification answer produces the same
+        # filename. No `## ANALYSIS REVIEW` block in any of them means no review
+        # was attached, which is what `None` says; raising here made the routine
+        # act of answering a clarification disqualify the report as a carry-in
+        # candidate. A block that *is* present but malformed still raises, in
+        # `_analysis_review_matches_with_valid_created_at` above.
+        return None
     review = parse_analysis_review("".join(attached))
     if review is None:
         raise UserResponseError("analysis review sidecar is unreadable")
@@ -443,7 +448,7 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
         if report is None or not report.is_file():
             continue
         text = report.read_text(encoding="utf-8")
-        scan = scan_open_user_input(text)
+        scan = scan_open_user_input(report)
         base = {"taskKey": key, "taskType": row.get("taskType", ""),
                 "seq": _seq_from_report(report), "reportPath": str(report),
                 "reportMtime": report.stat().st_mtime}
@@ -541,7 +546,7 @@ def resolve_refs(report_text: str, refs: list[str]) -> list[dict]:
 def show_open_rows(report_path: Path) -> dict:
     text = report_path.read_text(encoding="utf-8")
     rows = []
-    for r in parse_clarification_rows(text):
+    for r in read_clarification_rows(report_path):
         it = r["item"]
         if it.status not in ("open", "answered"):
             continue