okstra 0.228.2 → 0.230.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 (124) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +179 -13
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +16 -21
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/bin/okstra-provider-exec.py +53 -4
  16. package/runtime/prompts/duties/code-reviewer.json +5 -2
  17. package/runtime/prompts/launch.template.md +5 -5
  18. package/runtime/prompts/lead/convergence.md +4 -4
  19. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  20. package/runtime/prompts/lead/phase-routing.md +1 -1
  21. package/runtime/prompts/lead/report-writer.md +3 -3
  22. package/runtime/prompts/lead/team-contract.md +3 -3
  23. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  24. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  25. package/runtime/python/okstra_ctl/cmux.py +4 -2
  26. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  27. package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
  28. package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
  29. package/runtime/python/okstra_ctl/code_review_target.py +79 -25
  30. package/runtime/python/okstra_ctl/conformance.py +61 -0
  31. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  32. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  33. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  34. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  35. package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
  36. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  37. package/runtime/python/okstra_ctl/ids.py +1 -41
  38. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  39. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  40. package/runtime/python/okstra_ctl/locks.py +28 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
  42. package/runtime/python/okstra_ctl/paths.py +84 -31
  43. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  44. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  46. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  47. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  48. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  50. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  51. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  53. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  55. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  57. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  58. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  59. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  62. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  63. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  66. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  67. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  68. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  69. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  70. package/runtime/python/okstra_ctl/process_group.py +26 -3
  71. package/runtime/python/okstra_ctl/qa_commands.py +7 -2
  72. package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
  73. package/runtime/python/okstra_ctl/recap.py +1 -2
  74. package/runtime/python/okstra_ctl/render.py +10 -2
  75. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  76. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  77. package/runtime/python/okstra_ctl/run.py +24 -20
  78. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  79. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  80. package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
  81. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  82. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  83. package/runtime/python/okstra_ctl/verification_generation.py +248 -0
  84. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  85. package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
  86. package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
  87. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  88. package/runtime/python/okstra_ctl/verification_target.py +20 -5
  89. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  90. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  91. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  92. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  93. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  94. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  95. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +84 -48
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
  99. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +6 -6
  101. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  102. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  103. package/runtime/validators/validate-run.py +118 -52
  104. package/docs/cli.md +0 -1060
  105. package/docs/container.md +0 -100
  106. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  107. package/docs/performance-improvement-plan-v2.md +0 -369
  108. package/runtime/python/okstra_ctl/container.py +0 -702
  109. package/runtime/python/okstra_ctl/rollup.py +0 -241
  110. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  111. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  112. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  113. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  114. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  115. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  116. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  117. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  118. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  119. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  120. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  121. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  122. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  123. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  124. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -181,7 +181,9 @@ from okstra_project.dirs import tasks_root as _okstra_tasks_root # noqa: E402
181
181
  from okstra_project.resolver import resolve_architecture # noqa: E402
182
182
 
