okstra 0.67.0 → 0.68.0

package/runtime/validators/validate-run.py

@@ -748,6 +748,36 @@ def _parse_diff_summary_files(content: str) -> list[str]:
     return _DIFF_ROW_PATH_RE.findall(section.group(0))
 
 
+_STAGE_RUN_DIR_RE = re.compile(r"^stage-\d+$")
+
+
+def _implementation_stage_name(run_dir: Path) -> str | None:
+    """implementation stage 격리 run(`runs/implementation/stage-<N>`)이면
+    `stage-<N>` 을 반환. 그 외(final-verification 등 task-type 레벨 run)는
+    None — whole-task 스코프."""
+    if run_dir.parent.name == "implementation" and _STAGE_RUN_DIR_RE.match(run_dir.name):
+        return run_dir.name
+    return None
+
+
+def _scope_manifest_entries(manifest: dict, stage_name: str | None) -> dict:
+    """게이트 평가 대상 entry 를 run 스코프로 좁힌 manifest 를 반환.
+
+    implementation 은 한 run = 한 stage 이므로 자기 stageKey
+    (`<task-id>-stage-<N>`) entry 만 게이트한다 — 다른 stage 는 각자의
+    implementation run / final-verification(whole-task) 이 검증한다.
+    suffix 매칭인 이유: stageKey 의 `<task-id>` 는 planning 이 쓴 원문이라
+    task 디렉터리 segment 와 표기가 다를 수 있다.
+    """
+    if stage_name is None:
+        return manifest
+    entries = [
+        e for e in manifest.get("entries", [])
+        if isinstance(e, dict) and str(e.get("stageKey", "")).endswith(f"-{stage_name}")
+    ]
+    return {"entries": entries}
+
+
 def _task_root_from_run_dir(run_dir: Path) -> Path:
     """run_dir 에서 `runs` 디렉터리를 앵커로 task_root 를 복원한다.
 
@@ -770,6 +800,12 @@ def _validate_conformance(report_path: Path, failures: list[str],
     가 없다는 뜻 — 선언을 강제하는 것은 planning 계약(Phase 4)의 몫). 매니페스트가
     있으면 결과 사이드카와 함께 evaluate_conformance 로 판정하고 BLOCKING verdict
     를 run 검증 실패로 승격한다. WAIVED(conditional)/EXEMPT 는 통과시킨다.
+
+    게이트 스코프: implementation stage 격리 run 은 자기 stage entry 만(결과
+    게이트·diff-surface 교차검증 모두 — 미래 stage 의 미실행이 현재 run 을
+    막으면 안 된다), final-verification 등 task-type 레벨 run 은 전 entry
+    (whole-task). prompts/profiles/_implementation-verifier.md §Tier 3 /
+    final-verification.md 의 스코프 계약과 동형.
     """
     # conformance 산출물은 task-level(<task_root>/qa)에 있어 planning/
     # implementation/final-verification 가 공유한다. report_path 는
@@ -792,8 +828,9 @@ def _validate_conformance(report_path: Path, failures: list[str],
     if schema_errors:
         failures.extend(f"conformance manifest: {e}" for e in schema_errors)
         return
-    results = _load_conformance_results(qa_dir, manifest)
-    for verdict in evaluate_conformance(manifest, results):
+    scoped = _scope_manifest_entries(manifest, _implementation_stage_name(run_dir))
+    results = _load_conformance_results(qa_dir, scoped)
+    for verdict in evaluate_conformance(scoped, results):
         if not verdict.ok:
             failures.append(
                 f"conformance gate BLOCKING for stage {verdict.stage_key}: "
@@ -803,13 +840,14 @@ def _validate_conformance(report_path: Path, failures: list[str],
             )
     changed_files = _parse_diff_summary_files(report_path.read_text(encoding="utf-8"))
     if changed_files:
-        uncovered = detect_surfaces(changed_files, surface_patterns) - manifest_required_surfaces(manifest)
+        uncovered = detect_surfaces(changed_files, surface_patterns) - manifest_required_surfaces(scoped)
         if uncovered:
             failures.append(
                 "conformance gate BLOCKING: implementation diff touches undeclared "
-                f"surface(s) {sorted(uncovered)} — no stage declares `requires` for "
-                "them. Declare a conformance entry (requires=[...]) for the touching "
-                "stage, or an explicit exemption. (silent mock-green 방지 — DEV-9184)"
+                f"surface(s) {sorted(uncovered)} — no in-scope stage declares "
+                "`requires` for them. Declare a conformance entry (requires=[...]) "
+                "for the touching stage, or an explicit exemption. "
+                "(silent mock-green 방지 — DEV-9184)"
             )
 
 
@@ -1399,11 +1437,13 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             f"final-verification: verificationScope must be `whole-task` or "
             f"`single-stage`, got {scope!r}."
         )
-    if scope == "single-stage" and "release-handoff" in routing:
+    if (scope == "single-stage" and "release-handoff" in routing
+            and "release-handoff(stage-group)" not in routing):
         failures.append(
             "final-verification: verificationScope `single-stage` cannot recommend "
-            "release-handoff routing — single-stage is a partial verification and "
-            "release-handoff requires whole-task verification."
+            "plain release-handoff routing — a single-stage accepted verdict may "
+            "only route to `release-handoff(stage-group)` (partial-PR mode); "
+            "whole-task release-handoff requires whole-task verification."
         )
 
 

package/src/git-reconcile.mjs

@@ -0,0 +1,31 @@
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra git-reconcile — okstra 밖 git 히스토리 변경 후 기록 화해
+
+A thin shim over \`python3 -m okstra_ctl.git_reconcile\`. 기본은 검사:
+stale 항목을 JSON 으로 출력하고, confirm 항목이 남으면 exit 2.
+patch-id 로 내용 동일성이 증명되는 항목(auto)은 --apply 로 일괄 보정되고,
+내용이 바뀐 항목(confirm)은 --stage/--use-ref 로만 보정된다.
+
+Usage:
+  okstra git-reconcile --plan-run-root <dir> --project-id <id> \\
+    --task-group <g> --task-id <t> --work-category <c> \\
+    [--apply] [--stage <N> --use-ref <ref>] [--reset-anchor <ref>] [--json]
+
+Exit codes:
+  0  stale 없음 또는 보정 완료
+  2  confirm 항목 잔존 (check: 확인 필요 / apply: 일부 미보정)
+  1  error (resolve 실패 등)
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.git_reconcile",
+    args,
+  });
+  return code ?? 1;
+}

package/src/handoff.mjs

@@ -0,0 +1,30 @@
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra handoff — release-handoff stage-group 보조 (자격/수집/기록)
+
+A thin shim over \`python3 -m okstra_ctl.handoff\`. JSON 출력.
+
+Usage:
+  okstra handoff eligible --plan-run-root <dir> --approved-plan <md>
+  okstra handoff assemble --plan-run-root <dir> --approved-plan <md> \\
+    --project-root <dir> --project-id <id> --task-group <g> --task-id <t> \\
+    --work-category <c> --stages 2,3 --base <branch>
+  okstra handoff record-verified --plan-run-root <dir> --stage <N> \\
+    --report-path <md> --data-json <json>
+  okstra handoff record-pr --plan-run-root <dir> --stages 2,3 \\
+    --branch <b> --url <u>
+
+Exit codes: 0 ok / 1 자격·전제 위반 / 2 stage 간 merge 충돌(conflicts 동봉)
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.handoff",
+    args,
+  });
+  return code ?? 1;
+}