okstra 0.188.1 → 0.189.1

package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py

@@ -0,0 +1,280 @@
+"""run 갈래의 교정 원장 대조 — 매니페스트가 정한 스키마·소스로 `check_corrections` 를 돌린다.
+
+`materialize --corrections`, `check-corrections`, `apply-corrections` 가 같은 대조
+함수를 부른다. 스키마는 조립(`report_assembly.assemble_report`)이 쓰는 것과 같은
+계약 3.0 완성 리포트 스키마이고, task 의미 검증기의 입력(요구 id 순서·참여
+analyser)은 작성자가 받는 합성 묶음에서 가져온다 — 두 소비자가 다른 규칙을 보지
+않게 하기 위해서다.
+
+`apply-corrections` 는 replace·remove 만 있는 원장을 작성자 라운드 없이 서사에
+쓰고 활동 원장에 `lead-correction-applied` 행을 남긴다. 선례는 implementation-
+planning 의 planner self-fix 기록(`plan_items_cli._record_self_fixes`)이다.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import tempfile
+from typing import Any, Mapping
+
+from ..activity import (
+    ActivityProjectionError,
+    agent_activity_rows,
+    record_activity,
+)
+from ...final_report_schema import load_schema_version
+from ...implementation_options import validate_implementation_option_selection
+from ...report_contract import TASK_TYPE_DATA_PROPERTY
+from ...report_corrections import (
+    CorrectionsCheck,
+    check_corrections,
+    load_corrections,
+    render_applied_narrative,
+)
+from ...report_inputs import report_narrative_path, uses_report_contract_v3
+from ...report_synthesis_packet import (
+    ReportSynthesisPacketError,
+    build_report_synthesis_packet,
+)
+from .inputs import AgentPromptCliError, _authorized_path, _relative
+
+
+LEAD_CORRECTION_ACTIVITY_KIND = "lead-correction-applied"
+# 활동 원장의 `agent` 허용값 중 리드를 뜻하는 고정 이름(`activity._validate_activity_ownership`).
+_LEAD_AGENT = "okstra-lead"
+
+
+def run_corrections_check(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    corrections_path: Path,
+    narrative_path: Path,
+) -> CorrectionsCheck:
+    """원장을 이 run 의 기준 서사에 대조한다. 결함은 `CorrectionsCheck.defects` 에 모인다."""
+    ledger, load_defects = load_corrections(corrections_path)
+    if load_defects:
+        return CorrectionsCheck(ledger, (), None, False, {}, tuple(load_defects))
+    if not uses_report_contract_v3(manifest):
+        return CorrectionsCheck(ledger, (), None, False, {}, (
+            "owner=lead correction=ledger path=- reason=corrections require report "
+            "contract 3.0 (a Markdown narrative); this run uses an older contract",
+        ))
+    contract = manifest.get("agentContract")
+    authorized = contract.get("authorizedPaths") if isinstance(contract, Mapping) else None
+    authorized = authorized if isinstance(authorized, Mapping) else {}
+    try:
+        base_path = _authorized_path(
+            project_root,
+            str(ledger.get("baseNarrativePath") or ""),
+            authorized.get("resultRoots"),
+            "base narrative",
+            must_exist=True,
+        )
+    except AgentPromptCliError as exc:
+        return CorrectionsCheck(ledger, (), None, False, {}, (
+            f"owner=lead correction=ledger path={ledger.get('baseNarrativePath')} reason={exc}",
+        ))
+    try:
+        packet = build_report_synthesis_packet(
+            project_root=project_root,
+            manifest=manifest,
+            active_context=active_context,
+            team_state=team_state,
+            narrative_path=narrative_path,
+        )
+    except ReportSynthesisPacketError as exc:
+        return CorrectionsCheck(ledger, (), None, False, {}, tuple(
+            f"owner={issue.owner} correction=ledger path={issue.path} "
+            f"reason=synthesis packet source defect: {issue.reason}"
+            for issue in exc.issues
+        ))
+    task_type = str(manifest.get("taskType") or "")
+    semantic_validator = None
+    if task_type == "implementation-option-selection":
+        block_key = TASK_TYPE_DATA_PROPERTY[task_type]
+        original_ids = packet.original_requirement_ids
+        analysers = packet.participating_analysers
+
+        def semantic_validator(data: dict[str, Any]) -> list[str]:
+            block = data.get(block_key)
+            return validate_implementation_option_selection(
+                block if isinstance(block, Mapping) else {}, original_ids, analysers,
+            )
+
+    return check_corrections(
+        ledger=ledger,
+        base_narrative=base_path.read_text(encoding="utf-8"),
+        schema=load_schema_version("3.0"),
+        block_rules=packet.block_rules,
+        semantic_validator=semantic_validator,
+    )
+
+
+def corrections_payload(
+    check: CorrectionsCheck, *, project_root: Path, corrections_path: Path,
+) -> dict[str, Any]:
+    """`check-corrections --json` 의 출력."""
+    return {
+        "ok": check.ok,
+        "correctionsPath": _relative(project_root, corrections_path),
+        "mechanical": check.mechanical,
+        "corrections": [
+            {
+                "id": item.get("id"),
+                "kind": item.get("kind"),
+                "path": item.get("path"),
+                "constraints": list(check.constraints.get(str(item.get("id")), ())),
+            }
+            for item in check.corrections
+        ],
+        "defects": list(check.defects),
+    }
+
+
+def run_corrections_apply(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    manifest_path: Path,
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    corrections_path: Path,
+) -> dict[str, Any]:
+    """기계적 원장을 서사에 쓰고 활동 행을 남긴다 — `apply-corrections` 의 본체.
+
+    순서: 대조(결함이면 거절) → rewrite 없음 확인 → 활동 계약·중복 적용 확인 →
+    서사 원자적 쓰기 → 활동 행. 활동 계약이 없는 run 은 서사를 쓰기 전에
+    거절한다: 행 없는 기계 수정은 감사에서 작성자의 것으로 읽힌다.
+    """
+    if not uses_report_contract_v3(manifest):
+        raise AgentPromptCliError(
+            "apply-corrections requires report contract 3.0 (a Markdown "
+            "narrative); this run uses an older contract"
+        )
+    narrative_path = report_narrative_path(project_root, manifest)
+    events_value = manifest.get("leadEventsPath")
+    if manifest.get("activityContractVersion") != 1 or not (
+        isinstance(events_value, str) and events_value.strip()
+    ):
+        raise AgentPromptCliError(
+            "apply-corrections records a `lead-correction-applied` activity row, "
+            "and this run manifest declares no activity contract "
+            "(activityContractVersion 1 with leadEventsPath); dispatch the "
+            "writer with --corrections instead"
+        )
+    corrections_rel = _relative(project_root, corrections_path)
+    check = run_corrections_check(
+        project_root=project_root,
+        manifest=manifest,
+        active_context=active_context,
+        team_state=team_state,
+        corrections_path=corrections_path,
+        narrative_path=narrative_path,
+    )
+    if check.defects:
+        raise AgentPromptCliError(
+            "report-writer corrections defects: " + "; ".join(check.defects)
+        )
+    if not check.mechanical:
+        pending = ", ".join(
+            str(item.get("id")) for item in check.corrections
+            if item.get("kind") == "rewrite"
+        )
+        raise AgentPromptCliError(
+            f"corrections ledger has rewrite entries ({pending}): a rewrite "
+            "needs a writer round — materialize the report-writer prompt with "
+            "--corrections instead of applying"
+        )
+    base_path = project_root / str(check.ledger.get("baseNarrativePath") or "")
+    if os.path.normpath(base_path) == os.path.normpath(narrative_path):
+        raise AgentPromptCliError(
+            "baseNarrativePath is the live narrative "
+            f"({_relative(project_root, narrative_path)}); applying would "
+            "overwrite the only copy of the attempt being corrected. Copy it "
+            "to worker-results/report-writer-narrative-a<N>-<task-type>-<seq>.md "
+            "first and point the ledger at that copy"
+        )
+    previous = _already_applied(project_root, manifest_path, corrections_rel)
+    if previous is not None:
+        raise AgentPromptCliError(
+            f"corrections ledger {corrections_rel} was already applied as "
+            f"activity {previous}; a further correction needs a new ledger "
+            "whose baseNarrativePath is the narrative that apply wrote"
+        )
+    applied_ids = [str(item.get("id")) for item in check.corrections]
+    narrative_rel = _relative(project_root, narrative_path)
+    _write_text_atomic(
+        narrative_path, render_applied_narrative(check, load_schema_version("3.0")),
+    )
+    details = {
+        "kind": LEAD_CORRECTION_ACTIVITY_KIND,
+        "agent": _LEAD_AGENT,
+        "summary": (
+            f"Applied {len(applied_ids)} mechanical correction(s) "
+            f"({', '.join(applied_ids)}) from {corrections_rel} to the report "
+            "narrative without a writer round"
+        ),
+        "planItemIds": [],
+        "resultPath": narrative_rel,
+        "commands": [],
+        "evidenceRefs": [corrections_rel, *applied_ids],
+        "outcome": "completed",
+    }
+    try:
+        event = record_activity(project_root, manifest_path, details)
+    except ActivityProjectionError as exc:
+        raise AgentPromptCliError(
+            f"narrative written to {narrative_rel} but the activity row was "
+            f"refused: {exc}; re-run apply-corrections once the cause is fixed "
+            "(the same ledger applies again to the same base)"
+        ) from exc
+    return {
+        "ok": True,
+        "correctionsPath": corrections_rel,
+        "narrativePath": narrative_rel,
+        "appliedCorrectionIds": applied_ids,
+        "activityId": event.details.get("activityId"),
+        "activityLine": (
+            f"ACTIVITY: id={event.details.get('activityId')} agent={_LEAD_AGENT} "
+            f"kind={LEAD_CORRECTION_ACTIVITY_KIND} corrections={corrections_rel} "
+            f"result={narrative_rel}"
+        ),
+    }
+
+
+def _already_applied(
+    project_root: Path, manifest_path: Path, corrections_rel: str,
+) -> str | None:
+    """이 원장을 이미 적용한 활동 행의 id. 없으면 None."""
+    try:
+        rows = agent_activity_rows(project_root, manifest_path)
+    except ActivityProjectionError as exc:
+        raise AgentPromptCliError(f"activity ledger is unreadable: {exc}") from exc
+    for row in rows:
+        refs = row.get("evidenceRefs")
+        if (
+            row.get("kind") == LEAD_CORRECTION_ACTIVITY_KIND
+            and isinstance(refs, list)
+            and corrections_rel in refs
+        ):
+            return str(row.get("activityId"))
+    return None
+
+
+def _write_text_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=path.parent,
+    )
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)

package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py

@@ -32,13 +32,25 @@ from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignmen
 from ...path_hints import hydrate_active_run_context
 from ...worker_prompt_headers import worker_prompt_headers
 from ...final_report_paths import final_report_data_path
+from ...final_report_schema import load_schema_version
 from ...report_inputs import report_narrative_path, uses_report_contract_v3
+from ...report_narrative import NarrativeContractError, parse_narrative_structure
 from ...report_synthesis_packet import (
     ReportSynthesisPacketError,
     materialize_report_synthesis_packet,
 )
 from ...worker_prompt_body import report_writer_input_lines
 from ...dispatch_state import detect_terminal_backend
+from ...report_corrections import (
+    body_owned_section_conflicts,
+    render_corrections_section,
+    render_output_section,
+)
+from .corrections import (
+    corrections_payload,
+    run_corrections_apply,
+    run_corrections_check,
+)
 from .dynamic_verifier import (
     _dynamic_verifier_source,
     _reserve_dynamic_verifier_request,
@@ -270,6 +282,26 @@ def _materialize_run(
                 narrative_path=result_path,
             ),
         )
+    if args.audience == "report-writer" and uses_report_contract_v3(manifest):
+        body = _with_report_writer_sections(
+            args,
+            project_root,
+            manifest,
+            authorized,
+            active_context,
+            body,
+            narrative_path=result_path,
+        )
+    elif getattr(args, "corrections", None):
+        if args.audience != "report-writer":
+            raise AgentPromptCliError(
+                "--corrections is a report-writer materialization option; "
+                f"audience {args.audience} has no corrections ledger"
+            )
+        raise AgentPromptCliError(
+            "--corrections requires report contract 3.0 (a Markdown narrative); "
+            "this run uses an older contract"
+        )
     request = AgentInvocationRequest(
         invocation_id=args.invocation_id,
         worker_id=args.worker_id if identity is None else None,
@@ -315,6 +347,165 @@ def _normalized(path: Path) -> Path:
     return Path(os.path.normpath(path))
 
 
+def _with_report_writer_sections(
+    args: argparse.Namespace,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    authorized: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    body: str,
+    *,
+    narrative_path: Path,
+) -> str:
+    """run 갈래 report-writer 프롬프트의 okstra 소유 절을 본문 끝에 렌더한다.
+
+    `## Output` 은 매 디스패치에 렌더한다 — 세 산출물을 리드가 손으로 열거하다
+    하나를 빠뜨리면 `required worker artifact was not produced` 로 끝났다.
+    `--corrections` 가 있으면 원장을 대조해 `## Corrections` 를 그 앞에 둔다.
+    리드가 자유 서술로 적던 교정 지시는 기계가 대조할 수 없어 값 오류가
+    조립에서야 드러났다(2026-09-03 실측: 재실행 6회 중 4회). 그래서 원장 없는
+    교정 디스패치(서사가 이미 있고 파싱되는 경우)는 거절한다. 두 절은 okstra 가
+    렌더하므로 본문에 같은 제목이 있으면 거절한다.
+    """
+    conflicts = body_owned_section_conflicts(body)
+    if conflicts:
+        raise AgentPromptCliError(
+            f"instruction body must not contain {', '.join(conflicts)}: okstra "
+            "renders those sections itself (## Output from the run manifest, "
+            "## Corrections from the --corrections ledger)"
+        )
+    sections: list[str] = []
+    if getattr(args, "corrections", None):
+        corrections_path = _authorized_path(
+            project_root,
+            args.corrections,
+            authorized.get("instructionRoots"),
+            "corrections",
+            must_exist=True,
+        )
+        check = run_corrections_check(
+            project_root=project_root,
+            manifest=manifest,
+            active_context=active_context,
+            team_state=_load_team_state(project_root, manifest),
+            corrections_path=corrections_path,
+            narrative_path=narrative_path,
+        )
+        if check.defects:
+            raise AgentPromptCliError(
+                "report-writer corrections defects: " + "; ".join(check.defects)
+            )
+        sections.extend(render_corrections_section(
+            check,
+            base_narrative_rel=str(check.ledger.get("baseNarrativePath") or ""),
+            corrections_rel=_relative(project_root, corrections_path),
+        ))
+        sections.append("")
+    else:
+        _refuse_free_form_correction(project_root, narrative_path)
+    sections.extend(render_output_section())
+    return body.rstrip("\n") + "\n\n" + "\n".join(sections) + "\n"
+
+
+def _refuse_free_form_correction(project_root: Path, narrative_path: Path) -> None:
+    """서사가 이미 있고 구조가 읽히면 이 디스패치는 교정이다 — 원장 없이는 거절한다.
+
+    구조가 읽히지 않는 서사(줄 문법·소유권 결함)는 교정 대상이 아니라 재저작
+    대상이다(원장의 경로가 해소될 자료가 없다). 그 디스패치는 원장 없이
+    통과한다. 값 결함(패턴 밖 id, enum 밖 값)은 구조가 읽히는 서사이고, 그것이
+    원장이 고치는 자리다 — 실측(dev-10626 a3)의 `SC-` id 20곳이 이 경우다.
+    """
+    if not narrative_path.is_file():
+        return
+    try:
+        parse_narrative_structure(
+            narrative_path.read_text(encoding="utf-8"), load_schema_version("3.0"),
+        )
+    except NarrativeContractError:
+        return
+    narrative_rel = _relative(project_root, narrative_path)
+    raise AgentPromptCliError(
+        f"report-writer narrative already exists at {narrative_rel} and parses, "
+        "so this is a corrective dispatch, and a free-form correction is refused: "
+        "nothing can check it before the writer runs. Write a corrections ledger "
+        "(schemas/report-writer-corrections-v1.0.schema.json; baseNarrativePath "
+        "names a preserved copy of that attempt), run `okstra agent-prompt "
+        "check-corrections --project-root <root> --run-manifest <manifest> "
+        "--corrections <ledger>` until it reports no defect, then pass the same "
+        "--corrections here. A ledger of only replace/remove entries needs no "
+        "writer round: `okstra agent-prompt apply-corrections` writes the "
+        "narrative and records the activity row. Only a narrative whose "
+        "structure does not parse (line grammar, unknown top-level field) is "
+        "re-authored without a ledger; value defects are what the ledger fixes"
+    )
+
+
+def _corrections_context(
+    args: argparse.Namespace,
+) -> tuple[Path, Path, dict[str, Any], Mapping[str, Any], Path]:
+    """`check-corrections`·`apply-corrections` 가 공유하는 입력 해소."""
+    project_root = _project_root(args.project_root)
+    manifest_path = _project_input(project_root, args.run_manifest, "run manifest")
+    manifest = _read_json_object(manifest_path, "run manifest")
+    contract = _mapping(manifest.get("agentContract"), "run agent contract")
+    authorized = _mapping(contract.get("authorizedPaths"), "authorized paths")
+    corrections_path = _authorized_path(
+        project_root,
+        args.corrections,
+        authorized.get("instructionRoots"),
+        "corrections",
+        must_exist=True,
+    )
+    active_context_path = _project_manifest_path(
+        project_root,
+        manifest.get("activeRunContextPath"),
+        "active run context",
+        must_exist=True,
+    )
+    active_context = hydrate_active_run_context(
+        _read_json_object(active_context_path, "active run context")
+    )
+    return project_root, manifest_path, manifest, active_context, corrections_path
+
+
+def _check_corrections(args: argparse.Namespace) -> dict[str, Any]:
+    """`okstra agent-prompt check-corrections` — 실체화 없이 원장만 대조한다."""
+    project_root, _manifest_path, manifest, active_context, corrections_path = (
+        _corrections_context(args)
+    )
+    narrative_path = (
+        report_narrative_path(project_root, manifest)
+        if uses_report_contract_v3(manifest)
+        else project_root
+    )
+    check = run_corrections_check(
+        project_root=project_root,
+        manifest=manifest,
+        active_context=active_context,
+        team_state=_load_team_state(project_root, manifest),
+        corrections_path=corrections_path,
+        narrative_path=narrative_path,
+    )
+    return corrections_payload(
+        check, project_root=project_root, corrections_path=corrections_path,
+    )
+
+
+def _apply_corrections(args: argparse.Namespace) -> dict[str, Any]:
+    """`okstra agent-prompt apply-corrections` — 기계적 원장을 서사에 쓴다."""
+    project_root, manifest_path, manifest, active_context, corrections_path = (
+        _corrections_context(args)
+    )
+    return run_corrections_apply(
+        project_root=project_root,
+        manifest=manifest,
+        manifest_path=manifest_path,
+        active_context=active_context,
+        team_state=_load_team_state(project_root, manifest),
+        corrections_path=corrections_path,
+    )
+
+
 def _validate_report_writer_paths(
     project_root: Path,
     manifest: Mapping[str, Any],

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -99,6 +99,7 @@ def build_analysis_packet(
     clarification_response_path: Path | None,
     directive: str,
     instruction_set_relative_path: str,
+    group_context_path: Path | None = None,
     fix_history_text: str = "",
     stage_ledger_json: str = "",
     stage_ledger_notice: str = "",
@@ -112,8 +113,13 @@ def build_analysis_packet(
     from disk state this file does not own. Each arrives already narrowed, and
     an empty string means the caller found nothing to carry — the matching
     block is then omitted rather than rendered saying "none".
+
+    `group_context_path` is the task-group context prepare copied into the
+    instruction set (`task-group-context.md`); `None` means the group has no
+    such document and the packet carries no `## Task-Group Context` section.
     """
     brief_text = task_brief_path.read_text(encoding="utf-8")
