okstra 0.229.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 (150) 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 +168 -18
  9. package/docs/architecture.md +15 -14
  10. package/docs/coding-rules.md +15 -0
  11. package/docs/contributor-change-matrix.md +5 -5
  12. package/docs/project-structure-overview.md +13 -19
  13. package/package.json +2 -3
  14. package/runtime/BUILD.json +2 -2
  15. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  16. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  17. package/runtime/prompts/coding-preflight/overview.md +1 -0
  18. package/runtime/prompts/launch.template.md +7 -5
  19. package/runtime/prompts/lead/convergence.md +4 -4
  20. package/runtime/prompts/lead/okstra-lead-contract.md +19 -18
  21. package/runtime/prompts/lead/phase-routing.md +1 -1
  22. package/runtime/prompts/lead/report-writer.md +3 -3
  23. package/runtime/prompts/lead/team-contract.md +3 -3
  24. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  25. package/runtime/python/okstra_ctl/agent/invocation.py +190 -9
  26. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  27. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  28. package/runtime/python/okstra_ctl/cmux.py +4 -2
  29. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  30. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  31. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  32. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  33. package/runtime/python/okstra_ctl/conformance.py +30 -0
  34. package/runtime/python/okstra_ctl/conformance_evidence.py +316 -0
  35. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  36. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  37. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  38. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  39. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  40. package/runtime/python/okstra_ctl/ids.py +1 -41
  41. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  42. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  43. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  44. package/runtime/python/okstra_ctl/locks.py +28 -1
  45. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  46. package/runtime/python/okstra_ctl/paths.py +90 -33
  47. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  48. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  50. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  51. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  53. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +5 -4
  55. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  57. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +5 -4
  58. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  59. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +6 -2
  60. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +4 -2
  61. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +23 -7
  63. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  65. package/runtime/python/okstra_ctl/phases/implementation/spec.md +6 -4
  66. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  67. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  68. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  69. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -12
  70. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  71. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  72. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  73. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  74. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  75. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  76. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  77. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  78. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  79. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  80. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  81. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  82. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  83. package/runtime/python/okstra_ctl/process_group.py +26 -3
  84. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  85. package/runtime/python/okstra_ctl/recap.py +1 -2
  86. package/runtime/python/okstra_ctl/render.py +25 -2
  87. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  88. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  89. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  90. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  91. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  92. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  93. package/runtime/python/okstra_ctl/run.py +40 -20
  94. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  95. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  96. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  97. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  98. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  99. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  100. package/runtime/python/okstra_ctl/verification_dispatch.py +136 -0
  101. package/runtime/python/okstra_ctl/verification_evidence.py +671 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +34 -16
  103. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  104. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  105. package/runtime/python/okstra_ctl/verification_inputs.py +83 -2
  106. package/runtime/python/okstra_ctl/verification_invocation.py +140 -0
  107. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  108. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  109. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  110. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  111. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  112. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  113. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  114. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  115. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  116. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  117. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  118. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  119. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  120. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  121. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  122. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  123. package/runtime/skills/okstra-run/SKILL.md +11 -7
  124. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  125. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  126. package/runtime/templates/reports/html/i18n/en.json +7 -0
  127. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  128. package/runtime/validators/validate-run.py +130 -20
  129. package/runtime/validators/validate-workflow.sh +1 -1
  130. package/docs/cli.md +0 -1060
  131. package/docs/container.md +0 -100
  132. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  133. package/docs/performance-improvement-plan-v2.md +0 -369
  134. package/runtime/python/okstra_ctl/container.py +0 -702
  135. package/runtime/python/okstra_ctl/rollup.py +0 -241
  136. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  137. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  138. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  139. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  140. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  141. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  142. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  143. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  144. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  145. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  146. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  147. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  148. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  149. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  150. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -10,7 +10,7 @@ from contextlib import contextmanager
10
10
  from pathlib import Path
11
11
 
12
12
  from .cleanliness import is_dirty_excluding_okstra
13
- from .git_ops import _git, is_ancestor
13
+ from .git_ops import WITHOUT_HOOKS, _git, is_ancestor
14
14
 
15
15
 
16
16
  def _checked_git(root: Path, *args: str) -> str:
@@ -38,7 +38,9 @@ def _stage_worktree(project_root: Path, branch: str) -> Iterator[Path]:
38
38
  if temporary:
39
39
  holder = Path(tempfile.mkdtemp(prefix="okstra-rebase-"))
40
40
  holder.rmdir()
41
- _checked_git(project_root, "worktree", "add", str(holder), branch)
41
+ _checked_git(
42
+ project_root, *WITHOUT_HOOKS, "worktree", "add", str(holder), branch
43
+ )
42
44
  try:
