okstra 0.54.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"}
 
@@ -616,6 +625,19 @@ def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
 # a section heading line (not as inline text inside a paragraph or table).
 _VERDICT_CARD_HEADING_RE = re.compile(r"^##[ \t]+Verdict Card\b", re.MULTILINE)
 
+# Top-of-report Index block. The renderer
+# (scripts/okstra_ctl/render_final_report.py) injects `<a id="report-index">`
+# into the index heading; a missing anchor means the markdown was produced
+# outside the renderer or hand-edited. Language-independent (the heading text
+# itself is localized "Index" / "목차").
+_REPORT_INDEX_ANCHOR_RE = re.compile(r'<a id="report-index"')
+
+# An ID-defining table row: `| **FU-001**…` or `| C-001 |`. After the
+# renderer's anchor pass the leading token becomes `<a id="…">…`, so a row
+# still matching this (ID is the bare leading token) is one the renderer
+# never anchored — i.e. an un-anchored ID that the Index cannot link to.
+_UNANCHORED_ID_ROW_RE = re.compile(r"^\|[ \t]*\*{0,2}([A-Z]{1,4}-\d{3,})\b", re.MULTILINE)
+
 # Reading Confirmation heading must NOT appear in the final-report — it
 # belongs in the worker audit sidecar (`<worker>-audit-<task-type>-<seq>.md`).
 _READING_CONFIRMATION_HEADING_RE = re.compile(
@@ -687,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:
@@ -723,6 +823,32 @@ def validate_report(
             "the corresponding cells in `## 7. Final Verdict` and `## 3.` first item."
         )
 
+    # Top-of-report Index (목차 / Index) is mandatory in every final-report so
+    # the reader can jump to any section / tracked ID. Schema task-types get it
+    # from render_final_report.py; `improvement-discovery` (authored free-form)
+    # gets it from the `okstra-inject-report-index.py` post-step. A missing
+    # index anchor means that injection never ran.
+    if _REPORT_INDEX_ANCHOR_RE.search(content) is None:
+        failures.append(
+            "final report is missing the top-of-report Index block "
+            '(`## Index` / `## 목차` carrying `<a id="report-index">`). It is '
+            "injected by scripts/okstra_ctl/render_final_report.py (schema "
+            "task-types) or scripts/okstra-inject-report-index.py "
+            "(improvement-discovery); a missing index means that step never ran."
+        )
+
+    # Every ID-defining table row (FU-/E-/S-/C-/R-/I-/… in the first cell) must
+    # carry a scroll anchor so the Index can link to it. A row still matching
+    # the bare-leading-token shape is one the injector never anchored.
+    for match in _UNANCHORED_ID_ROW_RE.finditer(content):
+        failures.append(
+            f"final report has an ID-defining table row for `{match.group(1)}` "
+            'without a scroll anchor (`<a id="…">`). IDs must be anchored so the '
+            "top-of-report Index can link to them — run the index injector "
+            "(render_final_report.py / okstra-inject-report-index.py) instead of "
+            "hand-editing."
+        )
+
     # Reading Confirmation belongs in the worker audit sidecar, not the
     # user-facing final-report.
     if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
@@ -1870,14 +1996,23 @@ def main() -> int:
     # data.json is well-formed, the rendered markdown is guaranteed to
     # contain every required section. Substring checks below are a
     # safety net for hand-edited or pre-v1.0 reports.
+    task_type = effective_run_task_type(run_manifest, task_manifest)
     validate_final_report_data(report_path, failures)
     validate_report(report_path, contract["required_agent_status_entries"], failures)
     validate_team_state_usage(team_state, failures)
 
-    task_type = effective_run_task_type(run_manifest, task_manifest)
     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/runtime/validators/validate_improvement_report.py

@@ -30,6 +30,10 @@ _NEXT_PHASES = ("requirements-discovery", "implementation-planning", "error-anal
 _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")
+# The index/anchor post-pass (okstra-inject-report-index.py) injects an empty
+# scroll anchor into ID-defining first cells (`<a id="i-001"></a>I-001`). Strip
+# it during cell normalization so `_CAND_ID_RE` still matches the bare `I-NNN`.
+_CELL_ANCHOR_RE = re.compile(r'<a id="[^"]*"></a>')
 
 
 @dataclass
@@ -53,7 +57,7 @@ def _read_section_table(body: str, heading: str) -> list[list[str]]:
         s = line.strip()
         if not s.startswith("|") or not s.endswith("|"):
             continue
-        cells = [c.strip() for c in s.strip("|").split("|")]
+        cells = [_CELL_ANCHOR_RE.sub("", c).strip() for c in s.strip("|").split("|")]
         if all(set(c) <= set("-: ") for c in cells):
             continue
         rows.append(cells)

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;
-}