okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -11,6 +11,17 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+from .implementation_options import (
+    CANDIDATE_COMPARISON_ROUTING,
+    EVALUATION_CRITERIA,
+    MAX_CRITERION_VALUE,
+    MAX_RANKED_OPTIONS,
+    MIN_CRITERION_VALUE,
+    MIN_FEASIBLE_VOTES,
+    NO_VALID_OPTIONS_ROUTING,
+)
+from .report_narrative import writer_owned_data
+from .scope_provenance import brief_end_state_id_sequence
 
 
 @dataclass(frozen=True)
@@ -52,6 +63,97 @@ class ReportSynthesisPacket:
     result_path: str
     sources: tuple[ReportSynthesisSource, ...]
     accounting_snapshot: dict[str, Any]
+    original_requirement_ids: tuple[str, ...] = ()
+    participating_analysers: tuple[str, ...] = ()
+    # 증분 판정. 저작 계약이 이번 run 의 stage 번호를 말할 수 있는 유일한 출처다.
+    incremental_decision: dict[str, Any] | None = None
+
+    def _carry_instructions(self) -> list[str]:
+        """이번 run 의 이월 지시. 증분이 아니면 빈 목록.
+
+        일반 규칙으로 두면 계획 분석자 프로필의 한 줄이 되고, 그 줄은 이번
+        run 의 `carry_stages` 값을 말하지 못한다. 번호를 박아 넣는 자리는
+        판정을 아는 여기뿐이다.
+        """
+        decision = self.incremental_decision
+        if not decision:
+            return []
+        carried = ", ".join(str(stage) for stage in decision.get("carryStages", []))
+        reverify = ", ".join(str(stage) for stage in decision.get("reverifyStages", []))
+        return [
+            "This run is an incremental re-plan. Record the decision verbatim as "
+            "`implementationPlanning.incrementalDecision` with keys mode, "
+            "reverifyStages, carryStages, reason.",
+            f"Copy stage rows {carried} from the \"{CARRIED_STAGES_LABEL}\" source "
+            f"into `implementationPlanning.stages` unchanged - every field, byte for "
+            f"byte. Author only stage(s) {reverify}. `okstra incremental-carry` "
+            f"rejects a carried stage that changed or is missing.",
+        ]
+
+    def _carry_validation_rules(self) -> list[str]:
+        return ["carried-stages-unchanged"] if self.incremental_decision else []
+
+    def _task_instructions(self) -> list[str]:
+        if self.task_type == "implementation-planning":
+            return self._planning_requirement_instructions()
+        if self.task_type != "implementation-option-selection":
+            return []
+        criteria = ", ".join(f"`{item}`" for item in EVALUATION_CRITERIA)
+        requirement_ids = ", ".join(
+            f"`{item}`" for item in self.original_requirement_ids
+        )
+        analysers = ", ".join(
+            f"`{item}`" for item in self.participating_analysers
+        )
+        return [
+            f"Original requirement ids, in order: {requirement_ids}.",
+            f"Participating analysers: {analysers}.",
+            f"Evaluation criteria, in exact order: {criteria}.",
+            "Every `rankedOptions` and `candidateAudit` row must contain one "
+            "`requirementCoverage` row per original requirement id and one "
+            "`criterionScores` row per evaluation criterion. Weights and scores "
+            f"are integers from {MIN_CRITERION_VALUE} through {MAX_CRITERION_VALUE}; "
+            "`weightedScore` is the recalculated weighted mean.",
+            "A ranked option is valid only when every participating analyser "
+            "supplied one feasibility vote, at least "
+            f"{MIN_FEASIBLE_VOTES} votes are `feasible`, and both `safetyBlockers` "
+            "and `unresolvedFeasibilityFacts` are empty.",
+            f"Rank at most {MAX_RANKED_OPTIONS} valid options by descending "
+            "`requirement-fit`, `correctness-risk`, `architecture-fit`, "
+            "`weightedScore`, then id. With valid options set routing to "
+            f"`{CANDIDATE_COMPARISON_ROUTING}`; without a valid option use "
+            f"`{NO_VALID_OPTIONS_ROUTING}`.",
+            "In `candidate-comparison`, keep `preselectedDirection` null and do "
+            "not route directly to `implementation-planning`. In "
+            "`preselected-validation`, emit exactly one validated option, an empty "
+            "`candidateAudit`, a cited `preselectedDirection`, and routing "
+            "`implementation-planning`.",
+        ]
+
+    def _planning_requirement_instructions(self) -> list[str]:
+        """계획 저작 계약에 브리프 요구사항 id 순서를 박아 넣는다.
+
+        `validate_selected_direction_plan` 은 `requirementCoverage` 행 순서가
+        taskBriefPath 의 end-state id 순서와 정확히 한 번씩 일치할 것을
+        요구한다 (`implementation_direction._coverage_summary_errors`). 그
+        순서가 저작 계약에 없으면 작성자는 브리프 원문에서 재유도해야 하고,
+        오차는 §5.5.9 라운드 낭비와 조립 거부로 돌아온다. 레거시 브리프
+        (end-state id 없음)는 빈 목록이므로 지시도 싣지 않는다 — 검증기도
+        같은 조건으로 자기 비활성화한다.
+        """
+        if not self.original_requirement_ids:
+            return []
+        requirement_ids = ", ".join(
+            f"`{item}`" for item in self.original_requirement_ids
+        )
+        return [
+            f"Original requirement ids, in order: {requirement_ids}.",
+            "`implementationPlanning.requirementCoverage` must contain exactly "
+            "one row per original requirement id (`originalRequirementId`), in "
+            "that exact order.",
+            "`endStateCoverage` must contain exactly one row per original "
+            "requirement id; an `addressed` row names its `coveredBy` anchor.",
+        ]
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -67,6 +169,9 @@ class ReportSynthesisPacket:
                     "Preserve settled source values, identities, dissent, and user responses.",
                     "Do not invent a value when a source is missing or contradictory.",
                     "Write only the narrative, pointer, and audit artifacts named by the dispatch.",