183
183
  from okstra_ctl.conformance import (
184
+ conformance_entry_mismatches,
184
185
  conformance_result_file,
186
+ conformance_script_matches as _conformance_script_matches,
185
187
  detect_surfaces,
186
188
  evaluate_conformance,
187
189
  manifest_required_surfaces,
@@ -191,6 +193,11 @@ from okstra_ctl.conformance import (
191
193
  qa_result_from_dict,
192
194
  validate_conformance_manifest,
193
195
  )
196
+ from okstra_ctl.conformance_evidence import ( # noqa: E402
197
+ RunConformanceEvidence,
198
+ collect_conformance_evidence,
199
+ )
200
+ from okstra_ctl.verification_conformance import conformance_stage # noqa: E402
194
201
  from okstra_ctl.dispatch_state import ( # noqa: E402
195
202
  DispatchError,
196
203
  v2_worker_state_key,
@@ -1923,6 +1930,70 @@ def _load_conformance_results(qa_dir: Path, manifest: dict) -> dict:
1923
1930
  return results
1924
1931
 
1925
1932
 
1933
+ def _evidence_conformance_results(
1934
+ run_manifest_path: Path | None,
1935
+ project_root: Path | None,
1936
+ manifest: dict,
1937
+ scoped: dict,
1938
+ failures: list[str],
1939
+ ) -> tuple[dict, dict, dict[str, str]] | None:
1940
+ """Gated entries, results and unusable-record messages of a
1941
+ `verificationEvidenceVersion` run.
1942
+
1943
+ None for a run without that field, whose results stay the verifier-written
1944
+ sidecars. A marked run never reads a sidecar: a stage without an execution
1945
+ record has no result, and a stage whose latest records are no usable
1946
+ evidence is reported with those records instead of as never run.
1947
+ """
1948
+ if run_manifest_path is None or project_root is None:
1949
+ return None
1950
+ run_manifest = load_json(run_manifest_path)
1951
+ if "verificationEvidenceVersion" not in run_manifest:
1952
+ return None
1953
+ entries = [entry for entry in manifest.get("entries", []) if isinstance(entry, dict)]
1954
+ evidence = RunConformanceEvidence(frozenset(), {})
1955
+ if run_manifest["verificationEvidenceVersion"] != "1.0":
1956
+ failures.append(
1957
+ "conformance gate BLOCKING: unsupported verification evidence version "
1958
+ f"{run_manifest['verificationEvidenceVersion']!r} in {run_manifest_path}"
1959
+ )
1960
+ else:
1961
+ try:
1962
+ evidence = collect_conformance_evidence(
1963
+ project_root, run_manifest_path,
1964
+ [entry["stageKey"] for entry in entries],
1965
+ )
1966
+ except ValueError as exc:
1967
+ failures.append(
1968
+ "conformance gate BLOCKING: verification execution evidence "
1969
+ f"could not be collected for {run_manifest_path}: {exc}"
1970
+ )
1971
+ gated = list(scoped.get("entries", []))
1972
+ for entry in entries:
1973
+ if entry not in gated and _entry_stage(entry) in evidence.stages:
1974
+ gated.append(entry)
1975
+ results = {
1976
+ key: stage.result for key, stage in evidence.results.items()
1977
+ if stage.result is not None
1978
+ }
1979
+ unusable = {
1980
+ key: "no usable execution record: " + "; ".join(
1981
+ f"{path} ({reason})" for path, reason in stage.rejections.items())
1982
+ for key, stage in evidence.results.items()
1983
+ if stage.result is None and stage.rejections
1984
+ }
1985
+ return {"entries": gated}, results, unusable
1986
+
1987
+
1988
+ def _entry_stage(entry: dict) -> int | None:
1989
+ try:
1990
+ return conformance_stage(str(entry.get("stageKey")))
1991
+ except ValueError:
1992
+ # expected-miss: a stage key without a stage number names no stage a
1993
+ # generation can require; `_scope_manifest_entries` gates it by suffix.
1994
+ return None
1995
+
1996
+
1926
1997
  def _diff_summary_files(report_data: Mapping[str, Any]) -> list[str]:
1927
1998
  """implementation 리포트가 신고한 변경 파일 목록 (`implementation.diffSummary.files[].file`).
1928
1999
 
@@ -2210,27 +2281,6 @@ def _approved_plan_conformance_manifest(
2210
2281
  }
2211
2282
 
2212
2283
 
2213
- def _conformance_script_matches(actual: str, declared: str) -> bool:
2214
- """두 script 표기가 같은 파일을 가리키는지 판정한다.
2215
-
2216
- 1순위는 task-root 상대형끼리의 일치다. task_root 아래로 접히지 않는
2217
- 절대경로(예: 워크트리 경로로 적힌 선언)가 남으면, 남은 쪽이 다른 쪽을
2218
- 경로 경계에서 후행 일치하는지까지 본다 — `/…/wt/qa/scripts/s.ts` 와
2219
- `qa/scripts/s.ts` 는 같은 파일이다. 후행 일치는 경계(`/`)를 요구하므로
2220
- `renamed-stage-1.ts` 같은 다른 파일은 걸리지 않는다.
2221
- """
2222
- if actual == declared:
2223
- return True
2224
- if not actual or not declared:
2225
- return False
2226
- if actual.startswith("/") != declared.startswith("/"):
2227
- longer, shorter = (
2228
- (actual, declared) if actual.startswith("/") else (declared, actual)
2229
- )
2230
- return longer.endswith("/" + shorter)
2231
- return False
2232
-
2233
-
2234
2284
  def _declared_conformance_errors(
2235
2285
  declared_manifest: dict,
2236
2286
  actual_manifest: dict,
@@ -2268,23 +2318,17 @@ def _declared_conformance_errors(
2268
2318
  declared_script = _normalize_conformance_script(
2269
2319
  str(declaration.get("script") or ""), task_root
2270
2320
  )
2271
- if not _conformance_script_matches(actual_script, declared_script):
2272
- errors.append(f"stage {stage_number} script mismatch")
2273
- actual_requires = actual_entry.get("requires")
2274
- actual_capabilities = (
2275
- frozenset(actual_requires)
2276
- if isinstance(actual_requires, list)
2277
- and all(isinstance(value, str) for value in actual_requires)
2278
- else None
2279
- )
2280
2321
  # 넓히는 것만 허용한다 — 선언보다 많은 capability 는 더 엄격한 검증이다.
2281
2322
  # 승인된 계획이 `requires` 를 좁게 적고 그 stage 의 diff 가 다른 표면을
2282
2323
  # 건드리면, diff-surface 대조는 넓힐 것을 요구하는데 정확 일치는 그것을
2283
2324
  # 거절해 같은 계획으로는 통과할 입력이 없었다(2026-09-22 dev-10860
2284
2325
  # Stage 1). 좁히는 것은 선언한 검증을 빼는 것이므로 여전히 불일치다.
2285
- declared_capabilities = frozenset(declaration.get("requires") or [])
2286
- if actual_capabilities is None or not actual_capabilities >= declared_capabilities:
2287
- errors.append(f"stage {stage_number} requires mismatch")
2326
+ for error in conformance_entry_mismatches(
2327
+ actual_script=actual_script, declared_script=declared_script,
2328
+ actual_requires=actual_entry.get("requires"),
2329
+ declared_requires=frozenset(declaration.get("requires") or []),
2330
+ ):
2331
+ errors.append(f"stage {stage_number} {error}")
2288
2332
  # 계획이 면제한 stage 에 구현이 실제 Tier 3 항목을 붙이는 것은 허용한다 —
2289
2333
  # 면제 stage 의 diff 가 db/io/http/external 표면을 건드려 diff-surface 대조에
2290
2334
  # 걸렸을 때, 승인된 계획은 불변이므로 그 항목이 유일한 진행 경로다
@@ -2357,9 +2401,15 @@ def _validate_conformance(
2357
2401
  failures: list[str],
2358
2402
  surface_patterns: object = None,
2359
2403
  approved_plan_path: Path | None = None,
2404
+ run_manifest_path: Path | None = None,
2405
+ project_root: Path | None = None,
2360
2406
  ) -> list[str]:
2361
2407
  """Tier 3 conformance 게이트(implementation / final-verification).
2362
2408
 
2409
+ A run manifest with `verificationEvidenceVersion` takes results from the
2410
+ verification execution records alone and also gates every stage its
2411
+ generations require, such as an earlier stage whose script changed.
2412
+
2363
2413
  A missing task-level manifest is inert only without approved-plan evidence.
2364
2414
  When a recorded approved plan declares conformance for the in-scope stage,
2365
2415
  disappearance of that manifest is a blocking structural failure. Otherwise,
@@ -2450,9 +2500,16 @@ def _validate_conformance(
2450
2500
  f"in {manifest_path}"
2451
2501
  )
2452
2502
  scoped = _scope_manifest_entries(manifest, stage_name)
2503
+ evidence = _evidence_conformance_results(
2504
+ run_manifest_path, project_root, manifest, scoped, failures,
2505
+ )
2506
+ gated, results, unusable = (
2507
+ evidence if evidence is not None
2508
+ else (scoped, _load_conformance_results(qa_dir, scoped), {})
2509
+ )
2453
2510
  entries_by_key = {
2454
2511
  entry.get("stageKey"): entry
2455
- for entry in scoped.get("entries", [])
2512
+ for entry in gated.get("entries", [])
2456
2513
  if isinstance(entry, dict) and isinstance(entry.get("stageKey"), str)
2457
2514
  }
2458
2515
  for stage_key, entry in entries_by_key.items():
@@ -2469,8 +2526,7 @@ def _validate_conformance(
2469
2526
  "conformance result or record a user-acknowledged waiver. See "
2470
2527
  "docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md §7.1."
2471
2528
  )
2472
- results = _load_conformance_results(qa_dir, scoped)
2473
- for verdict in evaluate_conformance(scoped, results):
2529
+ for verdict in evaluate_conformance(gated, results):
2474
2530
  if verdict.status == "ADVISORY":
2475
2531
  entry = entries_by_key.get(verdict.stage_key, {})
2476
2532
  warnings.append(
@@ -2481,9 +2537,13 @@ def _validate_conformance(
2481
2537
  f"manifest: {manifest_path}"
2482
2538
  )
2483
2539
  elif not verdict.ok:
2540
+ # `unusable` keys only result-less stages, whose BLOCKING verdict
2541
+ # reads "never ran"; their rejected records exist, so the records
2542
+ # and their defects replace that message.
2484
2543
  failures.append(
2485
2544
  f"conformance gate BLOCKING for stage {verdict.stage_key}: "
2486
- f"{verdict.message}. Run the stage's conformance script (or declare "
2545
+ f"{unusable.get(verdict.stage_key, verdict.message)}. "
2546
+ f"Run the stage's conformance script (or declare "
2487
2547
  f"an exemption / user waiver) — see "
2488
2548
  f"docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md."
2489
2549
  )
@@ -2496,6 +2556,23 @@ def _validate_conformance(
2496
2556
  return warnings
2497
2557
 
2498
2558
 
2559
+ def _validate_run_conformance(
2560
+ report_path: Path, run_manifest_path: Path, project_root: Path,
2561
+ failures: list[str],
2562
+ ) -> list[str]:
2563
+ """The conformance gate as `run_preflight` and `main` both run it."""
2564
+ return _validate_conformance(
2565
+ report_path,
2566
+ failures,
2567
+ surface_patterns=_project_surface_patterns(project_root),
2568
+ approved_plan_path=_approved_plan_path_from_run_inputs(
2569
+ run_manifest_path, failures
2570
+ ),
2571
+ run_manifest_path=run_manifest_path,
2572
+ project_root=project_root,
2573
+ )
2574
+
2575
+
2499
2576
  _TEST_FILE_RE = re.compile(r"(\.spec\.|\.test\.|(^|/)test_|_test\.|(^|/)tests?/)")
2500
2577
  # okstra ships deliberately self-mocked samples as detector fixtures; gating
2501
2578
  # them would make okstra permanently fail its own gate when verifying itself.
@@ -5783,13 +5860,8 @@ def run_preflight(report_path: Path, run_manifest_path: Path) -> int:
5783
5860
  project_root = Path(
5784
5861
  str(manifest.get("projectRoot") or run_manifest_path.parent)
5785
5862
  )
5786
- warnings = _validate_conformance(
5787
- report_path,
5788
- failures,
5789
- surface_patterns=_project_surface_patterns(project_root),
5790
- approved_plan_path=_approved_plan_path_from_run_inputs(
5791
- run_manifest_path, failures
5792
- ),
5863
+ warnings = _validate_run_conformance(
5864
+ report_path, run_manifest_path, project_root, failures,
5793
5865
  )
5794
5866
  elif task_type == "implementation-planning":
5795
5867
  from okstra_ctl.report_assembly import selected_direction_plan_errors
@@ -6033,14 +6105,8 @@ def main() -> int:
6033
6105
  failures,
6034
6106
  )
6035
6107
  if task_type in ("implementation", "final-verification"):
6036
- conformance_warnings = _validate_conformance(
6037
- report_path,
6038
- failures,
6039
- surface_patterns=_project_surface_patterns(project_root),
6040
- approved_plan_path=_approved_plan_path_from_run_inputs(
6041
- run_manifest_path,
6042
- failures,
6043
- ),
6108
+ conformance_warnings = _validate_run_conformance(
6109
+ report_path, run_manifest_path, project_root, failures,
6044
6110
  )
6045
6111
  _validate_selfmock(report_path, failures)
6046
6112
  for warning in conformance_warnings: