okstra 0.55.0 → 0.56.1

package/runtime/templates/reports/implementation-planning-input.template.md

@@ -89,12 +89,12 @@ The final report of an `implementation-planning` run MUST contain every section
 1. **Option Candidates** — at least two viable options, each with the exact list of files to create or modify and the principal change per file.
 2. **Trade-off Matrix** — comparison of the candidates across complexity, risk, reversibility, performance impact, scope, and required test surface.
 3. **Recommended Option** — selected option with explicit rationale referencing the trade-off matrix.
-4. **Stepwise Execution Order** — ordered steps where each step is independently verifiable; each step lists the files it touches and the test/command that proves it works.
+4. **Stage Map** — `## 5.5 Stage Map` plus one `## 5.5.<i> Stage <i>:` section per stage. Each stage is a thin vertical slice with `Slice value:`, `Acceptance:`, `Conformance tests:` or `Conformance exemption:`, the four required subsections, and a RED/GREEN step order unless a `TDD exemption:` line applies.
 5. **Dependency and Migration Risk** — schema, data, ordering, feature-flag, and cross-service risks that the recommended option introduces.
 6. **Validation Checklist** — pre-execution, mid-execution, and post-execution checks (commands, expected outputs, observability points).
 7. **Rollback Strategy** — exact reverse procedure or compensating action for each significant step.
 8. **Scope Boundary** — an explicit list of adjacent areas, files, refactors, or quality improvements that this plan **does NOT** cover, each with a one-line reason (deferred, separate owner, separate decision, out of requirement). Any item the analysers were tempted to fold in but chose to exclude MUST appear here. An empty list is allowed only when the analysers explicitly state "no adjacent expansion was considered" — silence is not acceptable.
-9. **User Approval Request** — a labelled block stating that the plan is awaiting explicit user approval. The next `implementation` run MUST NOT begin until the user has replied with explicit approval to this block.
+9. **Approval frontmatter** — the final report's YAML frontmatter MUST emit `approved: false` and `implementation-option:`. Do NOT create a `User Approval Request` body block; the next `implementation` run reads only the frontmatter gate.
 
 ## Phase Boundary
 
@@ -108,7 +108,7 @@ The final report of an `implementation-planning` run MUST contain every section
 
 ## Stage Output Shape (reference)
 
-This run's final report MUST emit `## 5.5 Stage Map` and `## 5.5.<i> Stage <i>` sections per the implementation-planning profile §"Required deliverable shape". Two illustrative shapes:
+This run's final report MUST emit `## 5.5 Stage Map` and `## 5.5.<i> Stage <i>` sections per the implementation-planning profile §"Required deliverable shape". Two illustrative Stage Map tables:
 
 ### Shape A — single stage (small work)
 | stage | title | depends-on | step-count | exit-contract-summary |

package/runtime/validators/validate-implementation-plan-stages.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""S1–S10 checks for the Stage Map structure of an approved
+"""S1–S11 checks for the Stage Map structure of an approved
 implementation-planning final-report.md. Run from prepare_task_bundle
 of `implementation` task or standalone."""
 
@@ -40,7 +40,7 @@ class StageMeta:
 
 @dataclass
 class ValidationError:
-    code: str   # S1..S10
+    code: str   # S1..S11
     stage: int  # 0 = global
     message: str
 
@@ -168,6 +168,8 @@ def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[Valida
 SLICE_VALUE = re.compile(r"^\s*Slice value\s*:\s*(.+?)\s*$", re.M)
 ACCEPTANCE = re.compile(r"^\s*Acceptance\s*:\s*(.+?)\s*$", re.M)
 TDD_EXEMPTION = re.compile(r"^\s*TDD exemption\s*:\s*\S", re.M)
+CONFORMANCE_TESTS = re.compile(r"^\s*Conformance tests\s*:\s*\S", re.M)
+CONFORMANCE_EXEMPTION = re.compile(r"^\s*Conformance exemption\s*:\s*\S", re.M)
 
 
 def _check_slice_tdd(text: str, stages: List[StageMeta]) -> List[ValidationError]:
@@ -204,6 +206,28 @@ def _check_slice_tdd(text: str, stages: List[StageMeta]) -> List[ValidationError
     return errs
 
 
+def _check_conformance_declaration(
+    text: str, stages: List[StageMeta]
+) -> List[ValidationError]:
+    """S11: 각 stage 는 conformance 검증을 선언하거나 명시적으로 면제한다.
+
+    S11 — `Conformance tests:` 라인(Tier3 검증 스크립트 선언) 또는
+          `Conformance exemption:` 라인(테스트 불필요 사유) 중 하나 필수.
+    diff 가 db/io/http surface 를 건드렸는데 아무 선언이 없는 silent-pass(DEV-9184)
+    를 planning boundary 에서 차단한다.
+    """
+    errs: List[ValidationError] = []
+    for s in stages:
+        section = _slice_stage_section(text, s.stage_number)
+        if not (CONFORMANCE_TESTS.search(section) or CONFORMANCE_EXEMPTION.search(section)):
+            errs.append(ValidationError(
+                "S11", s.stage_number,
+                "S11: stage must declare 'Conformance tests:' (Tier3 검증 스크립트) "
+                "or 'Conformance exemption:' (사유) — stage conformance QA design §12.2",
+            ))
+    return errs
+
+
 def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
     errs: List[ValidationError] = []
     valid = {s.stage_number for s in stages}
@@ -274,7 +298,7 @@ def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[Validatio
 
 
 def collect_validation_errors(text: str) -> List[ValidationError]:
-    """All S1–S10 checks against the report text; empty list means valid.
+    """All S1–S11 checks against the report text; empty list means valid.
 
     S1 (missing `## 5.5 Stage Map` heading) makes the rest unparseable, so it
     short-circuits. Shared by `main()` (CLI / implementation entry) and the
@@ -290,6 +314,7 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
         errors.extend(_check_slice_tdd(text, stages))
+        errors.extend(_check_conformance_declaration(text, stages))
         errors.extend(_check_depends_on(stages))
         errors.extend(_check_parallel_safety(text, stages))
     return errors

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:
@@ -904,6 +991,7 @@ PLANNING_REQUIRED_SECTIONS = (
     "Option Candidates",
     "Trade-off",
     "Recommended Option",
+    "Stage Map",
     "Stepwise Execution Order",
     "Dependency",
     "Validation Checklist",
@@ -918,6 +1006,7 @@ IMPLEMENTATION_REQUIRED_SECTIONS = (
     "Commit List",
     "Diff Summary",
     "Out-of-plan Edits",
+    "Stage Sidecar Evidence",
     "Validation Evidence",
     "Verifier Results",
     "Rollback Verification",
@@ -1917,6 +2006,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;
-}