+                    *_INTERNAL_IDENTIFIER_INSTRUCTION,
+                    *self._task_instructions(),
+                    *self._carry_instructions(),
                 ],
                 "runtimeOwnedContent": [
                     "session identifiers",
@@ -78,6 +183,7 @@ class ReportSynthesisPacket:
                     "source-digest-match",
                     "writer-owned-fields-only",
                     "all-defects-collected",
+                    *self._carry_validation_rules(),
                 ],
             },
             "accountingSnapshot": self.accounting_snapshot,
@@ -99,6 +205,11 @@ class ReportSynthesisPacket:
             "user response carry-in",
             "- Validation: source digest match, writer-owned fields, all defects collected",
         ]
+        # 작성자가 실제로 읽는 것은 마크다운이다. JSON 정본에만 실으면 지시가
+        # 도달하지 않는다.
+        lines.extend(f"- {text}" for text in _INTERNAL_IDENTIFIER_INSTRUCTION)
+        lines.extend(f"- {text}" for text in self._task_instructions())
+        lines.extend(f"- {text}" for text in self._carry_instructions())
         lines.extend(_accounting_markdown(self.accounting_snapshot))
         for source in self.sources:
             lines.extend(_source_markdown(source))
@@ -190,12 +301,129 @@ def _context_path(
     return _string(manifest.get(key))
 
 
+# 패킷은 워커 결과를 통째로 나른다. 그 안의 finding id(`F-001`)는 수렴 상태에만
+# 있고 리포트는 그 id 를 정의하는 객체를 싣지 않는다 — 인용하면 독자가 해소할 수
+# 없는 참조가 된다. 규칙은 여기에 둔다: 워커 결과를 보여 주는 자리가 여기뿐이다.
+# 집행 코드는 없다(리포트 산문은 자유 서술이다). 저자 지시로만 전달한다.
+_INTERNAL_IDENTIFIER_INSTRUCTION = (
+    "Do not cite worker-internal identifiers in reader-facing prose - finding "
+    "ids (`F-NNN`), worker ids, round labels. This report defines none of them, "
+    "so the reader cannot resolve them. State the substance instead, and cite "
+    "only identifiers the report itself defines (`R-NNN`, `C-NNN`, `A-NNN`, "
+    "stage numbers).",
+)
+
+
+CARRIED_STAGES_LABEL = "Carried plan stages"
+
+
+def read_incremental_decision(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> dict | None:
+    """이 run 의 증분 판정. 없거나 증분이 아니면 ``None``.
+
+    레코드가 없으면 full 로 읽는다 — 그것이 이 기능이 없던 동안의 동작이고,
+    "판정을 못 찾았으니 좁혀도 된다"는 반대 방향의 실패보다 안전하다.
+    """
+    value = _string(manifest.get("incrementalDecisionPath"))
+    if not value:
+        return None
+    path = _resolve(project_root, value)
+    if not path.is_file():
+        return None
+    try:
+        record = load_owned_object(path, artifact="incremental scope decision")
+    except (OSError, UnicodeError, JsonBoundaryError):
+        return None
+    if not isinstance(record, Mapping) or record.get("mode") != "incremental":
+        return None
+    stages = record.get("carryStages")
+    if not isinstance(stages, list) or not stages:
+        return None
+    return dict(record)
+
+
+def carried_stage_rows(prior_data: Mapping[str, Any], carry_stages: list) -> list[dict]:
+    """직전 리포트에서 이월 대상 stage 의 **본문 행**을 뽑는다.
+
+    Stage Ledger 가 싣는 것은 `stage`/`title`/`status`/`dependsOn`/`headCommit`
+    뿐이다. narrative 의 `stages[]` 한 행은 `sliceValue`·`acceptance`·`carryIn`·
+    `stepwiseExecution`·`exitContract`·`stageValidation` 을 요구하므로, 원장만
+    받은 작성자는 이월 행을 옮길 수 없다.
+    """
+    # 작성자에게 넘기는 행은 작성자 소유 필드만이어야 한다. 완성 리포트의
+    # stage 행에는 `designSurfaceCoverage` 같은 assembly 소유 필드가 함께 있고,
+    # 그것까지 실으면 "옮겨 적으라"는 지시가 곧 소유권 위반 지시가 된다.
+    planning = writer_owned_data(prior_data).get("implementationPlanning")
+    rows = planning.get("stages") if isinstance(planning, Mapping) else None
+    if not isinstance(rows, list):
+        return []
+    wanted = {int(stage) for stage in carry_stages if isinstance(stage, int)}
+    return [
+        dict(row)
+        for row in rows
+        if isinstance(row, Mapping) and row.get("stage") in wanted
+    ]
+
+
+def carried_stages_path(narrative_path: Path) -> Path:
+    _, markdown_path = report_synthesis_packet_paths(narrative_path)
+    return markdown_path.with_name(
+        markdown_path.name.replace(
+            "report-writer-synthesis-packet", "report-writer-carried-stages"
+        )
+    ).with_suffix(".json")
+
+
+def materialize_carried_stages(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    narrative_path: Path,
+) -> tuple[str, dict] | None:
+    """이월 stage 본문을 파일로 남기고 (프로젝트 상대 경로, 판정) 을 돌려준다.
+
+    묶음의 source 는 파일과 그 다이제스트다. 파생 내용을 특례로 인라인하지 않고
+    실제 파일로 만드는 이유는 두 가지다 — 다이제스트가 다른 source 와 같은
+    의미를 갖고, 어긋났을 때 사람이 열어 볼 수 있다.
+    """
+    decision = read_incremental_decision(project_root, manifest)
+    if decision is None:
+        return None
+    prior = _resolve(project_root, _string(decision.get("prevDataPath")))
+    if not prior.is_file():
+        return None
+    try:
+        prior_data = load_owned_object(prior, artifact="prior planning report")
+    except (OSError, UnicodeError, JsonBoundaryError):
+        return None
+    rows = carried_stage_rows(prior_data, decision["carryStages"])
+    if not rows:
+        return None
+    path = carried_stages_path(narrative_path)
+    write_owned_object_atomic(
+        path,
+        {
+            "schemaVersion": "1.0",
+            "sourcePlanPath": _string(decision.get("prevDataPath")),
+            "carryStages": list(decision["carryStages"]),
+            "stages": rows,
+        },
+        artifact="carried plan stages",
+    )
+    try:
+        return str(path.resolve().relative_to(project_root.resolve())), decision
+    except ValueError:
+        return str(path), decision
+
+
 def _source_specs(
     project_root: Path,
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
     team_state: Mapping[str, Any],
     narrative_path: Path,
+    carried_source: str,
 ) -> list[tuple[str, str, str, bool]]:
     specs: list[tuple[str, str, str, bool]] = []
     for label, owner, section, key, required in _SOURCE_FIELDS:
@@ -212,6 +440,8 @@ def _source_specs(
                 path = str(Path(instruction_set) / "final-report-schema.json")
         if path or required:
             specs.append((label, owner, path, required))
+    if carried_source:
+        specs.append((CARRIED_STAGES_LABEL, "orchestrator", carried_source, True))
     specs.extend(_user_response_specs(project_root, narrative_path))
     attempt_specs = _attempt_result_specs(manifest)
     if attempt_specs:
@@ -382,6 +612,9 @@ def build_report_synthesis_packet(
     team_state: Mapping[str, Any],
     narrative_path: Path,
 ) -> ReportSynthesisPacket:
+    carried = materialize_carried_stages(
+        project_root=project_root, manifest=manifest, narrative_path=narrative_path,
+    )
     sources = _read_sources(
         project_root,
         _source_specs(
@@ -390,14 +623,38 @@ def build_report_synthesis_packet(
             active_context,
             team_state,
             narrative_path,
+            carried[0] if carried else "",
         ),
     )
+    task_type = _string(manifest.get("taskType"))
+    original_requirement_ids: tuple[str, ...] = ()
+    participating_analysers: tuple[str, ...] = ()
+    # 계획 저작도 같은 id 순서를 계약으로 받는다 — 커버리지 행 순서 검증
+    # (`validate_selected_direction_plan`)의 기준값이 이 목록이다.
+    if task_type in ("implementation-option-selection", "implementation-planning"):
+        brief_value = _context_path(
+            manifest, active_context, "instructionSet", "taskBriefPath"
+        )
+        original_requirement_ids = brief_end_state_id_sequence(
+            _resolve(project_root, brief_value)
+        )
+    if task_type == "implementation-option-selection":
+        roster = manifest.get("recommendedWorkers")
+        if isinstance(roster, list):
+            participating_analysers = tuple(
+                _string(worker)
+                for worker in roster
+                if _string(worker) and _string(worker) != "report-writer"
+            )
     return ReportSynthesisPacket(
         task_key=_string(manifest.get("taskKey")),
-        task_type=_string(manifest.get("taskType")),
+        task_type=task_type,
         result_path=_relative(project_root, narrative_path),
         sources=sources,
         accounting_snapshot=_accounting_snapshot(team_state),
+        original_requirement_ids=original_requirement_ids,
+        participating_analysers=participating_analysers,
+        incremental_decision=carried[1] if carried else None,
     )
 
 

package/runtime/python/okstra_ctl/report_translation.py

@@ -69,6 +69,7 @@ PROSE_KEYS = frozenset({
     "expectedForm",
     "expectedOutcome",
     "expectedResult",
+    "expectedVerification",
     "failureHandling",
     "finalConclusion",
     "headline",
@@ -108,6 +109,7 @@ PROSE_KEYS = frozenset({
     "rolloutCost",
     "routingRecommendation",
     "selfFixNote",
+    "satisfaction",
     "stageTitle",
     "stageValidation",
     "statement",
@@ -293,10 +295,6 @@ STRUCTURAL_KEYS = frozenset({
 })
 
 
-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.
@@ -429,17 +427,6 @@ def hangul_share(data: Mapping[str, Any]) -> tuple[float, int]:
     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()
 
@@ -465,23 +452,3 @@ def _schema_string_keys(schema: Mapping[str, Any], *, enums: bool) -> set[str]:
         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

@@ -34,6 +34,10 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable, Optional
 
+from .user_response_values import (  # noqa: F401 — 재노출(값 타입은 leaf 소유)
+    UserPlanDecision,
+    UserResponseEntry,
+)
 from .final_report_paths import final_report_data_path
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .report_html.view_models.implementation_planning import (
@@ -1077,28 +1081,6 @@ def _slugify(text: str) -> str:
 # templates/reports/report.js implements the byte-identical client side).
 # --------------------------------------------------------------------------- #
 
-@dataclass(frozen=True)
-class UserResponseEntry:
-    response_id: str
-    kind: str
-    value: str
-    rationale: Optional[str] = None
-    disposition: str = "answer"
-
-
-@dataclass(frozen=True)
-class UserPlanDecision:
-    """HTML 계획 결정 위젯의 Export 결과.
-
-    ``status`` 가 승인이 아니면 ``reason`` 이 필수다 — 사유 없는 반려는 다음
-    run 이 무엇을 고쳐야 하는지 알 수 없어 되돌아올 수밖에 없다.
-    ``implementation_option`` 이 빈 문자열이면 라인을 생략한다 (소비 측은
-    Recommended Option 폴백)."""
-    status: str
-    implementation_option: str = ""
-    reason: str = ""
-
-
 @dataclass(frozen=True)
 class UserDirectionSelection:
     option_id: str

package/runtime/python/okstra_ctl/resolve_task_key.py

@@ -19,8 +19,21 @@ from okstra_project import (
 )
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra resolve-task-key <task-id> [--task-group <g>] [--project-root <dir>] [--cwd <dir>] [--json]
+
+Output: JSON { ok, projectRoot, matches: [ { taskKey, taskGroup, taskId,
+taskGroupPathSegment, taskIdPathSegment, taskManifestPath, ... } ] }.
+matches.length 0 = not found, 1 = unambiguous, N = ambiguous (caller asks).
+This is read-only; it never mutates task state.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra resolve-task-key",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Resolve a bare token (task-id or task-group) to candidate "
         "task-keys from the catalog."
     )

package/runtime/python/okstra_ctl/rollup.py

@@ -139,8 +139,21 @@ def build_rollup(project_root: Path, task_group: str | None) -> dict:
     }
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]
+
+Read-only. Prints a JSON roll-up of every catalog task (optionally scoped to one
+task-group): per-task run count, elapsed time (raw ms), error count, and the
+latest report path, plus group-level totals and status/category/phase tallies.
+With no --task-group it covers the whole project catalog. Time is raw ms; the
+caller formats HH:MM:SS and synthesizes the prose digest from the report files.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra rollup",
         description="Roll up run results across a task-group's tasks (raw ms).")
     parser.add_argument("--task-group", default="",