+    group_context_text = _read_optional(group_context_path) if group_context_path else ""
     profile_text = analysis_profile_path.read_text(encoding="utf-8")
     reference_text = _read_optional(reference_expectations_path)
     clarification_text = (
@@ -127,8 +133,12 @@ def build_analysis_packet(
             task_type,
             instruction_set_relative_path,
             bool(clarification_response_path),
+            bool(group_context_text),
         )
     )
+    # 그룹 맥락은 브리프 발췌보다 앞에 둔다: 짧고 "왜" 를 담으며, 46KB 에서 잘리는
+    # 읽기(agy view_file)에서도 도착해야 하는 절이다.
+    parts.extend(_group_context_block(group_context_text))
     parts.extend(_brief_block(brief_text))
     parts.extend(_profile_block(task_type, profile_text))
     parts.extend(_reference_block(reference_text))
@@ -243,6 +253,7 @@ def _intro_block(
     task_type: str,
     instruction_set: str,
     has_clarification: bool,
+    has_group_context: bool = False,
 ) -> list[str]:
     lines = [
         f"# OKSTRA Analysis Packet - {task_key}",
@@ -268,9 +279,36 @@ def _intro_block(
         lines.append(
             f"- Clarification response: `{instruction_set}/clarification-response.md`"
         )
+    if has_group_context:
+        lines.append(
+            f"- Task-group context: `{instruction_set}/task-group-context.md`"
+        )
     return lines
 
 
+GROUP_CONTEXT_PREFACE = (
+    "Background shared by every task in this task-group, copied from the group's "
+    "`group-context.md`. It is not this task's requirement ledger: the "
+    "`## Task-Specific Brief Extract` below decides what this run must deliver, "
+    "while this section decides how the result is measured and what no task in the "
+    "group may break. Where the two conflict, raise a `Clarification Items` row; "
+    "never resolve the conflict silently in either direction."
+)
+
+
+def _group_context_block(group_context_text: str) -> list[str]:
+    if not group_context_text.strip():
+        return []
+    return [
+        "",
+        "## Task-Group Context",
+        "",
+        GROUP_CONTEXT_PREFACE,
+        "",
+        _strip_frontmatter(group_context_text).strip(),
+    ]
+
+
 def _brief_block(brief_text: str) -> list[str]:
     return [
         "",