npm - okstra - Versions diffs - 0.34.1 → 0.36.0 - Mend

okstra 0.34.1 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

package/README.kr.md +26 -16
package/README.md +26 -16
package/docs/kr/architecture.md +59 -45
package/docs/kr/cli.md +61 -18
package/docs/pr-template-usage.md +65 -0
package/docs/project-structure-overview.md +358 -354
package/docs/superpowers/plans/2026-05-12-ticket-id-in-reports.md +1 -1
package/docs/superpowers/plans/2026-05-14-convergence-queue-pruning.md +1 -1
package/docs/superpowers/plans/2026-05-17-dual-format-final-report.md +1 -1
package/docs/superpowers/plans/2026-05-20-final-report-language.md +1501 -0
package/docs/superpowers/plans/2026-05-20-implementation-planning-multi-stage.md +1267 -0
package/docs/superpowers/plans/2026-05-20-okstra-run-prompt-sot-b1.md +1007 -0
package/docs/superpowers/plans/2026-05-20-wizard-messages-json-sot.md +720 -0
package/docs/superpowers/plans/2026-05-20-wizard-prompt-json-sot-a1.md +681 -0
package/docs/superpowers/plans/2026-05-21-improvement-discovery-task-type.md +1691 -0
package/docs/superpowers/specs/2026-05-20-final-report-language-design.md +383 -0
package/docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md +320 -0
package/docs/superpowers/specs/2026-05-20-okstra-run-prompt-sot-design.md +299 -0
package/docs/superpowers/specs/2026-05-21-improvement-discovery-task-type-design.md +335 -0
package/docs/task-process/README.md +74 -0
package/docs/task-process/common-flow.md +166 -0
package/docs/task-process/error-analysis.md +101 -0
package/docs/task-process/final-verification.md +167 -0
package/docs/task-process/implementation-planning.md +128 -0
package/docs/task-process/implementation.md +149 -0
package/docs/task-process/release-handoff.md +206 -0
package/docs/task-process/requirements-discovery.md +115 -0
package/package.json +1 -1
package/runtime/BUILD.json +2 -2
package/runtime/agents/SKILL.md +12 -2
package/runtime/agents/workers/claude-worker.md +26 -0
package/runtime/agents/workers/codex-worker.md +27 -1
package/runtime/agents/workers/gemini-worker.md +27 -1
package/runtime/agents/workers/report-writer-worker.md +8 -1
package/runtime/bin/okstra-central.sh +6 -6
package/runtime/bin/okstra-codex-exec.sh +49 -28
package/runtime/bin/okstra-gemini-exec.sh +39 -21
package/runtime/bin/okstra-render-final-report.py +13 -2
package/runtime/bin/okstra-wrapper-status.py +155 -0
package/runtime/bin/okstra.sh +2 -2
package/runtime/prompts/profiles/_common-contract.md +11 -6
package/runtime/prompts/profiles/error-analysis.md +3 -7
package/runtime/prompts/profiles/implementation-planning.md +22 -21
package/runtime/prompts/profiles/implementation.md +28 -11
package/runtime/prompts/profiles/improvement-discovery.md +42 -0
package/runtime/prompts/profiles/kr/_common-contract.md +92 -0
package/runtime/prompts/profiles/kr/error-analysis.md +36 -0
package/runtime/prompts/profiles/kr/final-verification.md +48 -0
package/runtime/prompts/profiles/kr/implementation-planning.md +90 -0
package/runtime/prompts/profiles/kr/implementation.md +144 -0
package/runtime/prompts/profiles/kr/improvement-discovery.md +42 -0
package/runtime/prompts/profiles/kr/release-handoff.md +104 -0
package/runtime/prompts/profiles/kr/requirements-discovery.md +42 -0
package/runtime/prompts/profiles/release-handoff.md +1 -1
package/runtime/prompts/profiles/requirements-discovery.md +8 -12
package/runtime/prompts/wizard/prompts.ko.json +230 -0
package/runtime/python/lib/okstra/cli.sh +2 -49
package/runtime/python/lib/okstra/globals.sh +21 -21
package/runtime/python/lib/okstra/interactive.sh +7 -7
package/runtime/python/okstra_ctl/clarification_items.py +3 -9
package/runtime/python/okstra_ctl/consumers.py +53 -0
package/runtime/python/okstra_ctl/final_report_schema.py +0 -7
package/runtime/python/okstra_ctl/i18n.py +73 -0
package/runtime/python/okstra_ctl/improvement_lenses.py +44 -0
package/runtime/python/okstra_ctl/index.py +1 -1
package/runtime/python/okstra_ctl/paths.py +23 -20
package/runtime/python/okstra_ctl/render.py +147 -202
package/runtime/python/okstra_ctl/render_final_report.py +53 -10
package/runtime/python/okstra_ctl/run.py +292 -107
package/runtime/python/okstra_ctl/run_context.py +22 -0
package/runtime/python/okstra_ctl/seeding.py +186 -0
package/runtime/python/okstra_ctl/wizard.py +348 -127
package/runtime/python/okstra_ctl/workflow.py +21 -2
package/runtime/python/okstra_ctl/worktree.py +54 -1
package/runtime/python/okstra_project/resolver.py +4 -3
package/runtime/python/okstra_token_usage/report.py +2 -2
package/runtime/schemas/final-report-v1.0.schema.json +22 -16
package/runtime/skills/okstra-brief/SKILL.md +124 -31
package/runtime/skills/okstra-convergence/SKILL.md +2 -3
package/runtime/skills/okstra-report-writer/SKILL.md +35 -15
package/runtime/skills/okstra-run/SKILL.md +5 -4
package/runtime/skills/okstra-schedule/SKILL.md +4 -4
package/runtime/skills/okstra-setup/SKILL.md +27 -0
package/runtime/skills/okstra-team-contract/SKILL.md +1 -1
package/runtime/templates/okstra.CLAUDE.md +104 -0
package/runtime/templates/reports/final-report.template.md +93 -98
package/runtime/templates/reports/i18n/en.json +135 -0
package/runtime/templates/reports/i18n/ko.json +135 -0
package/runtime/templates/reports/implementation-planning-input.template.md +18 -0
package/runtime/templates/reports/improvement-discovery-input.template.md +78 -0
package/runtime/templates/reports/task-brief.template.md +2 -2
package/runtime/validators/lib/fixtures.sh +30 -0
package/runtime/validators/lib/runners.sh +1 -1
package/runtime/validators/validate-implementation-plan-stages.py +211 -0
package/runtime/validators/validate-run.py +121 -26
package/runtime/validators/validate-workflow.sh +2 -2
package/runtime/validators/validate_improvement_report.py +275 -0
package/src/config.mjs +18 -0
package/src/install.mjs +41 -14
package/src/setup.mjs +133 -1
package/src/uninstall.mjs +21 -1

