okstra 0.230.0 → 0.231.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 (57) hide show
  1. package/docs/architecture/storage-model.md +67 -6
  2. package/docs/architecture.md +2 -0
  3. package/docs/coding-rules.md +15 -0
  4. package/docs/project-structure-overview.md +2 -1
  5. package/package.json +2 -2
  6. package/runtime/BUILD.json +2 -2
  7. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  8. package/runtime/prompts/coding-preflight/overview.md +1 -0
  9. package/runtime/prompts/launch.template.md +2 -0
  10. package/runtime/prompts/lead/okstra-lead-contract.md +5 -5
  11. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  12. package/runtime/python/okstra_ctl/agent/invocation.py +48 -4
  13. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  14. package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
  15. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  16. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  17. package/runtime/python/okstra_ctl/paths.py +19 -4
  18. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +1 -0
  19. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  20. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +1 -0
  21. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  22. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +5 -1
  23. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -0
  24. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +19 -3
  25. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  26. package/runtime/python/okstra_ctl/phases/implementation/spec.md +2 -0
  27. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  28. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  29. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  30. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  31. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  32. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  33. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  34. package/runtime/python/okstra_ctl/render.py +15 -0
  35. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  36. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  37. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  38. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  39. package/runtime/python/okstra_ctl/run.py +16 -0
  40. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  41. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  42. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  43. package/runtime/python/okstra_ctl/verification_dispatch.py +8 -2
  44. package/runtime/python/okstra_ctl/verification_evidence.py +26 -7
  45. package/runtime/python/okstra_ctl/verification_generation.py +12 -4
  46. package/runtime/python/okstra_ctl/verification_inputs.py +10 -0
  47. package/runtime/python/okstra_ctl/verification_invocation.py +2 -1
  48. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  49. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  50. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  51. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  52. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  53. package/runtime/skills/okstra-run/SKILL.md +5 -1
  54. package/runtime/templates/reports/html/i18n/en.json +7 -0
  55. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  56. package/runtime/validators/validate-run.py +24 -5
  57. package/runtime/validators/validate-workflow.sh +1 -1
@@ -10230,9 +10230,163 @@
10230
10230
  },
10231
10231
  "discrepancy": {
10232
10232
  "type": "string"
10233
+ },
10234
+ "executionEvidence": {
10235
+ "type": "array",
10236
+ "description": "The latest run of each check this verifier ran in evidence mode, derived by report assembly from the verification execution records of an evidence-contract run. Absent in runs without that contract.",
10237
+ "minItems": 1,
10238
+ "items": {
10239
+ "$ref": "#/$defs/ExecutionEvidenceRef"
10240
+ }
10233
10241
  }
10234
10242
  }
10235
10243
  },