43
45
  yield holder
44
46
  finally:
@@ -93,6 +95,7 @@ def rebase_stage_branch(
93
95
  def _apply_rebase(holder: Path, branch: str, old: str, new: str) -> str:
94
96
  result = _git(
95
97
  holder,
98
+ *WITHOUT_HOOKS,
96
99
  "rebase",
97
100
  "--no-autostash",
98
101
  "--no-autosquash",
@@ -3,7 +3,6 @@ from __future__ import annotations
3
3
 
4
4
  import argparse
5
5
  import contextlib
6
- import os
7
6
  import subprocess
8
7
  import sys
9
8
  from pathlib import Path
@@ -11,6 +10,11 @@ from pathlib import Path
11
10
  from okstra_project.dirs import okstra_home
12
11
 
13
12
  from .locks import worktree_exec_lock
13
+ from .registry.verification_inputs_store import default_verification_input_store
14
+ from .verification_evidence import (
15
+ EvidenceRefused, resolve_evidence_check, run_evidence_check, shell_argv,
16
+ shell_exit_code,
17
+ )
14
18
 
15
19
  _CLI_EPILOG = r"""Every verifier of a stage runs in the same worktree at the same time, and each
16
20
  re-runs the plan's Tier 1 commands itself. A command that starts a server on a
@@ -28,24 +32,60 @@ The lock file is <okstra home>/.locks/worktree-exec/<hash of the worktree
28
32
  realpath>.lock, outside the worktree and the project's .okstra tree. When it
29
33
  cannot be created or locked, the command still runs, unlocked, after a warning
30
34
  on stderr.
35
+
36
+ Evidence mode runs one frozen check for one open verifier attempt instead:
37
+
38
+ okstra worktree-lock --project-root <root> --invocation-metadata <meta.json> \
39
+ --check qa:<qaCommands id>
40
+ okstra worktree-lock --project-root <root> --invocation-metadata <meta.json> \
41
+ --check conformance:<stageKey>
42
+
43
+ The command, the worktree and any resourceKeys come from the verification
44
+ generation the invocation is bound to, never from flags. A conformance check
45
+ runs the runCommand of that stage's entry in the conformance manifest the
46
+ generation sealed, only for a stage the generation lists in conformanceStages
47
+ and only while the manifest bytes still match the seal. In an implementation
48
+ run only the stage QA owner may run it; in final verification every verifier
49
+ runs it. It takes the worktree
50
+ lock and then each resource lock in sorted order, re-checks the attempt and the
51
+ sealed target under them, saves stdout and stderr byte for byte while passing
52
+ them through, and publishes one record under the run's verification directory.
53
+ The exit code is the command's only when the record is complete and no signal
54
+ arrived. A SIGTERM, SIGINT or SIGHUP received while the check waits or runs
55
+ exits 128+N of the first one, whatever the record says. Any other outcome (lock
56
+ unavailable, attempt cancelled, target changed, output not saved, incomplete
57
+ drain, evidence error) exits 70 and names the record on stderr. A refused
58
+ invocation or check exits 2 and runs nothing.
31
59
  """
32
60
 
33
61
 
34
- def _shell() -> str:
35
- return os.environ.get("SHELL", "") or "/bin/sh"
62
+ def _announce_wait(lockfile: Path) -> None:
63
+ _notify(f"another command holds {lockfile}; waiting")
36
64
 
37
65
 
38
- def _announce_wait(lockfile: Path) -> None:
39
- sys.stderr.write(
40
- f"okstra worktree-lock: another command holds {lockfile}; waiting\n"
66
+ def _run(command: str, worktree: Path) -> int:
67
+ return shell_exit_code(
68
+ subprocess.run(shell_argv(command), cwd=worktree, check=False).returncode
41
69
  )
70
+
71
+
72
+ def _notify(message: str) -> None:
73
+ sys.stderr.write(f"okstra worktree-lock: {message}\n")
42
74
  sys.stderr.flush()
43
75
 
44
76
 
45
- def _run(command: str, worktree: Path) -> int:
46
- code = subprocess.run([_shell(), "-c", command], cwd=worktree, check=False).returncode
47
- # 시그널로 죽은 자식은 음수를 준다. 셸이 보고하는 128+N 으로 맞춘다.
48
- return 128 - code if code < 0 else code
77
+ def _run_evidence(project: Path, metadata: Path, check_ref: str) -> int:
78
+ store = default_verification_input_store()
79
+ try:
80
+ check = resolve_evidence_check(project, metadata, check_ref, store=store)
81
+ except EvidenceRefused as exc:
82
+ _notify(f"evidence refused: {exc}")
83
+ return 2
84
+ sys.stdout.flush()
85
+ return run_evidence_check(
86
+ check, metadata, store=store, home=okstra_home(), on_wait=_announce_wait,
87
+ notify=_notify,
88
+ )
49
89
 
50
90
 
51
91
  def main(argv: list[str] | None = None) -> int:
@@ -56,17 +96,33 @@ def main(argv: list[str] | None = None) -> int:
56
96
  formatter_class=argparse.RawDescriptionHelpFormatter,
57
97
  )
58
98
  parser.add_argument(
59
- "--worktree", type=Path, required=True,
99
+ "--worktree", type=Path,
60
100
  help="worktree the command runs in; also the lock key (resolved to its realpath)",
61
101
  )
62
102
  parser.add_argument(
63
- "--command", required=True,
103
+ "--command",
64
104
  help="the declared command, run verbatim through the shell",
65
105
  )
106
+ parser.add_argument("--project-root", type=Path, help="evidence mode: project root")
107
+ parser.add_argument(
108
+ "--invocation-metadata", type=Path,
109
+ help="evidence mode: the verifier invocation's .meta.json",
110
+ )
111
+ parser.add_argument(
112
+ "--check", help="evidence mode: qa:<qaCommands id> or conformance:<stageKey>",
113
+ )
66
114
  args = parser.parse_args(argv)
115
+ evidence = (args.project_root, args.invocation_metadata, args.check)
116
+ if any(value is not None for value in evidence):
117
+ if None in evidence or args.worktree is not None or args.command is not None:
118
+ parser.error("evidence mode takes exactly --project-root, "
119
+ "--invocation-metadata and --check")
120
+ return _run_evidence(*evidence)
121
+ if args.worktree is None or args.command is None:
122
+ parser.error("--worktree and --command are required")
67
123
  worktree = args.worktree.resolve()
68
124
  if not worktree.is_dir():
69
- sys.stderr.write(f"okstra worktree-lock: not a directory: {worktree}\n")
125
+ _notify(f"not a directory: {worktree}")
70
126
  return 2
71
127
  with contextlib.ExitStack() as stack:
72
128
  try:
@@ -76,10 +132,7 @@ def main(argv: list[str] | None = None) -> int:
76
132
  except OSError as exc:
77
133
  # 잠그지 못해도 검증자의 재실행 자체를 막지 않는다. 동시 실행의 위험은
78
134
  # 락 도입 전과 같고, 그 사실을 stderr 에 남긴다.
79
- sys.stderr.write(
80
- f"okstra worktree-lock: warning: cannot take the lock ({exc}); running unlocked\n"
81
- )
82
- sys.stderr.flush()
135
+ _notify(f"warning: cannot take the lock ({exc}); running unlocked")
83
136
  return _run(args.command, worktree)
84
137
 
85
138
 
@@ -290,6 +290,10 @@ def get_implementation_base(
290
290
  ) -> Optional[str]:
291
291
  """Return the fixed implementation base commit, or None when unset /
292
292
  task-key missing."""
293
+ # Validation gates read this and must leave no file behind; taking the lock
294
+ # creates `registry.lock`.
295
+ if not _registry_path().is_file():
296
+ return None
293
297
  key = task_key(project_id, task_group, task_id)
294
298
  with _registry_lock():
295
299
  data = _load()
@@ -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": {
@@ -11,7 +11,7 @@ description: >-
11
11
  Model reviewers consolidate their teams before the orchestrator settles the
12
12
  combined findings. A coverage audit repeats missing checks on their original model and specialty slots,
13
13
  and the orchestrator verifies and settles findings. NOT for writing a PR body (okstra-pr-gen), starting a run
14
- (okstra-run), or inspecting a finished task (okstra-inspect).
14
+ (okstra-run).
15
15
  ---
16
16
 
17
17
  # OKSTRA Code Review
@@ -116,7 +116,7 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
116
116
  3. **Route the packs once, here — and fix both absolute paths the briefs carry.** `okstra paths --field home` prints the okstra home; read `<okstraHome>/prompts/coding-preflight/overview.md` and walk all three stages of its routed resource selection over the changed-file list. The result is the applied pack list — the absolute paths reviewers will read. This routing happens exactly once per run; no reviewer repeats it.
117
117
 
118
118
  The second path is this skill's own calibration file. A subagent has no "next to this file" coordinate, so the brief must spell it out: `okstra install` writes this skill to `~/.agents/skills/okstra-code-review/` on every machine (and to `~/.claude/skills/` only when `~/.claude` exists), making the literal path `~/.agents/skills/okstra-code-review/references/review-calibration.md` — the same string whether the skill was copied in or dev-linked. Carry it, together with the pack list, into every Step 3 brief.
119
- 4. Build the cells per `references/census-rules.md` and print, in this response: one cell table per axis, the exclusion list with a reason on every entry, and the applied pack list.
119
+ 4. Build the cells per `references/census-rules.md` with `okstra code-review census --project-root <projectRoot> --base <baseCommit> --head <headCommit> --rules <rules-path> --out <census-path>`, where `<rules-path>` holds the shared rule catalog for the routed packs; on a follow-up add `--previous-census <prior-census-path>` so identical targets keep their IDs. Exit 1 lists changed non-Python code under Unresolved function boundaries: add those function cells by hand before dispatch. Then print, in this response: one cell table per axis, the exclusion list with a reason on every entry, and the applied pack list.
120
120
  5. Restate both completion criteria and show they hold: censused files + exclusions = files in the diff, and every hunk maps to a censused function or to file-level code.
121
121
 
122
122
  **Membership is mechanical; judgment only ever decides a cell's verdict.** Never drop a cell because you doubt the rule applies to it — that doubt is the reviewer's answer, and its name is `clean`. Over-inclusion costs one line; a judged exclusion is the run-to-run variance this census exists to remove.
@@ -125,7 +125,7 @@ A large census is never truncated. Report the cell count and confirm before disp
125
125
 
126
126
  ## Step 3 — Select one to three model teams with six specialists each
127
127
 
128
- Let the user choose one to three reviewers with distinct models at review start; the default is 2. Honor an explicit count without asking again. Otherwise offer 2 as the default/recommended choice, with 1 and 3 as alternatives. Carry the selected value as `<reviewerCount>`; use 2 when the user accepts the default or supplies no count. Keep that count for this review and its gap-fills. The instruction and its default are checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; the runtime count range is enforced by `resolve_operation_slots` and `tests/run/test_operation_invocation.py::test_the_caller_picks_a_count_up_to_the_contract_s`. This skill is model-agnostic: do not hard-code provider names, model names or versions, preferred model order, or specialty-to-model mappings. Resolve the roster from the runtime's registered model pool for each new review:
128
+ Let the user choose one to three reviewers with distinct models at review start; the default is 2. Honor an explicit count without asking again. Otherwise offer 2 as the default/recommended choice, with 1 and 3 as alternatives. Carry the selected value as `<reviewerCount>`; use 2 when the user accepts the default or supplies no count. Keep that count for this review and its gap-fills. The instruction and its default are checked by the retired Python suite; the runtime count range is enforced by `resolve_operation_slots` and the retired Python suite. This skill is model-agnostic: do not hard-code provider names, model names or versions, preferred model order, or specialty-to-model mappings. Resolve the roster from the runtime's registered model pool for each new review:
129
129
 
130
130
  ```
131
131
  okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount>
@@ -153,7 +153,7 @@ Each returned slot is a model-team coordinator, not a specialty. Every coordinat
153
153
 
154
154
  Each model coordinator divides its received full census into six assigned censuses and passes each one to its responsible subagent. The orchestrator supplies the same full census to each coordinator; the coordinator owns division and delivery within its team. Copy the specialty's rules and all cells of its axis without changing IDs, targets, references or ordering. Naming/readability share semantic cell IDs; state/tests share state-and-tests cell IDs. Their rule subsets differ. Within each team, assigned `(cell ID, rule ID)` pairs are disjoint and their union equals the full census's pairs. Across models the entire assignment repeats independently. Never partition specialties between models. An empty specialty is recorded by its coordinator as not applicable without inventing checks or dispatching an empty review. Do not pass an empty census to `scope` or `check-coverage`, which require cells.
155
155
 
156
- Show all selected model teams and the six-specialty division policy before dispatching coordinators. Each coordinator records its concrete child assignments before spawning them. The initial review includes `reviewerCount` coordinator calls and up to `6 × reviewerCount` specialty subagent calls, plus automatic coverage gap-fills under Step 3.5. Honor any user-set cost or call limit; an insufficient limit blocks dispatch rather than silently reducing the team. This authorization does not cover provider retries, new scope, another model or a new implementation round. Instruction presence is checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; delegation, authorization and assignment accuracy remain lead checks.
156
+ Show all selected model teams and the six-specialty division policy before dispatching coordinators. Each coordinator records its concrete child assignments before spawning them. The initial review includes `reviewerCount` coordinator calls and up to `6 × reviewerCount` specialty subagent calls, plus automatic coverage gap-fills, format repairs and single provider retries under Step 3.5. Honor any user-set cost or call limit; an insufficient limit blocks dispatch rather than silently reducing the team. This authorization does not cover further provider retries, new scope, another model or a new implementation round. Instruction presence is checked by the retired Python suite; delegation, authorization and assignment accuracy remain lead checks.
157
157
 
158
158
  Each selected model coordinator itself spawns its six specialty subagents through a supported delegation surface, collects their verified completions, requests any specialty gap-fills, and consolidates their results before returning its model report. The orchestrator launches the selected coordinators; it does not spawn their children on their behalf or consolidate raw child results. These are actual separate model calls, not six headings in one response. Preserve the verified provider/model binding and standalone evidence for every child. If a coordinator cannot spawn and collect its children under that binding, report an execution blocker rather than moving those responsibilities to the orchestrator, substituting a model or replacing the team with one serial review. Specialty subagents do not delegate further. Never share other model teams' verdicts before independent team reports are complete.
159
159
 
@@ -183,7 +183,7 @@ it. **Every reviewer receives its assigned census** and independently owns its v
183
183
  - **the assigned census** — its rule subset and grouped cells, verbatim, plus its model-team slot, specialty, parent coordinator ID and the full census path for context. Coordinators receive the full census and all six child assignments; children receive only their own verdict assignment
184
184
  - the absolute paths of the packs allocated to its axes (from step 2's routing)
185
185
  - shared test execution evidence, including missing or blocked verification
186
- - the full-context inspection requirement: read whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head; follow transitive effects as needed. Specialty limits verdict ownership, not access to context. Report a suspected issue outside the assignment to the lead, who checks it and routes any required inspection to the owning specialist without duplicating or changing cells
186
+ - the full-context inspection requirement: read whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head; follow transitive effects as needed. Read with targeted `git show` ranges and `git grep`; never print a whole generated report or graph dump (for example under `graphify-out/`) into a child's context. Specialty limits verdict ownership, not access to context. Report a suspected issue outside the assignment to the lead, who checks it and routes any required inspection to the owning specialist without duplicating or changing cells
187
187
  - the calibration path, written out in full as Step 2 fixed it — `~/.agents/skills/okstra-code-review/references/review-calibration.md`. The verdict format, the severity points, and the rules for a legitimate `clean` are defined there, not in the brief; a reviewer that cannot open this file cannot return a usable verdict, so never hand it a relative path or a "next to the skill" hint
188
188
 
189
189
  **Resolve each slot's inspection scope before materializing its prompt.** Run:
@@ -237,6 +237,8 @@ Pass the `headCommit` that `okstra code-review target` returned. The command rea
237
237
 
238
238
  Automatically fill missing verdicts, unaccounted rules and malformed rows within the authorized review. Preserve every raw response and completion. For each incomplete specialist, dispatch one gap-fill on its original slot and specialty carrying only its incomplete grouped cells, their assigned rule subset, the same range, rule paths and full-context requirements. Ask for a complete row per affected cell under that subset. Use a new invocation ID and repeat materialize → verify → dispatch → materialize-result → complete → verify-completion. Audit that child's initial and gap-fill markers against its entire assigned census. Earlier usable verdicts remain unchanged. Repeat while the incomplete cell count decreases, until every assigned cell passes. Do not rerun completed specialists or borrow another model team's verdicts.
239
239
 
240
+ Two cases get one bounded repeat before the no-progress rule applies. A row rejected only for its syntax (cell or rule separators, escaping, a column count, an observation form the calibration does not allow there) gets one format repair: a continuation on the same child that carries the parser's rejection text and asks for the same verdicts in the calibration row format. That repair does not count toward the no-progress stop. An invocation that exits non-zero without a returned body is retried once on the same slot and specialty under a new invocation ID; a second failure is a provider-execution stop. Each specialist's gap-fills, repair and retry are judged separately: one specialist's stop never stops another specialist that has not had its own gap-fill.
241
+
240
242
  Stop with incomplete coverage when a gap-fill makes no progress, a user-set call/cost limit is reached, source evidence is unavailable, or an invocation fails authentication, billing, provider execution or integrity verification. Unknown cell IDs are invalid: preserve the response and report the blocker rather than relabeling IDs or retrying automatically. Do not treat infrastructure failures as missing inspections. A stopping condition fails the review instead of pausing it for authorization: dispatch no further gap-fills, continue to Step 3.6 with the verified results, and record every unaccounted `(cell ID, rule ID)` pair as a `must-fix` `now` coverage finding that names the pair, its responsible team and specialty, and the blocker. That finding stays open until a later review round accounts for the pair. A manual assessment does not satisfy reviewer coverage or create a verified completion. The lead checks these stopping conditions; the parser only checks accounting and source anchors.
241
243
 
242
244
  An isolated false observation reopens the affected cells and any dependent conclusions, not automatically every valid verdict. Record the excluded completion/cells and retain only independently valid evidence. Semantically rejected rows enter the same affected-cell gap-fill procedure; count them as incomplete when checking progress. If an older row is syntactically valid but disproved, pass the corrected completion first so the existing first-usable rule selects it; retain the older completion only for unaffected rows. If the error's extent cannot be bounded, report the unresolved extent; a full correction requires explicit authorization. Never edit an immutable response to make it pass.
@@ -85,7 +85,7 @@ Two consequences:
85
85
 
86
86
  Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) are censused on `state-and-tests` only. They are not excluded: they are covered by a different rule group.
87
87
 
88
- Enumerate functions from the frozen source and intersect their signature/body spans with the diff's changed lines. Include every matching enclosing or nested function, including same-line anonymous functions distinguished by column. Use base-side source spans to locate deletion-only changes and map surviving targets to their head positions. A removed function has no head target; account for its deletion in the surviving file's file-level cells. Changes outside functions (imports, module wiring, top-level declarations, class-level constants) also belong to file-level cells. If boundaries cannot be established, report the incomplete census and stop before dispatch instead of claiming the hunk criterion holds. Instruction presence is checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; boundary accuracy remains a lead check.
88
+ Enumerate functions from the frozen source and intersect their signature/body spans with the diff's changed lines. Include every matching enclosing or nested function, including same-line anonymous functions distinguished by column. Use base-side source spans to locate deletion-only changes and map surviving targets to their head positions. A removed function has no head target; account for its deletion in the surviving file's file-level cells. Changes outside functions (imports, module wiring, top-level declarations, class-level constants) also belong to file-level cells. If boundaries cannot be established, report the incomplete census and stop before dispatch instead of claiming the hunk criterion holds. Instruction presence is checked by the retired Python suite; boundary accuracy remains a lead check.
89
89
 
90
90
  ## Exclusions
91
91
 
@@ -143,7 +143,7 @@ Keep the original PR base and rebuild its full net-diff census at the new head.
143
143
 
144
144
  Keep all six specialty assignments stable within each selected model team. Run scope/coverage checks separately for each `(model-team slot, specialty)` against its current and previous subset census, then check each coordinator's consolidated report against the full census. Do not substitute another specialty's or model's completions. Each model independently covers the full census through its children. An empty assignment is acknowledged by its coordinator as described in SKILL.md, not passed to these commands.
145
145
 
146
- The `code-review scope` command proposes carry candidates per reviewer. It verifies prior completion integrity, role/model consistency within the prior results, complete prior coverage, ancestor history, exact base/head baseline, catalog references, and rule/policy content fingerprints. It reopens cells with prior findings, changed targets or changed recorded inputs. Missing dependency records reopen their cells. Any changed path outside the prior inventory, changed rules/base, rewritten history or missing baseline falls back to full review. Invalid completion integrity stops scope calculation. These checks are enforced by `code_review_scope.py::review_scope` and the standalone completion scope tests.
146
+ The `code-review scope` command proposes carry candidates per reviewer. It verifies prior completion integrity, role/model consistency within the prior results, ancestor history, exact base/head baseline, catalog references, and rule/policy content fingerprints. It reopens cells with prior findings, changed targets or changed recorded inputs, and cells the prior results left unverified. Missing dependency records reopen their cells. A changed path outside the prior inventory reopens only the cells that list it and is named in the scope reason so reviewers search it for further effects. Changed rules/base, rewritten history, unknown prior cell IDs or a missing baseline fall back to full review. Invalid completion integrity stops scope calculation. These checks are enforced by `code_review_scope.py::review_scope` and the standalone completion scope tests.
147
147
 
148
148
  Record each inspected cell's repository-relative input files under `Review Dependencies`: its whole target file, definitions/callees, callers, outcome consumers, relevant tests and contracts read to justify the verdict. Include transitive dependencies. Paths describe files, not line ranges; changing any part reopens the dependent cell. An external rule or instruction belongs in the repeated `--policy` inputs instead. A gap-fill retains the same baseline and records dependencies for its inspected cells.
149
149
 
@@ -39,4 +39,4 @@ Read the returned human report. Explain the business findings, verified scope an
39
39
 
40
40
  The investigation reads source, configuration, test bodies and explicitly supplied existing results. Its policy forbids executing tests, starting services, deploying, migrating or editing investigated projects. The report distinguishes that policy and the before/after source audit from an enforced write boundary. A report and a shared fact use the same accepted evidence. New runs retain prior reports and source baselines.
41
41
 
42
- Enforcement: `business_flow.engine` validates the result schema, source evidence and source stability before contribution; `agent.invocation` verifies standalone completion; `business_flow.store` preserves claim provenance and source versions. These behaviors are covered by `tests/run/test_business_flow.py` and existing invocation/JSON-boundary contract tests.
42
+ Enforcement: `business_flow.engine` validates the result schema, source evidence and source stability before contribution; `agent.invocation` verifies standalone completion; `business_flow.store` preserves claim provenance and source versions. These behaviors are covered by the retired Python suite and existing invocation/JSON-boundary contract tests.
@@ -39,9 +39,9 @@ For settings, `kind: done` means the settings transaction finished: show `next.l
39
39
 
40
40
  ## When NOT to Use
41
41
 
42
- - User explicitly asks to spawn a new terminal / new agent session — use `okstra-inspect history.4` (resume command) or instruct them to run `okstra` in another terminal.
43
- - User wants status only — use `okstra-inspect status`.
44
- - User wants past runs — use `okstra-inspect history`.
42
+ - User explicitly asks to spawn a new terminal / new agent session — instruct them to run `okstra` in another terminal.
43
+ - User wants status only — use `okstra task-show <task-key>`.
44
+ - User wants past runs — use the task timeline.
45
45
 
46
46
  <!-- BEGIN FRAGMENT: wizard-relay-protocol -->
47
47
  ## How the wizard talks to you
@@ -176,7 +176,7 @@ This prints one absolute path on stdout (e.g. `/var/folders/.../okstra-wizard.Ab
176
176
 
177
177
  Then initialize the wizard with the literal `projectRoot` / `projectId` you parsed from Step 1 and the literal state-file path from above.
178
178
 
179
- For task continuity, pass `--preferred-task-key <project-id:task-group:task-id>` on every initialization when this conversation has a known task. Use the task explicitly requested in the current message first; otherwise use the last task the user selected in this conversation's wizard. Resolve abbreviated task IDs against the project catalog before passing the full key. If the ID is ambiguous, ask which matching task the user means. Never infer this conversation's selection from project-wide `latest-task.json`, catalog recency, or another session. With neither an explicit task nor a prior selection in this conversation, omit the flag. The runtime puts the preferred task first, including a completed task when explicitly carried in, and rejects a key absent from the catalog instead of substituting another task; ordering is covered by `tests/domain/wizard/test_task_selection.py`. The task picker still lets the user change tasks.
179
+ For task continuity, pass `--preferred-task-key <project-id:task-group:task-id>` on every initialization when this conversation has a known task. Use the task explicitly requested in the current message first; otherwise use the last task the user selected in this conversation's wizard. Resolve abbreviated task IDs against the project catalog before passing the full key. If the ID is ambiguous, ask which matching task the user means. Never infer this conversation's selection from project-wide `latest-task.json`, catalog recency, or another session. With neither an explicit task nor a prior selection in this conversation, omit the flag. The runtime puts the preferred task first, including a completed task when explicitly carried in, and rejects a key absent from the catalog instead of substituting another task; ordering is covered by the former Python suite; that regression check is now retired. The task picker still lets the user change tasks.
180
180
 
181
181
  After a successful task selection, retain the returned full task key in this conversation as its task context, including in continuation summaries, and carry it into the next initialization. A different selection replaces it. Selecting a brand-new task clears the previous selection; retain the new full key once its project, group, and task ID are resolved. This conversation carry-forward is a lead instruction, not automatic host-session discovery by the runtime.
182
182
 
@@ -447,7 +447,7 @@ When the user picks a waiver, append `--qa-waiver "<stageKey>:<reason>"` to the
447
447
  If `render-bundle` stdout carries an `okstra concurrent-run stages: <stages>` label line (another implementation run on the same task-key is occupying `<stages>`), the launch prompt has already been rendered with the "Concurrent-run marker" gate. If this line is absent it is not a concurrent run, so skip this branch. If present, before dispatch present a 3-option recommendation picker to the user (run-prompt recommendation rule: 1–2 recommendations + Enter directly; this picker is authored by the skill, so it is unconstrained by the wizard `options[]` rule):
448
448
 
449
449
  1. (recommended) Proceed as-is — use the already-rendered bundle. Each session uses its own implicit team, so concurrent runs have no team conflict and split-pane works fine.
450
- 2. Wait — hold the dispatch for now. The stage worktree·run-context are preserved, so after the other occupying run finishes, resuming the same stage takes the normal team path. Print the resume command (`okstra-inspect` history → resume) to the user.
450
+ 2. Wait — hold the dispatch for now. The stage worktree·run-context are preserved, so after the other occupying run finishes, resuming the same stage takes the normal team path. Tell the user to resume the same stage with `okstra-run` after the other run finishes.
451
451
  3. Enter directly.
452
452
 
453
453
  ### Stale git SHA recovery (git-reconcile gate)
@@ -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 -->
@@ -554,4 +558,4 @@ Follow the rendered launch prompt's "Progress, remaining work, and recommendatio
554
558
  - Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
555
559
  - Name every file you show the user as a markdown link — `[<short label>](<absolute path>)`, with the absolute path inside the parentheses and a short label naming what the file is. A relative destination does not open from an external program. That is the only form the host renders as clickable; a path in backticks is text the user has to copy out. The `report-finalize` result's `reportPaths.markdown` carries the run's report, report record, and team state already in that form. Commands stay in backticks — a link is for a file, not for something to run.
556
560
  - Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
557
- - After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, finish after Step 6 and any same-run recovery, unless the user has already authorized continuing the task through further phases. In an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `/okstra-inspect status`.
561
+ - After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, finish after Step 6 and any same-run recovery, unless the user has already authorized continuing the task through further phases. In an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `okstra task-show <task-key>`.
@@ -16,7 +16,7 @@ Generate a consolidated work schedule for the selected `implementation-planning`
16
16
  - User asks to generate a work schedule / plan / "schedule" for an entire `task-group`
17
17
  - User wants a single document that summarizes all non-done tasks with effort, risk, and dependencies
18
18
 
19
- **Do NOT use** for single-task analysis (use `okstra-inspect status`) or to execute one task (use `okstra-run`).
19
+ **Do NOT use** for single-task analysis or to execute one task (use `okstra-run`).
20
20
 
21
21
  Public invocation: `/okstra-schedule-gen [task-group]`. A title or directive may be supplied in the host conversation. If none is, name the schedule after the work itself — read the task titles in scope and write what they do (e.g. `폰트 업로드 경로 개선 — 작업 일정`). Never title it after the group token: that is a directory name, not what the work is.
22
22
 
@@ -103,7 +103,7 @@ One computation rule the template scaffold cannot carry inline:
103
103
 
104
104
  ### Step 2: Filter by workStatus
105
105
 
106
- For inference when `workStatus` is missing or empty, defer to the inference table in `skills/okstra-inspect/SKILL.md` (`status.4` → "Default value convention") — do not duplicate it here. Then filter: resolved `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done` / inferred non-done) → include.
106
+ When `workStatus` is missing or empty, infer `done` if `currentStatus` is `completed` and `workflow.nextRecommendedPhase.status` is `terminal`; infer `phase-done` if `currentStatus` is `completed` and `workflow.currentPhaseState` is `completed`; infer `blocked` if `currentStatus` is `contract-violated` or `workflow.currentPhaseState` is `blocked`; otherwise infer `in-progress`. Do not write inferred values back. Then filter: resolved `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done` / inferred non-done) → include.
107
107
 
108
108
  If 0 tasks remain, output `All tasks in this task-group are done. There is no schedule to generate.` and stop **without creating a file**.
109
109
 
@@ -305,7 +305,7 @@ Reached only after both Step 5.5 gates return `pass`. Promote the verified same
305
305
 
306
306
  | Case | Handling |
307
307
  |------|----------|
308
- | `workStatus` absent or empty | Resolve via the `okstra-inspect status.4` inference table; include unless resolved `done` |
308
+ | `workStatus` absent or empty | Apply the inference rules above; include unless resolved `done` |
309
309
  | Filtered task count is 0 | Emit the "all tasks are done" message; do NOT create a file |
310
310
  | No implementation-planning report | List with a `[NEEDS-PLANNING]` banner only; no stage picker / Gantt / day total |
311
311
  | 0 remaining stages (all done, workStatus unmarked) | `_Complete — no remaining stage_`, no forward computation |
@@ -20,8 +20,7 @@ machine, or when adopting okstra in a new project.
20
20
 
21
21
  ## When NOT to use
22
22
 
23
- - A task is already in flight → use [`okstra-run`](../okstra-run/SKILL.md) or
24
- [`okstra-inspect status`](../okstra-inspect/SKILL.md).
23
+ - A task is already in flight → use [`okstra-run`](../okstra-run/SKILL.md).
25
24
  - Day-to-day usage in a project that already has `project.json` — skip this skill.
26
25
 
27
26
  ## Prerequisites
@@ -56,7 +55,7 @@ Replace `<host-runtime>` with the resolved literal value before executing each
56
55
  command. Keep the same resolved host for installation, preflight, diagnostics,
57
56
  and retries, including retries against another project or npm cache directory.
58
57
  The runtime registry validates host IDs; the skill command contract is checked
59
- by `tests/contract/test_docs_runtime_contract.py::test_skills_declare_their_host_runtime_explicitly`.
58
+ by the former Python suite; that regression check is now retired.
60
59
 
61
60
  ```bash
62
61
  npx -y okstra@latest install --runtime <host-runtime>