package/runtime/validators/validate-run.py CHANGED Viewed

@@ -54,6 +54,7 @@ def write_json(path: Path, payload: dict) -> None:
 def default_next_phase(task_type: str) -> str:
     mapping = {
         "requirements-discovery": "pending-routing-decision",
+        "improvement-discovery": "pending-routing-decision",
         "error-analysis": "implementation-planning",
         "implementation-planning": "implementation",
         "implementation": "final-verification",
@@ -144,10 +145,11 @@ def update_workflow_metadata(
     awaiting_approval = workflow.get("awaitingApproval")
     if not isinstance(awaiting_approval, bool):
         awaiting_approval = False
-    # 승인 게이트(`User Approval Request`)는 implementation 진입 직전에 한 번만 의미를 가진다.
+    # 승인 게이트(`frontmatter approved`)는 implementation 진입 직전에 한 번만 의미를 가진다.
     # implementation run 이 검증을 통과했다는 것은 `_validate_approved_plan` 이 이미 사용자
-    # 마커를 소비했다는 뜻이므로, 이 시점에 awaitingApproval 플래그를 명시적으로 내려
-    # 다음 phase 의 status 뷰에서 stale 상태로 남지 않게 한다.
+    # 승인 플래그(frontmatter `approved: true`)를 소비했다는 뜻이므로, 이 시점에
+    # awaitingApproval 플래그를 명시적으로 내려 다음 phase 의 status 뷰에서 stale 상태로
+    # 남지 않게 한다.
     if validation_status == "passed" and current_phase == "implementation":
         awaiting_approval = False
@@ -488,7 +490,7 @@ TOKEN_PLACEHOLDERS = (
 # heading (or end-of-file). Matched non-greedily so the body of the next
 # section never bleeds in.
 _TOKEN_USAGE_SECTION_RE = re.compile(
-    r"^##[ \t]+Token Usage Summary[ \t]*$\n(?P<body>.*?)(?=^##[ \t]|\Z)",
+    r"^##[ \t]+(?:Token Usage Summary|토큰 사용량 요약)[ \t]*$\n(?P<body>.*?)(?=^##[ \t]|\Z)",
     re.DOTALL | re.MULTILINE,
 )
@@ -548,7 +550,8 @@ def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
         # surfaced elsewhere by the placeholder check (which would also
         # not fire — so we add a dedicated failure here).
         failures.append(
-            "final report is missing the `## Token Usage Summary` section — "
+            "final report is missing the `## Token Usage Summary` "
+            "(or `## 토큰 사용량 요약`) section — "
             "the template renders it unconditionally and Phase 7 substitution "
             "depends on it being present."
         )
@@ -632,17 +635,21 @@ _EMPTY_CARRY_IN_SOURCE_RE = re.compile(
 # (e.g. this file itself, or skill documentation that mentions the
 # deprecated names).
 _DEPRECATED_FINAL_REPORT_PATTERNS: tuple[tuple[re.Pattern, str], ...] = (
+    (
+        re.compile(r"^##[ \t]+User Approval Request\b", re.MULTILINE),
+        "deprecated `## User Approval Request` block — approval gate moved to "
+        "the YAML frontmatter `approved: true|false` field. Delete the body section.",
+    ),
     (
         re.compile(r"^###[ \t]+4\.5\.8[ \t]+User Approval Request\b", re.MULTILINE),
-        "deprecated `### 4.5.8 User Approval Request` stub — the top-of-report "
-        "`## User Approval Request (사용자 승인 게이트)` block is the only one. "
-        "Delete the §4.5.8 heading + body.",
+        "deprecated `### 4.5.8 User Approval Request` stub — approval gate moved "
+        "to the YAML frontmatter `approved: true|false` field. Delete the §4.5.8 heading + body.",
     ),
     (
         re.compile(r"^###[ \t]+4\.5\.9[ \t]+Open Questions\b", re.MULTILINE),
         "deprecated `### 4.5.9 Open Questions` block — promote each row into "
         "`## 5. Clarification Items` with `Kind=decision` (and `Blocks=approval` "
-        "if it gated the User Approval Request).",
+        "if it gates the frontmatter approval flag).",
     ),
     (
         re.compile(
@@ -847,7 +854,6 @@ PLANNING_REQUIRED_SECTIONS = (
     "Dependency",
     "Validation Checklist",
     "Rollback",
-    "User Approval Request",
     "Plan Body Verification",
 )
@@ -933,15 +939,14 @@ _GATE_RESULT_RE = re.compile(
     re.IGNORECASE,
 )
-# Approval marker line — the bullet that toggles to grant approval. Both
-# unchecked (`- [ ] Approved`) and checked (`- [x] Approved`) forms count
-# as "checkbox present" for this gate. Line-anchored to avoid false
-# positives from inline-code prose examples elsewhere in the template
-# (mirrors `APPROVED_PLAN_PATTERN` in scripts/okstra_ctl/run.py:79).
-_APPROVAL_CHECKBOX_RE = re.compile(
-    r"^[ \t]*(?:[-*+][ \t]+)?`?\[[ xX]\][ \t]*Approved`?[ \t]*$",
-    re.MULTILINE,
+# Frontmatter approval flag — `approved: true|false` line inside the
+# leading `---` YAML block. Mirrors `APPROVED_FRONTMATTER_PATTERN` in
+# scripts/okstra_ctl/run.py.
+_APPROVED_FRONTMATTER_RE = re.compile(
+    r"^approved:[ \t]+(true|false)[ \t]*$",
+    re.IGNORECASE | re.MULTILINE,
 )
+_FRONTMATTER_BLOCK_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
 def _extract_final_verdict_token(content: str) -> str | None:
@@ -1182,20 +1187,101 @@ def validate_phase_boundary(
             f"{', '.join(PLAN_VERIFY_GATE_VALUES)}."
         )
         return
-    checkbox_present = _APPROVAL_CHECKBOX_RE.search(content) is not None
-    if gate_value in ("passed", "passed-with-dissent") and not checkbox_present:
+    fm_block = _FRONTMATTER_BLOCK_RE.match(content)
+    fm_match = (
+        _APPROVED_FRONTMATTER_RE.search(fm_block.group(1)) if fm_block else None
+    )
+    if gate_value in ("passed", "passed-with-dissent") and fm_match is None:
         failures.append(
             "implementation-planning report Gate result is "
-            f"`{gate_value}` but the top-level `User Approval Request` "
-            "checkbox line (`- [ ] Approved` / `- [x] Approved`) is missing."
+            f"`{gate_value}` but the frontmatter `approved:` field is missing — "
+            "render `approved: false` so the user (or `--approve`) can flip it."
         )
-    if gate_value in ("blocked-by-disagreement", "aborted-non-result") and checkbox_present:
+    if (
+        gate_value in ("blocked-by-disagreement", "aborted-non-result")
+        and fm_match is not None
+        and fm_match.group(1).lower() == "true"
+    ):
         failures.append(
             "implementation-planning report Gate result is "
-            f"`{gate_value}` but a top-level `User Approval Request` "
-            "checkbox line is present — gate must NOT render the checkbox "
-            "for this gate result."
+            f"`{gate_value}` but the frontmatter has `approved: true` — gate "
+            "must NOT publish a pre-approved plan when verification did not pass."
+        )
+def _parse_brief_frontmatter(brief_path: Path) -> dict:
+    """Parse YAML frontmatter from a brief file into a flat dict.
+    Handles the scalar and inline-flow-sequence shapes used by okstra briefs:
+      key: scalar_value
+      key: [item1, item2]
+    Returns {} when the file is absent, has no ``---`` delimiters, or the
+    frontmatter block is empty. Does not raise.
+    """
+    if not brief_path.is_file():
+        return {}
+    try:
+        text = brief_path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    fm_match = _FRONTMATTER_BLOCK_RE.match(text)
+    if fm_match is None:
+        return {}
+    result: dict = {}
+    for line in fm_match.group(1).splitlines():
+        if ":" not in line:
+            continue
+        key, _, raw_val = line.partition(":")
+        key = key.strip()
+        raw_val = raw_val.strip()
+        if not key:
+            continue
+        # Inline flow sequence: [a, b, c]
+        if raw_val.startswith("[") and raw_val.endswith("]"):
+            inner = raw_val[1:-1]
+            items = [s.strip() for s in inner.split(",") if s.strip()]
+            result[key] = items
+        else:
+            result[key] = raw_val
+    return result
+def _validate_improvement_discovery(
+    report_path: Path,
+    run_dir: Path,
+    brief_path: Path,
+    failures: list[str],
+) -> None:
+    """Call validate_improvement_report and fold errors into failures.
+    Errors from the phase-specific validator are prefixed with
+    ``improvement-discovery: `` to match the style used by sibling validators
+    (e.g. ``report-views: <line>``).
+    """
+    _VALIDATORS_DIR_LOCAL = Path(__file__).resolve().parent
+    if str(_VALIDATORS_DIR_LOCAL) not in sys.path:
+        sys.path.insert(0, str(_VALIDATORS_DIR_LOCAL))
+    try:
+        from validate_improvement_report import validate_improvement_report  # noqa: E402
+    except ImportError as exc:
+        failures.append(
+            f"improvement-discovery: validate_improvement_report import failed — {exc}"
         )
+        return
+    brief_frontmatter = _parse_brief_frontmatter(brief_path)
+    result = validate_improvement_report(
+        report_path=report_path,
+        run_dir=run_dir,
+        brief_frontmatter=brief_frontmatter,
+    )
+    if not result.ok:
+        for err in result.errors:
+            failures.append(f"improvement-discovery: {err}")
 def _refresh_task_catalog(project_root: Path, task_manifest: dict) -> tuple[bool, str]:
@@ -1535,6 +1621,15 @@ def main() -> int:
     validate_phase_boundary(task_type, report_path, failures)
     if task_type:
         validate_worker_results_audit(report_path, task_type, failures)
+    if task_type == "improvement-discovery":
+        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
+        brief_path = (
+            (project_root / brief_relative).resolve()
+            if brief_relative
+            else project_root / "__no-brief__"  # absent path → _parse_brief_frontmatter returns {}
+        )
+        run_dir = report_path.parent.parent
+        _validate_improvement_discovery(report_path, run_dir, brief_path, failures)
     validate_report_views(report_path, failures)
     validation_status = "passed" if not failures else "failed"

package/runtime/validators/validate-workflow.sh CHANGED Viewed

@@ -15,7 +15,7 @@ PROJECT_ID="okstra-validation"
 PROJECT_ROOT="${OKSTRA_VALIDATION_PROJECT_ROOT:-/tmp/okstra-validate.workflow}"
 WORKSPACE_APP_PATH="$PROJECT_ROOT"
 OKSTRA_SCRIPT="$WORKSPACE_ROOT/scripts/okstra.sh"
-RUN_VALIDATOR_SCRIPT="$WORKSPACE_ROOT/validators/validate-run.py"
+RUN_VALIDATOR_PATH="$WORKSPACE_ROOT/validators/validate-run.py"
 SOURCE_ASSET_ROOT="$WORKSPACE_ROOT/agents"
 TASK_TYPE="final-verification"
 PRIMARY_TASK_GROUP="validation"
@@ -47,7 +47,7 @@ source "$SCRIPT_DIR/lib/summary.sh"
 trap 'on_error "$LINENO"' ERR
 require_file "$OKSTRA_SCRIPT"
-require_file "$RUN_VALIDATOR_SCRIPT"
+require_file "$RUN_VALIDATOR_PATH"
 validate_project_root_safety

package/runtime/validators/validate_improvement_report.py ADDED Viewed

@@ -0,0 +1,275 @@
+"""Validator for final-report.md produced by the improvement-discovery phase.
+Enforces the 11-item contract in
+docs/superpowers/specs/2026-05-21-improvement-discovery-task-type-design.md §6.5.
+Called by validators/validate-run.py when task_type == "improvement-discovery".
+"""
+from __future__ import annotations
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+# scripts/ is not a package; insert it so okstra_ctl is importable directly.
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+from okstra_ctl.improvement_lenses import (
+    LENSES,
+    DEFAULT_CANDIDATE_CAP,
+    ABSOLUTE_CANDIDATE_CAP,
+    SOURCE_WORKERS,
+)
+_VERDICT_TOKENS = ("candidates-ready", "no-candidates", "blocked")
+_NEXT_PHASES = ("requirements-discovery", "implementation-planning", "error-analysis")
+_CAND_ID_RE = re.compile(r"^I-\d{3}$")
+_SOURCE_WORKER_RE = re.compile(r"^([a-z-]+):([A-Za-z0-9._-]+)$")
+_CONSENSUS_VALUES = ("full", "partial", "contested", "worker-unique")
+@dataclass
+class ValidationResult:
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+def _read_section_table(body: str, heading: str) -> list[list[str]]:
+    """Return rows of the markdown pipe-table directly under ``heading``.
+    Each row is a list of trimmed cell values. Returns [] if heading absent
+    or no table follows.
+    """
+    pattern = rf"(?m)^##\s+{re.escape(heading)}\b.*?\n(.*?)(?=^##\s|\Z)"
+    m = re.search(pattern, body, flags=re.S)
+    if not m:
+        return []
+    section = m.group(1)
+    rows: list[list[str]] = []
+    for line in section.splitlines():
+        s = line.strip()
+        if not s.startswith("|") or not s.endswith("|"):
+            continue
+        cells = [c.strip() for c in s.strip("|").split("|")]
+        if all(set(c) <= set("-: ") for c in cells):
+            continue
+        rows.append(cells)
+    return rows
+def _candidate_cap(brief_frontmatter: dict) -> int:
+    raw = brief_frontmatter.get("candidate-cap")
+    if raw is None:
+        return DEFAULT_CANDIDATE_CAP
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return DEFAULT_CANDIDATE_CAP
+def _scope_subset(
+    candidate_scope_csv: str,
+    scan_scope: list[str],
+    out_of_scope: list[str],
+) -> tuple[bool, str]:
+    paths = [p.strip() for p in candidate_scope_csv.split(",") if p.strip()]
+    if not paths:
+        return False, "empty Scope"
+    for p in paths:
+        if any(p == s or p.startswith(s.rstrip("/") + "/") for s in scan_scope):
+            for o in out_of_scope:
+                if p == o or p.startswith(o.rstrip("/") + "/"):
+                    return False, f"Scope '{p}' is inside out-of-scope '{o}'"
+            continue
+        return False, f"Scope '{p}' is outside brief scan-scope {scan_scope}"
+    return True, ""
+def _check_grilling_log(run_dir: Path, errors: list[str]) -> None:
+    """Item 10 — phase-1.5-grilling.md must exist with resolved blocks."""
+    grilling = run_dir / "state" / "phase-1.5-grilling.md"
+    if not grilling.exists():
+        errors.append("missing phase-1.5-grilling.md log at runs/.../state/")
+        return
+    gtext = grilling.read_text(encoding="utf-8")
+    if "Resolved scope" not in gtext:
+        errors.append("phase-1.5-grilling.md missing 'Resolved scope' block")
+    if "Resolved lenses" not in gtext:
+        errors.append("phase-1.5-grilling.md missing 'Resolved lenses' block")
+def _check_candidates_cap(
+    data_row_count: int, brief_frontmatter: dict, errors: list[str]
+) -> int | None:
+    """Item 5 — validate candidate-cap range and row count vs cap.
+    Returns the validated cap, or None when the cap itself is out of range
+    (in that case the caller must NOT also flag row-count-exceeds-cap).
+    """
+    cap = _candidate_cap(brief_frontmatter)
+    if cap < 1 or cap > ABSOLUTE_CANDIDATE_CAP:
+        errors.append(
+            f"brief candidate-cap {cap} out of allowed range 1..{ABSOLUTE_CANDIDATE_CAP}"
+        )
+        return None
+    if data_row_count > cap:
+        errors.append(f"row count {data_row_count} exceeds candidate-cap {cap}")
+    return cap
+def _check_row_sources_and_consensus(
+    idx: int,
+    source_workers: str,
+    consensus: str,
+    errors: list[str],
+) -> None:
+    """Item 6 + Consensus enum + single-source → worker-unique invariant."""
+    workers_in_row: list[str] = []
+    for token in source_workers.split(","):
+        token = token.strip()
+        if not token:
+            continue
+        m = _SOURCE_WORKER_RE.match(token)
+        if not m:
+            errors.append(f"row {idx}: Source workers token '{token}' must match <worker>:<id>")
+            continue
+        worker, _item = m.group(1), m.group(2)
+        if worker not in SOURCE_WORKERS:
+            errors.append(
+                f"row {idx}: Source workers '{worker}' is not in {SOURCE_WORKERS} (report-writer excluded)"
+            )
+        workers_in_row.append(worker)
+    if not workers_in_row:
+        errors.append(f"row {idx}: Source workers cell is empty")
+    if consensus not in _CONSENSUS_VALUES:
+        errors.append(f"row {idx}: Consensus '{consensus}' must be one of {_CONSENSUS_VALUES}")
+    if len(set(workers_in_row)) == 1 and consensus != "worker-unique":
+        errors.append(f"row {idx}: single-source-worker entries must use Consensus=worker-unique")
+def _check_candidate_row(
+    idx: int,
+    row: list[str],
+    scan_scope: list[str],
+    out_of_scope: list[str],
+    seen_ids: set[str],
+    errors: list[str],
+) -> None:
+    """Items 2, 3, 4, 6, 7 — validate a single candidate row."""
+    if len(row) != 10:
+        errors.append(f"row {idx} has {len(row)} columns, expected 10")
+        return
+    cand_id, lens_cell, _title, scope, _sev, _eff, consensus, source_workers, next_phase, _evidence = row
+    if not _CAND_ID_RE.match(cand_id):
+        errors.append(f"row {idx}: Cand ID '{cand_id}' must match I-NNN")
+        return
+    if cand_id in seen_ids:
+        errors.append(f"row {idx}: duplicate Cand ID '{cand_id}'")
+    seen_ids.add(cand_id)
+    lenses_in_row = [ln.strip() for ln in lens_cell.split(",") if ln.strip()]
+    for ln in lenses_in_row:
+        if ln not in LENSES:
+            errors.append(f"row {idx}: Lens '{ln}' is not in whitelist {LENSES}")
+    if not (1 <= len(lenses_in_row) <= 2):
+        errors.append(f"row {idx}: Lens cell must contain 1 or 2 values, got {len(lenses_in_row)}")
+    ok, reason = _scope_subset(scope, scan_scope, out_of_scope)
+    if not ok:
+        errors.append(f"row {idx}: {reason}")
+    _check_row_sources_and_consensus(idx, source_workers, consensus, errors)
+    if next_phase not in _NEXT_PHASES:
+        errors.append(f"row {idx}: Recommended next-phase '{next_phase}' must be one of {_NEXT_PHASES}")
+def _check_candidate_rows(
+    data_rows: list[list[str]],
+    scan_scope: list[str],
+    out_of_scope: list[str],
+    errors: list[str],
+) -> None:
+    """Items 2..7 — iterate over all data rows, accumulating seen IDs."""
+    seen_ids: set[str] = set()
+    for idx, row in enumerate(data_rows, start=1):
+        _check_candidate_row(idx, row, scan_scope, out_of_scope, seen_ids, errors)
+def _check_candidates_table(
+    body: str, brief_frontmatter: dict, errors: list[str]
+) -> None:
+    """Items 1–7 coordinator — parse table, check header, delegate cap and rows."""
+    rows = _read_section_table(body, "4.9 Improvement Candidates")
+    if not rows:
+        errors.append("missing or empty `## 4.9 Improvement Candidates` table")
+        return
+    header, *data = rows
+    expected_columns = [
+        "Cand ID", "Lens", "Title", "Scope", "Severity", "Effort",
+        "Consensus", "Source workers", "Recommended next-phase", "Evidence",
+    ]
+    if header != expected_columns:
+        errors.append(
+            f"`## 4.9 Improvement Candidates` header must be {expected_columns}, "
+            f"got {header}"
+        )
+    _check_candidates_cap(len(data), brief_frontmatter, errors)
+    scan_scope = brief_frontmatter.get("scan-scope") or []
+    out_of_scope = brief_frontmatter.get("out-of-scope") or []
+    _check_candidate_rows(data, scan_scope, out_of_scope, errors)
+def _check_final_verdict(
+    body: str, errors: list[str]
+) -> list[list[str]]:
+    """Item 8 — ## 2. Final Verdict verdict token is in enum.
+    Returns the parsed final_verdict_rows (empty list when absent).
+    """
+    final_verdict_rows = _read_section_table(body, "2. Final Verdict")
+    if not final_verdict_rows:
+        errors.append("missing `## 2. Final Verdict` block")
+        return []
+    token_cell = final_verdict_rows[-1][0] if final_verdict_rows[-1] else ""
+    if token_cell not in _VERDICT_TOKENS:
+        errors.append(
+            f"`## 2. Final Verdict` Verdict Token '{token_cell}' must be one of {_VERDICT_TOKENS}"
+        )
+    return final_verdict_rows
+def _check_verdict_card(
+    body: str, final_verdict_rows: list[list[str]], errors: list[str]
+) -> None:
+    """Item 9 — Verdict Card must be present and byte-match Final Verdict row."""
+    verdict_card_rows = _read_section_table(body, "Verdict Card")
+    if not verdict_card_rows:
+        errors.append("missing `## Verdict Card` block")
+        return
+    if final_verdict_rows and verdict_card_rows[-1] != final_verdict_rows[-1]:
+        errors.append("Verdict Card row must byte-match `## 2. Final Verdict` row")
+def validate_improvement_report(
+    report_path: Path, run_dir: Path, brief_frontmatter: dict
+) -> ValidationResult:
+    errors: list[str] = []
+    if not report_path.exists():
+        errors.append(f"report file not found: {report_path}")
+        return ValidationResult(ok=False, errors=errors)
+    body = report_path.read_text(encoding="utf-8")
+    _check_grilling_log(run_dir, errors)
+    _check_candidates_table(body, brief_frontmatter, errors)
+    final_verdict_rows = _check_final_verdict(body, errors)
+    _check_verdict_card(body, final_verdict_rows, errors)
+    return ValidationResult(ok=not errors, errors=errors)

package/src/config.mjs CHANGED Viewed

@@ -16,6 +16,11 @@ Supported keys (CLI alias -> JSON field):
                        Path may be absolute, ~/-prefixed, or (project scope
                        only) relative to <project-root>.
+  report-language    -> reportLanguage
+                       Final-report language. One of: en, ko, auto.
+                       'auto' is resolved by the report-writer lead from
+                       the task brief at run time.
 Usage:
   okstra config get <key> [--scope project|global|all]
       Print the value at the requested scope.
@@ -63,6 +68,19 @@ const KEYS = {
       return null;
     },
   },
+  "report-language": {
+    jsonField: "reportLanguage",
+    scopes: ["project", "global"],
+    validate(value) {
+      const allowed = new Set(["en", "ko", "auto"]);
+      if (typeof value !== "string" || !allowed.has(value)) {
+        return (
+          `value must be one of: en, ko, auto (got ${JSON.stringify(value)})`
+        );
+      }
+      return null;
+    },
+  },
 };
 function parseArgs(args) {