10244
+ "ExecutionEvidenceRef": {
10245
+ "type": "object",
10246
+ "description": "One verification execution record: where it is, the bytes it had when the report was assembled, the invocation, attempt, check and check run it belongs to, the generation it ran against, and what it observed. `collection: incomplete` is a record that is no executed check; `defect` says why.",
10247
+ "required": [
10248
+ "recordPath",
10249
+ "recordDigest",
10250
+ "invocationRef",
10251
+ "attempt",
10252
+ "checkRef",
10253
+ "checkRun",
10254
+ "generation",
10255
+ "collection",
10256
+ "defect",
10257
+ "command",
10258
+ "exitCode",
10259
+ "signal",
10260
+ "outputTail"
10261
+ ],
10262
+ "additionalProperties": false,
10263
+ "properties": {
10264
+ "recordPath": {
10265
+ "type": "string",
10266
+ "minLength": 1
10267
+ },
10268
+ "recordDigest": {
10269
+ "description": "Null when the check run published no readable record.",
10270
+ "type": [
10271
+ "string",
10272
+ "null"
10273
+ ],
10274
+ "pattern": "^sha256:[0-9a-f]{64}$"
10275
+ },
10276
+ "invocationRef": {
10277
+ "type": "string",
10278
+ "minLength": 1
10279
+ },
10280
+ "attempt": {
10281
+ "type": "integer",
10282
+ "minimum": 1
10283
+ },
10284
+ "checkRef": {
10285
+ "type": "string",
10286
+ "pattern": "^(qa|conformance):.+$"
10287
+ },
10288
+ "checkRun": {
10289
+ "type": "integer",
10290
+ "minimum": 1
10291
+ },
10292
+ "generation": {
10293
+ "type": "object",
10294
+ "additionalProperties": false,
10295
+ "required": [
10296
+ "path",
10297
+ "digest"
10298
+ ],
10299
+ "properties": {
10300
+ "path": {
10301
+ "type": "string",
10302
+ "minLength": 1
10303
+ },
10304
+ "digest": {
10305
+ "type": "string",
10306
+ "pattern": "^sha256:[0-9a-f]{64}$"
10307
+ }
10308
+ }
10309
+ },
10310
+ "collection": {
10311
+ "enum": [
10312
+ "complete",
10313
+ "incomplete"
10314
+ ]
10315
+ },
10316
+ "defect": {
10317
+ "type": [
10318
+ "string",
10319
+ "null"
10320
+ ]
10321
+ },
10322
+ "command": {
10323
+ "type": [
10324
+ "string",
10325
+ "null"
10326
+ ]
10327
+ },
10328
+ "exitCode": {
10329
+ "type": [
10330
+ "integer",
10331
+ "null"
10332
+ ]
10333
+ },
10334
+ "signal": {
10335
+ "type": [
10336
+ "string",
10337
+ "null"
10338
+ ]
10339
+ },
10340
+ "outputTail": {
10341
+ "description": "The last lines of the saved standard output, bounded by report assembly.",
10342
+ "type": "string"
10343
+ }
10344
+ },
10345
+ "allOf": [
10346
+ {
10347
+ "if": {
10348
+ "properties": {
10349
+ "collection": {
10350
+ "const": "complete"
10351
+ }
10352
+ },
10353
+ "required": [
10354
+ "collection"
10355
+ ]
10356
+ },
10357
+ "then": {
10358
+ "properties": {
10359
+ "defect": {
10360
+ "type": "null"
10361
+ },
10362
+ "command": {
10363
+ "type": "string"
10364
+ }
10365
+ }
10366
+ }
10367
+ },
10368
+ {
10369
+ "if": {
10370
+ "properties": {
10371
+ "collection": {
10372
+ "const": "incomplete"
10373
+ }
10374
+ },
10375
+ "required": [
10376
+ "collection"
10377
+ ]
10378
+ },
10379
+ "then": {
10380
+ "properties": {
10381
+ "defect": {
10382
+ "type": "string",
10383
+ "minLength": 1
10384
+ }
10385
+ }
10386
+ }
10387
+ }
10388
+ ]
10389
+ },
10236
10390
  "CorrectionRoundRow": {
10237
10391
  "type": "object",
10238
10392
  "description": "One correction round: the findings it fixed, the executor's commit range, and each verifier's re-verification verdict.",
@@ -10731,12 +10885,14 @@
10731
10885
  "minLength": 1
10732
10886
  },
10733
10887
  "status": {
10888
+ "description": "`evidence-incomplete` is a check run of an evidence-contract run whose execution record is no executed check; `statusReason` carries the record's defect.",
10734
10889
  "enum": [
10735
10890
  "executed",
10736
10891
  "rejected",
10737
10892
  "not-configured",
10738
10893
  "env-unavailable",
10739
- "advisory"
10894
+ "advisory",
10895
+ "evidence-incomplete"
10740
10896
  ]
10741
10897
  },
10742
10898
  "exitCode": {
@@ -10753,9 +10909,36 @@
10753
10909
  },
10754
10910
  "outputTail": {
10755
10911
  "type": "string"
10912
+ },
10913
+ "executionEvidence": {
10914
+ "description": "The verification execution record this row was derived from in an evidence-contract run; report assembly writes the row's command, status, exit code and output tail from it.",
10915
+ "$ref": "#/$defs/ExecutionEvidenceRef"
10756
10916
  }
10757
10917
  },
