okstra 0.55.0 → 0.56.0

package/runtime/validators/validate-run.py

@@ -30,8 +30,17 @@ except ImportError:  # pragma: no cover — runtime guarantees this import
     load_schema = None  # type: ignore[assignment]
     schema_validate = None  # type: ignore[assignment]
 
+from okstra_project import project_json_path  # noqa: E402
 from okstra_project.dirs import tasks_root as _okstra_tasks_root  # noqa: E402
 
+from okstra_ctl.conformance import (  # noqa: E402
+    detect_surfaces,
+    evaluate_conformance,
+    manifest_required_surfaces,
+    qa_result_from_dict,
+    validate_conformance_manifest,
+)
+
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
 
@@ -700,6 +709,84 @@ _DEPRECATED_FINAL_REPORT_PATTERNS: tuple[tuple[re.Pattern, str], ...] = (
 )
 
 
+def _load_conformance_results(qa_dir: Path, manifest: dict) -> dict:
+    """매니페스트 각 entry 에 대응하는 `result-<stageKey>.json` 을 로드.
+    파일 부재/파손은 키를 비워 둬 미실행(None→BLOCKING)으로 흐르게 한다."""
+    results: dict = {}
+    for entry in manifest.get("entries", []):
+        key = entry.get("stageKey") if isinstance(entry, dict) else None
+        if not isinstance(key, str) or not key:
+            continue
+        sidecar = qa_dir / f"result-{key}.json"
+        if not sidecar.is_file():
+            continue
+        try:
+            results[key] = qa_result_from_dict(json.loads(sidecar.read_text()))
+        except (OSError, json.JSONDecodeError):
+            results[key] = qa_result_from_dict(None)  # → MISSING → BLOCKING
+    return results
+
+
+_DIFF_SUMMARY_RE = re.compile(r"^###\s+5\.7\.3\b.*?(?=^###\s|\Z)", re.MULTILINE | re.DOTALL)
+_DIFF_ROW_PATH_RE = re.compile(r"^\|\s*`([^`]+)`\s*\|", re.MULTILINE)
+
+
+def _parse_diff_summary_files(content: str) -> list[str]:
+    """implementation 리포트 §5.7.3 Diff Summary 표의 첫 셀(백틱 경로)들을 추출."""
+    section = _DIFF_SUMMARY_RE.search(content)
+    if section is None:
+        return []
+    return _DIFF_ROW_PATH_RE.findall(section.group(0))
+
+
+def _validate_conformance(report_path: Path, failures: list[str],
+                          surface_patterns: object = None) -> None:
+    """Tier 3 conformance 게이트(implementation / final-verification).
+
+    `<task_root>/qa/conformance-manifest.json` 이 없으면 inert(선언된 conformance
+    가 없다는 뜻 — 선언을 강제하는 것은 planning 계약(Phase 4)의 몫). 매니페스트가
+    있으면 결과 사이드카와 함께 evaluate_conformance 로 판정하고 BLOCKING verdict
+    를 run 검증 실패로 승격한다. WAIVED(conditional)/EXEMPT 는 통과시킨다.
+    """
+    # conformance 산출물은 task-level(<task_root>/qa)에 있어 planning/
+    # implementation/final-verification 가 공유한다. report_path 는
+    # task_root/runs/<task-type>/reports/final-report.md 이므로 task_root 는
+    # run_dir(=report_path.parent.parent)에서 두 단계 위.
+    run_dir = report_path.parent.parent
+    qa_dir = run_dir.parent.parent / "qa"
+    manifest_path = qa_dir / "conformance-manifest.json"
+    if not manifest_path.is_file():
+        return
+    try:
+        manifest = json.loads(manifest_path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        failures.append(f"conformance manifest unreadable at {manifest_path}: {exc}")
+        return
+    schema_errors = validate_conformance_manifest(manifest)
+    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):
+        if not verdict.ok:
+            failures.append(
+                f"conformance gate BLOCKING for stage {verdict.stage_key}: "
+                f"{verdict.message}. Run the stage's conformance script (or declare "
+                f"an exemption / user waiver) — see "
+                f"docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md."
+            )
+    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)
+        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)"
+            )
+
+
 def validate_report(
     report_path: Path, required_agent_status_entries: list[str], failures: list[str]
 ) -> None:
@@ -1917,6 +2004,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 in ("implementation", "final-verification"):
+        _sp = None
+        _pj = project_json_path(project_root)
+        if _pj.is_file():
+            try:
+                _sp = (json.loads(_pj.read_text()).get("qaEnv") or {}).get("surfacePatterns")
+            except (OSError, json.JSONDecodeError):
+                _sp = None
+        _validate_conformance(report_path, failures, surface_patterns=_sp)
     if task_type == "improvement-discovery":
         brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
         brief_path = (

package/src/okstra-dirs.mjs

@@ -15,7 +15,7 @@ export const OKSTRA_DIR = ".okstra";
 // Pre-v0.37 layout. `okstra migrate` reads this to find unmigrated projects.
 // 코드 path 빌드에는 절대 사용 금지 — `OKSTRA_DIR` 만. 오로지 migration
 // 탐지/안내 메시지 용도.
-export const LEGACY_OKSTRA_DIR = ".project-docs/okstra";
+export const LEGACY_OKSTRA_DIR = "./okstra";
 
 export function okstraRoot(projectRoot) {
   return join(projectRoot, OKSTRA_DIR);

package/src/migrate.mjs

@@ -1,146 +0,0 @@
-import { buildPythonpath, resolvePaths } from "./paths.mjs";
-import { LEGACY_OKSTRA_DIR, OKSTRA_DIR } from "./okstra-dirs.mjs";
-import { runProcess } from "./_proc.mjs";
-
-const USAGE = `okstra migrate — move project artifacts from ${LEGACY_OKSTRA_DIR}/ to ${OKSTRA_DIR}/
-
-Run this once per project that was set up before v0.37. The migrator moves
-the okstra-managed directory tree, rewrites the import line in your
-project's CLAUDE.md, updates .gitignore, and refreshes okstra-home
-registries (~/.okstra/{recent,active}.jsonl, ~/.okstra/worktrees/registry.json)
-so the existing run history keeps resolving to the new path.
-
-Usage:
-  okstra migrate                Dry-run by default. Prints the plan as JSON.
-  okstra migrate --apply        Execute the move and ancillary updates.
-  okstra migrate --cwd <dir>    Search starting point (default: cwd).
-  okstra migrate --quiet        Suppress stdout on success; exit code reports.
-
-Exit codes:
-  0   plan prepared (dry-run) or migration applied successfully
-  1   pre-condition rejected (e.g. ${OKSTRA_DIR}/ already exists, or no
-      ${LEGACY_OKSTRA_DIR}/ to migrate); reason printed on stderr
-  2   internal error (python invocation failed, etc.)
-
-The command is idempotent in spirit: re-running after a successful apply
-exits 1 with "nothing to migrate". Safe to wire into CI as a one-shot
-post-upgrade step.
-`;
-
-function parseArgs(args) {
-  const opts = { cwd: process.cwd(), apply: false, quiet: false };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--apply") opts.apply = true;
-    else if (a === "--quiet" || a === "-q") opts.quiet = true;
-    else if (a === "--cwd") {
-      const next = args[i + 1];
-      if (!next || next.startsWith("--")) throw new Error("--cwd requires a path");
-      opts.cwd = next;
-      i++;
-    } else {
-      throw new Error(`unknown argument '${a}'`);
-    }
-  }
-  return opts;
-}
-
-function emit(opts, payload) {
-  if (opts.quiet) return;
-  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-}
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-
-  let opts;
-  try {
-    opts = parseArgs(args);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
-    return 2;
-  }
-
-  const paths = await resolvePaths();
-
-  // We resolve project root via the python resolver — the same one used by
-  // every other okstra command — to keep "what project this is" consistent
-  // across CLI surfaces. The resolver knows three lookup strategies; the
-  // migrator only needs whichever ancestor it returns.
-  const py = await runProcess(
-    "python3",
-    [
-      "-c",
-      [
-        "import json, sys",
-        "from pathlib import Path",
-        "from okstra_project.resolver import resolve_project_root, ResolverError",
-        "from okstra_ctl.migrate import (",
-        "    prepare_migration_plan, apply_migration_plan, MigrationRefused,",
-        ")",
-        "cwd, apply = sys.argv[1], sys.argv[2] == 'apply'",
-        "try:",
-        "    # Resolver requires .okstra/project.json by default; for migrate",
-        "    # we fall back to the cwd directly because the legacy layout has",
-        "    # no .okstra/project.json yet.",
-        "    try:",
-        "        pr = resolve_project_root(explicit_root='', cwd=cwd)",
-        "    except ResolverError:",
-        "        pr = Path(cwd).resolve()",
-        "    plan = prepare_migration_plan(pr)",
-        "    if apply:",
-        "        result = apply_migration_plan(plan, dry_run=False)",
-        "    else:",
-        "        result = apply_migration_plan(plan, dry_run=True)",
-        "    print('OK')",
-        "    print(json.dumps({'plan': plan.to_dict(), 'result': result.to_dict()}, ensure_ascii=False))",
-        "except MigrationRefused as e:",
-        "    print('REFUSED')",
-        "    print(str(e))",
-        "    sys.exit(1)",
-      ].join("\n"),
-      opts.cwd,
-      opts.apply ? "apply" : "dry",
-    ],
-    { PYTHONPATH: buildPythonpath(paths) },
-  );
-
-  if (py.code === 1) {
-    // Refused — pre-condition fail. Stderr message already on second line.
-    const reason = py.stdout.split("\n").slice(1).join("\n").trim() || py.stderr.trim();
-    if (!opts.quiet) process.stderr.write(`migrate refused: ${reason}\n`);
-    return 1;
-  }
-  if (py.code !== 0) {
-    process.stderr.write(`error: python invocation failed: ${py.stderr.trim() || py.stdout.trim()}\n`);
-    return 2;
-  }
-
-  const lines = py.stdout.split("\n");
-  if (lines[0]?.trim() !== "OK") {
-    process.stderr.write(`error: unexpected python output: ${py.stdout}\n`);
-    return 2;
-  }
-  let payload;
-  try {
-    payload = JSON.parse(lines.slice(1).join("\n"));
-  } catch (err) {
-    process.stderr.write(`error: failed to parse python output: ${err.message}\n`);
-    return 2;
-  }
-
-  emit(opts, {
-    ok: true,
-    mode: opts.apply ? "apply" : "dry-run",
-    ...payload,
-  });
-  if (!opts.apply && !opts.quiet) {
-    process.stderr.write(
-      "\nNo changes written. Re-run with --apply to perform the migration.\n",
-    );
-  }
-  return 0;
-}