10758
10918
  "allOf": [
10919
+ {
10920
+ "if": {
10921
+ "properties": {
10922
+ "status": {
10923
+ "const": "evidence-incomplete"
10924
+ }
10925
+ },
10926
+ "required": [
10927
+ "status"
10928
+ ]
10929
+ },
10930
+ "then": {
10931
+ "required": [
10932
+ "statusReason",
10933
+ "executionEvidence"
10934
+ ],
10935
+ "properties": {
10936
+ "exitCode": {
10937
+ "type": "null"
10938
+ }
10939
+ }
10940
+ }
10941
+ },
10759
10942
  {
10760
10943
  "if": {
10761
10944
  "properties": {
@@ -464,6 +464,10 @@ If `render-bundle` fails with a `PrepareError` containing `Recorded stage SHAs n
464
464
 
465
465
  If the anchor (`implementation_base_commit`) is reported unresolvable, run the same command's `--reset-anchor <ref>` after user confirmation. Correcting a confirm item without the picker is forbidden — the runtime also rejects a confirm correction without `--use-ref`.
466
466
 
467
+ ### Predecessor merge conflict (merge-base gate)
468
+
469
+ A stage that depends on two or more stages starts from a merge-base branch that okstra builds from the implementation anchor by merging each predecessor's completion commit with `--no-ff`, in stage order. If two predecessors conflict, `render-bundle` fails with a `PrepareError` containing `merge conflict while merging stage <N>`. okstra never resolves the conflict itself. When it was creating the branch, it deletes the half-built branch and the steps start from the anchor. When it was advancing an existing branch to a newer predecessor commit, the branch stays at its previous tip and the steps check it out and merge only the commits it lacks. Do not edit the registry or consumers, and do not merge a predecessor into a stage branch. Stop and show the user the conflicting paths and the steps from the error verbatim: the branch name, the `git worktree add` command, and one `git merge --no-ff --no-edit <commit>` per predecessor in the listed order. Those commands disable repository hooks the way okstra's own merges do. The user, or you on the user's instruction, runs those steps, resolves the conflict, runs the project's checks, commits the merge and removes that worktree. Then retry the failed `render-bundle` with the same arguments. It reuses the branch only when the branch contains the anchor and every predecessor commit and carries no other non-merge commit; otherwise it fails and names the problem.
470
+
467
471
  ### Next stage not yet ready — normal termination (not an exception gate)
468
472
  Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
469
473
 
@@ -471,7 +475,7 @@ Because of the dependency closure, the chain queue **may include a stage that an
471
475
  A verifier FAIL that a passing lead minor fix answered does not make the verdict `FAIL` (`_implementation-deliverable.md` "Lead minor fix"); that stage settles `done` and the queue continues. When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
472
476
 
473
477
  ### Exception gate during chaining
474
- If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)
478
+ If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch), git stale-SHA reconciliation (git-reconcile branch) or a predecessor merge conflict (merge-base gate), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these branches do not discard the queue; they wait for user resolution.)
475
479
  <!-- END FRAGMENT: host-orchestration-implementation -->
476
480
 
477
481
  <!-- BEGIN FRAGMENT: wizard-lead-takeover -->
@@ -469,6 +469,11 @@
469
469
  "diff-summary": "Diff summary",
470
470
  "uncommitted-state": "Uncommitted state",
471
471
  "per-stage-reports": "Per-stage reports",
472
+ "read-only-commands": "Read-only commands",
473
+ "tier": "Tier",
474
+ "command": "Command",
475
+ "exit-code": "Exit code",
476
+ "execution-record": "Execution record",
472
477
  "release-path": "Release path",
473
478
  "the-current-verdict-does-not-allow-release-h": "The current verdict does not allow release-handoff to start. Clear the blocker or the condition first.",
474
479
  "next-step": "Next step",
@@ -649,6 +654,8 @@
649
654
  "independent-check": "Independent check:",
650
655
  "independent-rerun": "Independent re-run:",
651
656
  "command-log": "Command log:",
657
+ "execution-records": "Execution records:",
658
+ "incomplete-collection": "incomplete collection",
652
659
  "discrepancy": "Discrepancy:",
653
660
  "exit-code": "exit code",
654
661
  "what-is-left": "What is left",
@@ -469,6 +469,11 @@
469
469
  "diff-summary": "diff 요약",
470
470
  "uncommitted-state": "커밋되지 않은 상태",
471
471
  "per-stage-reports": "stage 별 리포트",
472
+ "read-only-commands": "읽기 전용 명령",
473
+ "tier": "등급",
474
+ "command": "명령",
475
+ "exit-code": "종료 코드",
476
+ "execution-record": "실행 기록",
472
477
  "release-path": "릴리스 경로",
473
478
  "the-current-verdict-does-not-allow-release-h": "현재 판정으로는 release-handoff 를 시작할 수 없습니다. 차단 항목이나 조건을 먼저 해소하세요.",
474
479
  "next-step": "다음 단계",
@@ -649,6 +654,8 @@
649
654
  "independent-check": "독립 검증:",
650
655
  "independent-rerun": "독립 재실행:",
651
656
  "command-log": "명령 기록:",
657
+ "execution-records": "실행 기록:",
658
+ "incomplete-collection": "수집 불완전",
652
659
  "discrepancy": "불일치:",
653
660
  "exit-code": "종료 코드",
654
661
  "what-is-left": "남은 것",
@@ -42,6 +42,8 @@ from okstra_ctl.phases.implementation.validation import (
42
42
  _validate_verifier_fail_blocks_verdict,
43
43
  _validate_correction_rounds,
44
44
  _validate_lead_fixes,
45
+ validate_settled_round_was_reverified,
46
+ validate_verifier_execution_evidence,
45
47
  _validate_verifier_command_log_is_read_only as validate_verifier_command_log_is_read_only,
46
48
  _validate_verifier_discrepancy_names_checklist_phase as validate_verifier_discrepancy_names_checklist_phase,
47
49
  _warn_out_of_plan_edits_not_in_diff as warn_out_of_plan_edits_not_in_diff,
@@ -227,7 +229,9 @@ from okstra_ctl.validation_contract import ( # noqa: E402
227
229
  )
228
230
  from okstra_ctl.blocking_checks import partition as partition_blocking # noqa: E402
229
231
  from okstra_ctl import next_phase # noqa: E402
232
+ from okstra_ctl.report_execution_evidence import execution_evidence_contract # noqa: E402
230
233
  from okstra_ctl.phases.final_verification.validation import ( # noqa: E402
234
+ validate_command_log_execution_evidence,
231
235
  validate_final_verification_content,
232
236
  validate_verification_target_match,
233
237
  )
@@ -1977,10 +1981,8 @@ def _evidence_conformance_results(
1977
1981
  if stage.result is not None
1978
1982
  }
1979
1983
  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
+ key: summary for key, stage in evidence.results.items()
1985
+ if (summary := stage.unusable_summary()) is not None
1984
1986
  }
1985
1987
  return {"entries": gated}, results, unusable
1986
1988
 
@@ -3158,6 +3160,7 @@ def validate_final_report_data(
3158
3160
  *,
3159
3161
  report_contracts: set[str] | None = None,
3160
3162
  run_manifest: dict | None = None,
3163
+ run_manifest_path: Path | None = None,
3161
3164
  project_root: Path | None = None,
3162
3165
  clarification_text: str = "",
3163
3166
  ) -> Mapping[str, Any] | None:
@@ -3281,15 +3284,30 @@ def validate_final_report_data(
3281
3284
  )
3282
3285
  elif task_type == "implementation":
3283
3286
  _validate_stage_carry_sidecar_exists(data, report_path, failures)
3284
- _validate_lead_fixes(data, failures)
3287
+ evidence_contract = execution_evidence_contract(manifest, failures)
3288
+ _validate_lead_fixes(
3289
+ data, failures, evidence_contract=evidence_contract is not False,
3290
+ )
3285
3291
  _validate_lead_fix_carry_head(data, report_path, failures)
3286
3292
  _validate_correction_rounds(data, manifest, failures)
3293
+ if (evidence_contract and run_manifest_path is not None
3294
+ and project_root is not None):
3295
+ validate_verifier_execution_evidence(
3296
+ data, project_root, run_manifest_path, manifest, failures,
3297
+ )
3298
+ validate_settled_round_was_reverified(
3299
+ data, project_root, run_manifest_path, manifest, failures,
3300
+ )
3287
3301
  _validate_lead_authored_report(data, report_path, failures)
3288
3302
  if task_type == "error-analysis":
3289
3303
  _validate_error_analysis_consistency(data, failures)
3290
3304
  elif task_type == "final-verification":
3291
3305
  _validate_final_verification_consistency(data, failures)
3292
3306
  _validate_verified_row_recorded(data, report_path, failures)
3307
+ if run_manifest_path is not None and project_root is not None:
3308
+ validate_command_log_execution_evidence(
3309
+ data, project_root, run_manifest_path, manifest, failures,
3310
+ )
3293
3311
  elif task_type == "implementation-planning":
3294
3312
  active_report_contracts = report_contracts or set()
3295
3313
  planning = data.get("implementationPlanning") or {}
@@ -6069,6 +6087,7 @@ def main() -> int:
6069
6087
  failures,
6070
6088
  report_contracts=report_contracts,
6071
6089
  run_manifest=run_manifest,
6090
+ run_manifest_path=run_manifest_path,
6072
6091
  project_root=project_root,
6073
6092
  clarification_text=_clarification_text_for_run(
6074
6093
  run_manifest_path, report_path
@@ -28,7 +28,7 @@ SOURCE_ASSET_ROOT="$WORKSPACE_ROOT/agents"
28
28
  # Arbitrary sample task-type used only to exercise the bundle-prep /
29
29
  # discovery-pointer / task-catalog / asset-seeding machinery via render-only
30
30
  # run_okstra. Must NOT require --approved-plan (excludes implementation and
31
- # final-verification) and must have a tests/fixtures/final-report-data/
31
+ # final-verification) and must have a tests/fixtures/final-report-data-v2/
32
32
  # <task-type>-001.data.json sample (used by prepare_run_validator_fixture).
33
33
  TASK_TYPE="requirements-discovery"
34
34
  PRIMARY_TASK_GROUP="validation"