okstra 0.226.0 → 0.228.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 (103) hide show
  1. package/README.md +2 -1
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/wizard.mjs +12 -15
  5. package/dist/commands/execute/wizard.mjs.map +1 -1
  6. package/docs/architecture/storage-model.md +77 -0
  7. package/docs/cli.md +43 -7
  8. package/docs/project-structure-overview.md +13 -3
  9. package/package.json +1 -1
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/agents/operations/code-review.json +1 -1
  12. package/runtime/prompts/duties/code-reviewer.json +1 -0
  13. package/runtime/prompts/lead/convergence.md +5 -19
  14. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  15. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  16. package/runtime/prompts/wizard/prompts.ko.json +44 -0
  17. package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
  18. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
  19. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
  20. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
  21. package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
  22. package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
  23. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
  24. package/runtime/python/okstra_ctl/brief_sources.py +162 -44
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +81 -19
  26. package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
  27. package/runtime/python/okstra_ctl/code_review_target.py +115 -55
  28. package/runtime/python/okstra_ctl/conformance.py +9 -3
  29. package/runtime/python/okstra_ctl/correction_cli.py +6 -5
  30. package/runtime/python/okstra_ctl/correction_round.py +1 -1
  31. package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
  32. package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
  33. package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
  34. package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
  35. package/runtime/python/okstra_ctl/fixed_text.py +31 -9
  36. package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
  37. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
  38. package/runtime/python/okstra_ctl/json_registry.py +3 -18
  39. package/runtime/python/okstra_ctl/manager_split.py +201 -84
  40. package/runtime/python/okstra_ctl/model_io/references.py +31 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
  42. package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
  43. package/runtime/python/okstra_ctl/path_hints.py +13 -1
  44. package/runtime/python/okstra_ctl/paths.py +4 -0
  45. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
  46. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
  47. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
  48. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
  49. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  50. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
  53. package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
  54. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
  55. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  60. package/runtime/python/okstra_ctl/plan_items.py +9 -11
  61. package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
  62. package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
  63. package/runtime/python/okstra_ctl/prior_planning.py +6 -17
  64. package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
  65. package/runtime/python/okstra_ctl/qa_commands.py +66 -1
  66. package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
  67. package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
  68. package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
  69. package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
  70. package/runtime/python/okstra_ctl/render.py +10 -0
  71. package/runtime/python/okstra_ctl/report_assembly.py +12 -12
  72. package/runtime/python/okstra_ctl/run.py +123 -6
  73. package/runtime/python/okstra_ctl/stage_done.py +5 -4
  74. package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
  75. package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
  76. package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
  77. package/runtime/python/okstra_ctl/verification_plan.py +116 -0
  78. package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
  79. package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
  80. package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
  81. package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
  82. package/runtime/python/okstra_ctl/wizard/render.py +2 -2
  83. package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
  84. package/runtime/python/okstra_ctl/wizard/state.py +55 -14
  85. package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
  86. package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
  87. package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
  88. package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
  89. package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
  90. package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
  91. package/runtime/python/okstra_ctl/write_policy.py +33 -18
  92. package/runtime/python/okstra_project/dirs.py +22 -0
  93. package/runtime/python/okstra_project/resolver.py +10 -0
  94. package/runtime/schemas/final-report-v3.0.schema.json +5 -1
  95. package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
  96. package/runtime/skills/okstra-code-review/SKILL.md +59 -63
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
  99. package/runtime/skills/okstra-manager/SKILL.md +2 -2
  100. package/runtime/skills/okstra-run/SKILL.md +21 -1
  101. package/runtime/skills/okstra-setup/SKILL.md +2 -0
  102. package/runtime/skills/okstra-setup/references/project-config.md +2 -0
  103. package/runtime/validators/validate-brief.py +21 -5
@@ -13,7 +13,37 @@ from typing import Any, Mapping
13
13
  from okstra_project import StateError, parse_task_key, slugify
14
14
 
15
15
  from ..json_boundary import JsonBoundaryError, load_owned_object
16
- from ..paths import okstra_home
16
+ from ..convergence import ConvergenceContractError, validated_run_authority
17
+ from ..paths import RunRef, okstra_home
18
+ from ..ports.verification_inputs import VerificationInputStore
19
+ from ..verification_input_ref import VerificationInputReference
20
+ from ..verification_input_types import VerificationInputs
21
+
22
+
23
+ def _load_verification_input(
24
+ run_manifest: Path, store: VerificationInputStore,
25
+ ) -> tuple[VerificationInputReference, VerificationInputs]:
26
+ try:
27
+ authority = validated_run_authority(run_manifest)
28
+ reference = VerificationInputReference.from_artifact_fields(authority.payload)
29
+ if reference is None:
30
+ raise ValueError("run has no verification input reference")
31
+ sequence = authority.payload["runSequencesByCategory"]["manifests"]
32
+ expected = RunRef.from_run_dir(
33
+ authority.run_dir, seq=int(sequence),
34
+ ).verification_inputs
35
+ if reference.relative_path != expected.relative_to(
36
+ authority.project_root,
37
+ ).as_posix():
38
+ raise ValueError("verification inputs do not match canonical run")
39
+ path = _fixed_owned_artifact_path(
40
+ authority.project_root,
41
+ expected.relative_to(authority.project_root / ".okstra"),
42
+ "verification inputs",
43
+ )
44
+ return reference, store.read(path, reference.digest)
45
+ except (ConvergenceContractError, OSError, ValueError) as exc:
46
+ raise JsonBoundaryError(run_manifest, "verification inputs", str(exc)) from exc
17
47
 
18
48
 
19
49
  def _fixed_owned_artifact_path(
@@ -16,9 +16,10 @@ from ..convergence import (
16
16
  validated_run_authority,
17
17
  )
18
18
  from ..error_zip import last_output_path
19
- from ..fixed_text import line as _line, scalar as _value
19
+ from ..fixed_text import line as _line, scalar as _value, quoted_value_lines
20
20
  from ..json_boundary import JsonBoundaryError, load_owned_object
21
21
  from ..paths import find_asset_root, okstra_home
22
+ from ..ports.verification_inputs import VerificationInputStore
22
23
  from ..phases.catalog import PhaseAssetError, profile_markdown
23
24
  from ..recap import assemble_group_recap, assemble_recap
24
25
  from ..role_requirements import RoleProfileError, load_role_profile
@@ -42,6 +43,7 @@ from .references import (
42
43
  _group_segment,
43
44
  _latest_task_pointer,
44
45
  _load_project,
46
+ _load_verification_input,
45
47
  _owned_run_manifest_path,
46
48
  _owned_task_manifest_path,
47
49
  _owned_tasks_root,
@@ -145,6 +147,31 @@ def render_project_context(project_root: Path, task_ref: str = "") -> str:
145
147
  )
146
148
 
147
149
 
150
+ def render_verification_input(
151
+ run_manifest: Path, store: VerificationInputStore,
152
+ ) -> str:
153
+ reference, inputs = _load_verification_input(run_manifest, store)
154
+ rows = [
155
+ "# Okstra Verification Input\n\n",
156
+ _line("Verification inputs", reference.relative_path),
157
+ _line("Verification inputs digest", reference.digest),
158
+ _line("Source root", inputs["sourceRoot"]),
159
+ "\nThese are frozen declarations, not command-execution evidence.\n",
160
+ "Scalar values below use JSON quoting; preserve escaped characters "
161
+ "when reading commands and procedure bodies.\n",
162
+ "\n## QA Commands\n\n",
163
+ *quoted_value_lines("QA commands", inputs["qaCommands"]),
164
+ "\n## Procedures\n\n",
165
+ *quoted_value_lines("Procedures", inputs["procedures"]),
166
+ ]
167
+ if "approvedPlan" in inputs:
168
+ rows.extend([
169
+ "\n## Approved Plan\n\n",
170
+ *quoted_value_lines("Approved plan", inputs["approvedPlan"]),
171
+ ])
172
+ return "".join(rows)
173
+
174
+
148
175
  def render_run_input(run_manifest: Path) -> str:
149
176
  """런 매니페스트의 간결한 비밀 없는 실행 식별자를 렌더한다."""
150
177
  run_manifest = _owned_run_manifest_path(run_manifest)
@@ -182,6 +209,8 @@ def render_run_input(run_manifest: Path) -> str:
182
209
  + _line("Task manifest", run.get("taskManifestPath"))
183
210
  + _line("Instruction set", run.get("instructionSetPath"))
184
211
  + _line("Reference expectations", run.get("referenceExpectationsPath"))
212
+ + _line("Verification inputs", run.get("verificationInputsPath"))
213
+ + _line("Verification inputs digest", run.get("verificationInputsDigest"))
185
214
  + _line("Report template", run.get("reportTemplatePath"))
186
215
  )
187
216
 
@@ -10,6 +10,7 @@ import sys
10
10
  from pathlib import Path
11
11
 
12
12
  from .json_boundary import JsonBoundaryError
13
+ from .registry.verification_inputs_store import default_verification_input_store
13
14
  from .model_io.renderers import (
14
15
  render_active_context_input,
15
16
  render_code_review_input,
@@ -24,12 +25,14 @@ from .model_io.renderers import (
24
25
  render_schedule_input,
25
26
  render_status_input,
26
27
  render_task_selection_input,
28
+ render_verification_input,
27
29
  )
28
30
 
29
31
 
30
32
  _CLI_EPILOG = r"""Usage:
31
33
  okstra model-io project-context --project-root <dir> [--task-ref <task-id|task-key|task-manifest-path>]
32
34
  okstra model-io run-input --run-manifest <path>
35
+ okstra model-io verification-input --run-manifest <path>
33
36
  okstra model-io active-context-input --project-root <dir> --run-manifest <path>
34
37
  okstra model-io schedule-input --project-root <dir> --task-group <id>
35
38
  okstra model-io code-review-input --project-root <dir> --base <ref> --head <ref>
@@ -52,6 +55,8 @@ def build_parser() -> argparse.ArgumentParser:
52
55
  project.add_argument("--task-ref", default="")
53
56
  run = commands.add_parser("run-input")
54
57
  run.add_argument("--run-manifest", required=True)
58
+ verification = commands.add_parser("verification-input")
59
+ verification.add_argument("--run-manifest", required=True)
55
60
  active = commands.add_parser("active-context-input")
56
61
  active.add_argument("--project-root", required=True)
57
62
  active.add_argument("--run-manifest", required=True)
@@ -93,6 +98,10 @@ def main(argv: list[str] | None = None) -> int:
93
98
  text = render_project_context(Path(args.project_root), args.task_ref)
94
99
  elif args.command == "run-input":
95
100
  text = render_run_input(Path(args.run_manifest))
101
+ elif args.command == "verification-input":
102
+ text = render_verification_input(
103
+ Path(args.run_manifest), default_verification_input_store(),
104
+ )
96
105
  elif args.command == "active-context-input":
97
106
  text = render_active_context_input(
98
107
  Path(args.project_root), Path(args.run_manifest)
@@ -19,6 +19,9 @@ from .paths import (
19
19
  task_timeline_file,
20
20
  )
21
21
  from .worker_artifacts import worker_artifact_paths
22
+ from .verification_input_ref import (
23
+ VerificationInputReference, artifact_fields, artifact_fields_from_context,
24
+ )
22
25
 
23
26
  RUN_CONTEXT_KIND = "run-context"
24
27
  RUN_CONTEXT_SCHEMA_VERSION = "2.0"
@@ -45,6 +48,7 @@ def compact_run_context(ctx: Mapping[str, Any]) -> dict[str, Any]:
45
48
  "runTimestampIso": ctx.get("RUN_TIMESTAMP_ISO", ""),
46
49
  "taskDate": ctx.get("TASK_DATE", ""),
47
50
  },
51
+ **artifact_fields_from_context(ctx),
48
52
  }
49
53
 
50
54
 
@@ -72,6 +76,7 @@ def compact_active_run_context(
72
76
  "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
73
77
  "verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
74
78
  "lazyReadPlan": dict(_mapping(payload.get("lazyReadPlan"))),
79
+ **artifact_fields_from_context(ctx),
75
80
  }
76
81
 
77
82
 
@@ -83,7 +88,11 @@ def hydrate_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
83
88
  identity = payload.get("identity")
84
89
  if not isinstance(hints, Mapping) or not isinstance(identity, Mapping):
85
90
  return dict(payload)
86
- return _hydrate_from_hints(identity, hints, payload.get("timestamps", {}))
91
+ ctx = _hydrate_from_hints(identity, hints, payload.get("timestamps", {}))
92
+ reference = VerificationInputReference.from_artifact_fields(payload)
93
+ if reference is not None:
94
+ ctx.update(reference.to_context(Path(str(identity.get("projectRoot", "")))))
95
+ return ctx
87
96
 
88
97
 
89
98
  def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
@@ -92,11 +101,13 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
92
101
  return dict(payload)
93
102
  identity = _mapping(payload.get("identity"))
94
103
  hints = _mapping(payload.get("pathHints"))
104
+ reference = VerificationInputReference.from_artifact_fields(payload)
95
105
  ctx = hydrate_run_context({
96
106
  "kind": RUN_CONTEXT_KIND,
97
107
  "identity": identity,
98
108
  "pathHints": hints,
99
109
  "timestamps": {},
110
+ **artifact_fields(reference),
100
111
  })
101
112
  return {
102
113
  "schemaVersion": "1.0",
@@ -305,6 +316,7 @@ def _hydrate_active_source_artifacts(ctx: Mapping[str, str]) -> dict[str, str]:
305
316
  "runContextPath": ctx.get("RUN_CONTEXT_RELATIVE_PATH", ""),
306
317
  "runInputsPath": ctx.get("RUN_INPUTS_RELATIVE_PATH", ""),
307
318
  "historyTimelinePath": ctx.get("TIMELINE_RELATIVE_PATH", ""),
319
+ **artifact_fields_from_context(ctx),
308
320
  }
309
321
 
310
322
 
@@ -219,6 +219,10 @@ class RunRef:
219
219
  def manifest(self) -> Path:
220
220
  return self.run_dir / "manifests" / f"run-manifest{self._suffix}.json"
221
221
 
222
+ @property
223
+ def verification_inputs(self) -> Path:
224
+ return self.run_dir / "verification" / f"inputs{self._suffix}.json"
225
+
222
226
  @property
223
227
  def convergence_state(self) -> Path:
224
228
  """이 run 의 finding convergence 상태 파일.
@@ -12,41 +12,61 @@ from __future__ import annotations
12
12
 
13
13
  import re
14
14
  from collections.abc import Mapping
15
+ from dataclasses import dataclass
15
16
  from pathlib import Path
16
17
 
17
18
  from okstra_ctl.final_report_paths import final_report_data_path
18
- from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
19
+ from okstra_ctl.phases.final_verification.validation import acceptance_blocker_rows
20
+ from okstra_ctl.prior_run_summary import load_prior_object, one_line
19
21
 
20
22
  _REPORT_RE = re.compile(r"^final-report-final-verification-(\d{3,})\.data\.json$")
21
23
  _SUMMARY_LIMIT = 300
22
- _WHITESPACE_RE = re.compile(r"\s+")
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class _PriorReport:
28
+ seq: str
29
+ data: Mapping
30
+ problem: str
23
31
 
24
32
 
25
33
  def prior_blockers_packet_block(final_report_path: Path) -> str:
26
- """이번 run 리포트보다 앞선 순번의 리포트 요약. 차단 사유가 없으면 빈 문자열."""
27
- current = _REPORT_RE.match(final_report_data_path(Path(final_report_path)).name)
34
+ """Summary of the reports numbered before this run's report.
35
+
36
+ Empty when no earlier report carries a blocker, none was skipped as
37
+ unreadable or malformed, and the latest readable one left no residual risk.
38
+ """
39
+ priors = _earlier_reports(Path(final_report_path))
40
+ readable = [prior for prior in priors if not prior.problem]
41
+ latest = readable[-1] if readable else None
42
+ risk_lines = _risk_lines(latest.data) if latest else []
43
+ skipped = len(readable) < len(priors)
44
+ has_blockers = any(acceptance_blocker_rows(prior.data) for prior in readable)
45
+ if not has_blockers and not skipped and not risk_lines:
46
+ return ""
47
+ return _render_block(priors, latest, risk_lines)
48
+
49
+
50
+ def _earlier_reports(final_report_path: Path) -> list[_PriorReport]:
51
+ current = _REPORT_RE.match(final_report_data_path(final_report_path).name)
28
52
  current_seq = int(current.group(1)) if current else None
29
- reports_dir = Path(final_report_path).parent
30
53
  priors = []
31
- for path in sorted(reports_dir.glob("final-report-final-verification-*.data.json")):
54
+ pattern = "final-report-final-verification-*.data.json"
55
+ for path in final_report_path.parent.glob(pattern):
32
56
  match = _REPORT_RE.match(path.name)
33
57
  if match is None:
34
58
  continue
35
- seq = int(match.group(1))
36
- if current_seq is not None and seq >= current_seq:
59
+ if current_seq is not None and int(match.group(1)) >= current_seq:
37
60
  continue
38
- data = _load(path)
39
- if data:
40
- priors.append((match.group(1), data))
41
- if not priors:
42
- return ""
43
- run_lines: list[str] = []
44
- for seq, data in priors:
45
- run_lines.extend(_run_lines(seq, data))
46
- latest_seq, latest = priors[-1]
47
- risk_lines = _risk_lines(latest)
48
- if not any(line.startswith(" - AB-") for line in run_lines) and not risk_lines:
49
- return ""
61
+ priors.append(_PriorReport(match.group(1), *_load(path)))
62
+ return sorted(priors, key=lambda prior: int(prior.seq))
63
+
64
+
65
+ def _render_block(
66
+ priors: list[_PriorReport],
67
+ latest: _PriorReport | None,
68
+ risk_lines: list[str],
69
+ ) -> str:
50
70
  parts = [
51
71
  "## Prior Final-Verification Blockers",
52
72
  "",
@@ -59,20 +79,31 @@ def prior_blockers_packet_block(final_report_path: Path) -> str:
59
79
  "`final-verification-NNN AB-NNN`, and route to a phase that re-plans",
60
80
  "the class, never to `implementation`.",
61
81
  "",
62
- *run_lines,
63
82
  ]
64
- if risk_lines:
83
+ for prior in priors:
84
+ if prior.problem:
85
+ parts.append(
86
+ f"- `final-verification-{prior.seq}`: {prior.problem} — skipped"
87
+ )
88
+ else:
89
+ parts.extend(_run_lines(prior.seq, prior.data))
90
+ if any(prior.problem for prior in priors):
65
91
  parts.extend([
66
92
  "",
67
- f"Residual risks `final-verification-{latest_seq}` left open:",
93
+ "A skipped run left a report this prepare could not read. Open it",
94
+ "before assuming that run raised no blocker.",
95
+ ])
96
+ if latest and risk_lines:
97
+ parts.extend([
98
+ "",
99
+ f"Residual risks `final-verification-{latest.seq}` left open:",
68
100
  *risk_lines,
69
101
  ])
70
102
  return "\n".join(parts)
71
103
 
72
104
 
73
105
  def _run_lines(seq: str, data: Mapping) -> list[str]:
74
- fv = data.get("finalVerification")
75
- fv = fv if isinstance(fv, Mapping) else {}
106
+ fv = data.get("finalVerification") or {}
76
107
  verdict = _one_line((data.get("finalVerdict") or {}).get("verdictToken")) or "unrecorded"
77
108
  routing = fv.get("routingRecommendation")
78
109
  target = _one_line(routing.get("target")) if isinstance(routing, Mapping) else ""
@@ -80,9 +111,7 @@ def _run_lines(seq: str, data: Mapping) -> list[str]:
80
111
  f"- `final-verification-{seq}`: verdict `{verdict}`, routed "
81
112
  f"`{target or 'unrecorded'}`"
82
113
  ]
83
- for row in fv.get("acceptanceBlockers") or []:
84
- if not isinstance(row, Mapping):
85
- continue
114
+ for row in acceptance_blocker_rows(data):
86
115
  defect_class = row.get("defectClass")
87
116
  mechanism = (
88
117
  _one_line(defect_class.get("mechanism"))
@@ -100,29 +129,42 @@ def _run_lines(seq: str, data: Mapping) -> list[str]:
100
129
 
101
130
 
102
131
  def _risk_lines(data: Mapping) -> list[str]:
103
- fv = data.get("finalVerification")
104
- rows = fv.get("residualRisk") if isinstance(fv, Mapping) else None
132
+ rows = (data.get("finalVerification") or {}).get("residualRisk") or []
105
133
  return [
106
134
  f"- {_one_line(row.get('id')) or '<no id>'}: {_one_line(row.get('item'))}"
107
- for row in rows or []
135
+ for row in rows
108
136
  if isinstance(row, Mapping)
109
137
  ]
110
138
 
111
139
 
112
- def _load(path: Path) -> Mapping:
113
- try:
114
- data = load_owned_object(path, artifact="prior final-verification report")
115
- except (JsonBoundaryError, OSError):
116
- # expected-miss: 이전 run 이 깨뜨린 리포트. 맥락 블록일 뿐이라 그 run 을
117
- # 건너뛰고, 이번 검증 준비는 막지 않는다.
118
- return {}
119
- return data if isinstance(data, Mapping) else {}
140
+ def _load(path: Path) -> tuple[Mapping, str]:
141
+ """The report and ``""``, or an empty mapping and why the report is skipped."""
142
+ data, reason = load_prior_object(path, artifact="prior final-verification report")
143
+ if reason is not None:
144
+ return {}, f"report unreadable ({_one_line(reason)})"
145
+ problem = _shape_problem(data)
146
+ if problem:
147
+ return {}, f"report malformed ({problem})"
148
+ return data, ""
149
+
150
+
151
+ def _shape_problem(data: Mapping) -> str:
152
+ """The first container this block reads that has the wrong type, or ``""``.
153
+
154
+ The loader checks only the top-level object, and a report validate-run.py
155
+ refused stays in the reports directory this block scans.
156
+ """
157
+ for key in ("finalVerdict", "finalVerification"):
158
+ value = data.get(key)
159
+ if value is not None and not isinstance(value, Mapping):
160
+ return f"`{key}` is not an object"
161
+ fv = data.get("finalVerification") or {}
162
+ for key in ("acceptanceBlockers", "residualRisk"):
163
+ value = fv.get(key)
164
+ if value is not None and not isinstance(value, list):
165
+ return f"`finalVerification.{key}` is not a list"
166
+ return ""
120
167
 
121
168
 
122
169
  def _one_line(value: object) -> str:
123
- if not isinstance(value, str):
124
- return ""
125
- collapsed = _WHITESPACE_RE.sub(" ", value).strip()
126
- if len(collapsed) <= _SUMMARY_LIMIT:
127
- return collapsed
128
- return collapsed[: _SUMMARY_LIMIT - 1].rstrip() + "…"
170
+ return one_line(value, _SUMMARY_LIMIT)
@@ -7,7 +7,7 @@
7
7
  - requirement & acceptance coverage — every must-pass point in the brief's `## Expected Behavior` / `## Preserved Behavior` / `## Expected Outcome` (and the approved plan's requirements) is covered with a cited artifact or raised as an Acceptance Blocker; no silent omissions
8
8
  - over-delivery — every surface the merged diff **adds** is traced back to a requirement. Enumerate them: each identifier, module, and configuration entry the diff introduces, searched for its callers across the whole repository (a declaration, its own test, or a commented-out line is not a caller). Record one `addedSurfaceAudit` row per surface with its disposition. `traced` names the brief requirement it serves. `exempt` names one of the legitimate exits and cites it — the approved plan reserves it for a named later stage, or something outside project code calls it (framework entrypoint, implemented interface method, migration hook, published-package API). `over-delivery` is everything else, and it is graded by callers: **no caller anywhere** is an Acceptance Blocker (delete it, or fold an added parameter back into its single call site), while **called but serving no requirement** is a Conditional Acceptance Condition with `blocksReleaseHandoff: false` — the judgement there rests on reading intent, so it travels to the PR body instead of stopping the release. The baseline is the brief, not the approved plan: a surface the plan authorised but no requirement asked for is still over-delivery, and this is the last gate that can see it. **Enforced:** `scripts/okstra_ctl/phases/final_verification/validation.py` `_validate_added_surface_audit` refuses a `traced` row naming no requirement, and an `over-delivery` row whose note does not cite the `AB-NNN` / `CA-NNN` row it became.
9
9
  - delivered artifacts match recorded expected values in `reference-expectations` (config files, deployment manifests, other recorded expected states); when reference-expectations are absent, record it as missing information rather than assuming a match
10
- - test & validation suite pass status — independently re-run the read-only two-tier command set (Tier 1 = brief/approved-plan `validation`, Tier 2 = `project.json` `qaCommands`) and confirm each passes on the verified head, citing exact command + exit code
10
+ - test & validation suite pass status — independently re-run the read-only two-tier command set selected by the declaration-source rule below and confirm each passes on the verified head, citing exact command + exit code
11
11
  - test correctness — delivered tests actually assert the intended behaviour: no gutted/weakened assertions, no tautological or always-passing tests, no tests exercising only mocks; new behaviour has matching coverage. For an `external-interface` / `transformation-mapping` surface specifically, treat a test whose only oracle is a self-authored synthetic fixture (no captured-real-sample provenance) as NOT establishing external correctness — it shows only that the parser agrees with its author's assumed shape, never that the shape matches reality; record that surface's external correctness as a user-owned external advisory gap (a Residual Risk carrying the exact "capture a real sample and confirm" next step, per the Coverage check in the self-review pass below), never as covered — the same non-blocking treatment the External QA advisory policy gives a live external check
12
12
  - DB / IO / SQL real-execution evidence — trigger: the diff touches DB/IO/SQL (ORM / query-builder, `*.repository.*`, model / `migrations/**` / `*.sql`, or changed query strings). Then Validation Evidence MUST cite a real (or faithful-replica) DB execution — the `db-test` command + exit code — not a mock-only suite. Rationale: a mock-only suite cannot observe the SQL actually emitted (observed failure class: `prompts/profiles/_implementation-verifier.md` §"DB / IO / SQL change — real-execution gate"). A DB-touching change whose only evidence is mocked, or for which no `db-test` ran, is an **Acceptance Blocker** (`major`+; per the Verdict vocabulary below, any blocker moves the verdict off `accepted`). This gate stops an unverified DB change from reaching `release-handoff` and being pushed.
13
13
  - **External Tier 3 de-duplication exception.** A DB/IO/SQL surface covered by an in-scope Tier 3 entry whose `requires` include `db`, `http`, or `external` is governed by the External QA outcome policy. Its non-PASS or unavailable result MUST NOT generate a second legacy db-test-not-configured or mock-only blocker solely for that same Tier 3 non-PASS or unavailable result. Tier 1 or Tier 2 failures remain blocking, and DB surfaces without declared external Tier 3 coverage remain blocking.
@@ -32,7 +32,7 @@
32
32
  - **Evidence:** attach file:line, exact command + exit code, log excerpt, or MCP SELECT evidence to every finding. Mark a requirement as covered only when the cited artifact demonstrates it.
33
33
  - **Defect-class sweep:** a confirmed defect is one instance of a class, and finding it does not end the search. Name its mechanism in one sentence (for example "after a recovery the editor keeps a copy of server data taken before the recovery"). Enumerate every location in the verified diff and its direct callers where that mechanism can occur, and the cases that change its outcome (for example same version, version changed, two recoveries overlapping, cancelled request). Judge every location × case cell `defective`, `sound`, `unverified`, or `not-applicable` with evidence, and report every defective cell in this run. Each blocker records the sweep as `defectClass` (`mechanism`, `cells[]`, `recurrence`). Its fix is the whole class: every `defective` cell names the `regressionTest` that must fail before the fix and pass after it. Sweep a Residual Risk's class the same way before writing it; a residual row has no `defectClass` field, so the sweep goes into its `item` text. **Enforced:** `phases/final_verification/validation.py` `_validate_defect_class_sweep` refuses a blocker without `defectClass`, without a `defective` cell, or with a `defective` cell that names no `regressionTest`. Whether the enumeration is complete is a judgement no validator can make.
34
34
  - **Prior-run carry-in:** when an earlier final-verification run of the same target exists, the analysis packet carries its blockers under `## Prior Final-Verification Blockers` (`phases/final_verification/prior_blockers.py`). Re-check each carried blocker's whole class on the current head. A blocker whose mechanism matches a carried one is `recurrence: recurring` and cites it in `priorBlockers` as `final-verification-NNN AB-NNN`; a class a single-point fix already failed to close is re-planned, so a report with a `recurring` blocker routes to `error-analysis`, `implementation-option-selection`, or `implementation-planning`, never to `implementation`. **Enforced:** `validation.py` `_validate_defect_class_sweep` refuses a `recurring` blocker with no `priorBlockers`, and `_validate_recurring_class_routing` refuses any other routing target. Marking a matching class `new` is a judgement the validator cannot see.
35
- - **Tier 1 and Tier 2 read-only validation:** Tier 1 is the originating brief/approved plan `validation` set. Tier 2 is the `Project QA Commands` section from `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token. Tier 2 is already screened by prepare, so this check catches a Tier 1 command the brief or plan named.
35
+ - **Tier 1 and Tier 2 read-only validation:** Follow the `**Verification inputs:**` declaration-source rule when that header is present. The legacy lookup supplies only the sources that rule leaves unfrozen: Tier 1 is the originating brief/approved plan `validation` set, and Tier 2 is the `Project QA Commands` section from `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). A missing or unreadable referenced snapshot is missing verification input, not permission to substitute current settings. Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token. Tier 2 is already screened by prepare, so this check catches a Tier 1 command the brief or plan named.
36
36
  - **External QA outcome policy:** continue to attempt every in-scope Tier 3
37
37
  command. For an entry requiring `db`, `http`, or `external`, record non-PASS
38
38
  as a Tier 3 `advisory` command, add a user-owned Residual Risk and exact
@@ -102,13 +102,21 @@ flowchart TD
102
102
  SelfReview --> Persist[final report + manifests]
103
103
  ```
104
104
 
105
- The validation command is never guessed automatically. When independent re-verification is needed, there are only two tiers of command source.
105
+ The validation command is never guessed automatically. When independent re-verification is needed, there are only two tiers of command source. The generated `worker_prompt_headers.py::verification_input_headers` instruction selects their declarations when frozen inputs are recorded; the legacy lookup supplies only what it leaves unfrozen.
106
+
107
+ This is a worker guideline, not command-execution evidence or an execution-log
108
+ validator. The named `model-io verification-input` projection validates the run
109
+ and snapshot before exposing frozen declarations as quoted scalar rows.
110
+ `test_verification_input_projection_rejects_invalid_input_before_output` checks
111
+ the read boundary. `tests/contract/test_docs_runtime_contract.py::test_qa_phase_sources_follow_frozen_input_headers`
112
+ checks instruction/spec alignment. Existing read-only execution, target scope,
113
+ independent QA and outcome policies remain in force.
106
114
 
107
115
  ```mermaid
108
116
  flowchart LR
109
117
  Need[needs validation command] --> Tier1{task brief / approved plan<br/>validation set?}
110
118
  Tier1 -->|yes| Deny[Deny-list self-check]
111
- Tier1 -->|no| Tier2{project.json<br/>qaCommands?}
119
+ Tier1 -->|no| Tier2{Selected project baseline<br/>qaCommands?}
112
120
  Tier2 -->|yes| Deny
113
121
  Tier2 -->|no| Missing[record<br/>qa-command not configured]
114
122
  Deny -->|clean| Run[execute read-only command]
@@ -99,8 +99,12 @@ def _added_surface_row_failures(
99
99
  return []
100
100
 
101
101
 
102
- def _acceptance_blockers(data: dict) -> list[Mapping]:
103
- rows = (data.get("finalVerification") or {}).get("acceptanceBlockers") or []
102
+ def acceptance_blocker_rows(data: Mapping) -> list[Mapping]:
103
+ """The object rows of `acceptanceBlockers`; none when a container is mistyped."""
104
+ fv = data.get("finalVerification")
105
+ rows = fv.get("acceptanceBlockers") if isinstance(fv, Mapping) else None
106
+ if not isinstance(rows, list):
107
+ return []
104
108
  return [row for row in rows if isinstance(row, Mapping)]
105
109
 
106
110
 
@@ -108,10 +112,9 @@ def _validate_defect_class_sweep(data: dict, failures: list[str]) -> None:
108
112
  """차단 사유마다 그것이 속한 결함 계열을 위치×경우 칸 단위로 훑었는지 본다.
109
113
 
110
114
  위치 하나만 적은 차단 사유는 다음 run 이 같은 원리의 다른 위치나 다른 경우를
111
- 새로 찾게 만들었다. 실측: 한 계열이 final-verification 네 번에 걸쳐 하나씩
112
- 드러났다(dev-11562 stage 1, 001-004).
115
+ 새로 찾게 만들었다.
113
116
  """
114
- for row in _acceptance_blockers(data):
117
+ for row in acceptance_blocker_rows(data):
115
118
  row_id = str(row.get("id") or "<id 없음>")
116
119
  defect_class = row.get("defectClass")
117
120
  if not isinstance(defect_class, Mapping):
@@ -121,10 +124,15 @@ def _validate_defect_class_sweep(data: dict, failures: list[str]) -> None:
121
124
  "and case that shares it before reporting the blocker."
122
125
  )
123
126
  continue
124
- cells = [
125
- cell for cell in defect_class.get("cells") or []
126
- if isinstance(cell, Mapping)
127
- ]
127
+ raw_cells = defect_class.get("cells")
128
+ if not isinstance(raw_cells, list):
129
+ failures.append(
130
+ f"final-verification: acceptance blocker {row_id} "
131
+ "`defectClass.cells` is not a list — record one cell per "
132
+ "location and case the mechanism reaches."
133
+ )
134
+ continue
135
+ cells = [cell for cell in raw_cells if isinstance(cell, Mapping)]
128
136
  defective = [cell for cell in cells if cell.get("verdict") == "defective"]
129
137
  if not defective:
130
138
  failures.append(
@@ -164,14 +172,14 @@ def _validate_recurring_class_routing(data: dict, failures: list[str]) -> None:
164
172
  """이전 run 이 이미 막았던 계열은 한 지점 수정으로 다시 보내지 않고 재계획한다."""
165
173
  recurring = [
166
174
  str(row.get("id") or "<id 없음>")
167
- for row in _acceptance_blockers(data)
175
+ for row in acceptance_blocker_rows(data)
168
176
  if isinstance(row.get("defectClass"), Mapping)
169
177
  and row["defectClass"].get("recurrence") == "recurring"
170
178
  ]
171
179
  if not recurring:
172
180
  return
173
181
  routing = (data.get("finalVerification") or {}).get("routingRecommendation")
174
- target = str((routing or {}).get("target") or "") if isinstance(routing, Mapping) else ""
182
+ target = str(routing.get("target") or "") if isinstance(routing, Mapping) else ""
175
183
  if target not in _CLASS_REPLANNING_TARGETS:
176
184
  failures.append(
177
185
  f"final-verification: acceptance blockers {recurring} are "
@@ -86,12 +86,12 @@ Changing a test's expected value is allowed here when the finding shows the orac
86
86
 
87
87
  1. Record the stage HEAD as `<base>` (`git rev-parse HEAD` in the stage worktree).
88
88
  2. Write the executor instruction with `okstra correction prompt --run-manifest <path> --round <N> --role executor --base <base> --stage-base <stage base> --finding <F-id> [--finding <F-id> ...]` into a file under the run's `state/`, then materialize it with `okstra agent-prompt materialize` — `--audience implementation-executor`, `--assignment-ref initial/<executor worker id>`, `--dispatch-kind correction-r<N>`, a new `--invocation-id` ending `-correction-r<N>-<executor worker id>`, and a result path `<executor worker id>-worker-correction-r<N>-implementation-<seq>.md`. Build a jobs file with `okstra agent-prompt jobs --dispatch-kind correction-r<N>`, dispatch it alone with `okstra team dispatch --jobs-file <path> --dispatch-kind correction-r<N>`, and settle it with `okstra team await`.
89
- `--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the 400-line limit, computed by `okstra correction file-size`; a `FILE-SIZE-ADVISORY:` line (the 300-line target) never opens or joins a round; a round may hold only those findings, and `findingIds` records them by that id. Leave out a convergence finding id that restates a `FILE-SIZE:` line, or the executor reads it twice.
89
+ `--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the 500-line limit, computed by `okstra correction file-size`; a `FILE-SIZE-ADVISORY:` line (the 300-line target) never opens or joins a round; a round may hold only those findings, and `findingIds` records them by that id. Leave out a convergence finding id that restates a `FILE-SIZE:` line, or the executor reads it twice.
90
90
  3. Do the same for every verifier with `--role verifier`, `--audience implementation-verifier`, its own `initial/<verifier worker id>` assignment, and result `<verifier worker id>-worker-correction-r<N>-implementation-<seq>.md`; dispatch the verifiers in one batch without the executor.
91
91
  4. Converge the re-verification results in round `<N>`'s own namespace, leaving the initial convergence as written. Run Phase 5.5 again with `correction-r<N>` before `<task-type>` in every state name: `okstra convergence prepare-groups --correction-round <N>` writes `convergence-groups-correction-r<N>-<task-type>-<seq>.json`; seed it with `--work-state …/convergence-work-correction-r<N>-<task-type>-<seq>.json` and `--final-state …/convergence-correction-r<N>-<task-type>-<seq>.json`; name round plans and results `convergence-round-<k>-plan-correction-r<N>-<task-type>-<seq>.json`. A reverify round in it passes `--correction-round <N>` to `reverify-prompt` and `collect-results`, materializes with `--invocation-id` ending `-correction-r<N>-reverify-r<k>-<worker id>`, and names its result `<worker id>-worker-correction-r<N>-reverify-r<k>-<task-type>-<seq>.md`. Never reseed the initial paths: a terminal final there is reused, and `--restart-from-round0` refuses it. Round `<N+1>`'s `okstra correction prompt` reads its findings from this round's final, and the report writer's synthesis packet carries it as `Convergence state (correction-r<N>)` beside the initial `Convergence state` (`report_synthesis_packet._source_specs`); report assembly projects it into `crossVerification.correctionRounds[]` and appends the evidence it promotes to `evidence.primary` with source `convergence correction-r<N>` (`report_assembly._correction_round_convergence`).
92
92
  5. No re-verification verdict is `FAIL`: the round `result` is `pass` and the run continues to persistence with the post-fix head. Otherwise `result: fail`; start round `<N+1>` if the cap allows and the entry rules still hold, or end the run `FAIL`.
93
93
 
94
- **Enforced:** `okstra convergence seed` (`scripts/okstra_ctl/convergence.py` `_seed`) accepts state paths only in the initial or a `correction-r<N>` namespace, refuses a round grouping before every grouped verifier returned an `ok` round `<N>` result (`convergence_provenance.missing_scope_results`), and checks its cited items against that round's results (`discovery_attempts` per namespace); `convergence_migration.decide_seed_action` refuses `--restart-from-round0` without an invalid working state; `plan-round` refuses to overwrite a round plan whose namespace already dispatched that round (`_refuse_dispatched_plan_overwrite`); `collect-results` reads only the namespace's reverify invocations (`correction_round.reverify_invocation_in_scope`). `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the 400-line file-size limit and names the `--stage-base` to pass, so a size violation no verifier reported still reaches a correction round, or ends the run `FAIL` when no round is left.
94
+ **Enforced:** `okstra convergence seed` (`scripts/okstra_ctl/convergence.py` `_seed`) accepts state paths only in the initial or a `correction-r<N>` namespace, refuses a round grouping before every grouped verifier returned an `ok` round `<N>` result (`convergence_provenance.missing_scope_results`), and checks its cited items against that round's results (`discovery_attempts` per namespace); `convergence_migration.decide_seed_action` refuses `--restart-from-round0` without an invalid working state; `plan-round` refuses to overwrite a round plan whose namespace already dispatched that round (`_refuse_dispatched_plan_overwrite`); `collect-results` reads only the namespace's reverify invocations (`correction_round.reverify_invocation_in_scope`). `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the 500-line file-size limit and names the `--stage-base` to pass, so a size violation no verifier reported still reaches a correction round, or ends the run `FAIL` when no round is left.
95
95
 
96
96
  ## Self-review pass before finalising the report (the Okstra lead runs this; do not delegate it)
97
97
 
@@ -9,6 +9,8 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
9
9
 
10
10
  ## Executor role binding (carried over from the thin core)
11
11
 
12
+ Follow the `**Verification inputs:**` declaration-source rule when that header is present. References to project `qaCommands` in this sidecar mean the baseline selected by that rule. The legacy lookup uses the existing plan and project baseline only where no frozen declaration replaces them.
13
+
12
14
  - **Moving dependency bases:** never run `git merge <predecessor>` or merge an old origin branch into this stage to update its base. Runtime preparation rebases downstream stages in dependency order through `okstra_ctl.stage_rebase`; a predecessor moving during execution requires stopping and re-entering preparation after the current stage claim is released. Do not rewrite another active stage or repair registry/ledger SHAs by hand. Enforcement of preparation ordering and conflict recovery is covered by `tests/worktree/test_stage_rebase.py`.
13
15
  - The `Executor` (bound in `implementation.md` thin core) is the **only worker permitted to mutate project files**. All other workers run read-only. A `runner=native-session` executor uses the selected host adapter's native edit and command primitives. A `runner=cli-wrapper` executor mutates files inside its provider CLI's auto-edit mode. The safety rules in this sidecar apply identically to both runners.
14
16
  - When the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files. If a file outside the worktree is genuinely needed, treat it as a planning gap: record it in `Out-of-plan edits` and continue.
@@ -52,7 +54,7 @@ template's check; that template is gone.
52
54
  - **External-source adapters — structure AND fixture both derive from a captured real sample; a self-authored fixture is NOT reality evidence:** when this run's diff builds or changes an `external-interface` or `transformation-mapping` surface (an HTTP / network client, or a parser / mapper of a third-party payload — HTML / JSON / XML / CSV originating outside this repo), the adapter's structural assumptions (selectors, field paths, expected response shape) AND the static fixture / golden that tests them MUST BOTH derive from a **captured real sample** of that payload — the capture cited in the stage's `external-interface` / `transformation-mapping` design-prep item, or one captured this run and recorded with its `source` + capture time. The captured sample is a static fixture (no live socket), so a parser test against it stays in source like any unit test — the Real-IO isolation rule below governs *live* calls, not the captured bytes. Do NOT hand-invent the shape and then hand-write a fixture that agrees with it: the passing test then only proves the code matches your assumption, never that the assumption matches reality (self-confirming oracle — the observed failure was a parser whose selectors existed in its synthetic fixture and in zero real pages: hundreds of green units over a fiction, and the whole structure built on the wrong shape). When no real sample is reachable (no network this run, or the brief supplied none), do NOT synthesize a stand-in and present its green tests as correctness: mark the adapter's shape `reality-unverified (no captured sample)` in `Validation evidence`, keep any placeholder fixture explicitly labelled an assumption (never validation evidence), and surface an explicit **user-owned** item in the routing recommendation to confirm against real data. Unlike the DB gate above this does NOT itself block acceptance — live external verification stays a user-owned item per `final-verification`'s External QA advisory policy — but a synthetic external fixture presented as reality-verified is exactly the mock-only external evidence the `final-verification` test-correctness pass is meant to reject.
53
55
  - **Real-IO test isolation (BLOCKING).** A test that exercises a **real** datastore, HTTP endpoint, external service, message queue, or filesystem — a live DB connection / DSN, a real `fetch` / `axios` / `http` request, an actual S3 / queue client, anything the project's normal CI test suite cannot run because that backend is absent — MUST be written under the task's qa scripts directory `<task_root>/qa/scripts/` (`<TASK_QA_PATH>/scripts`; the `qa/` root itself holds only data sidecars — the Tier 3 conformance manifest and `result-*.json`). It MUST NOT be written into the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, or anywhere the project's lint/test globs collect. Two reasons: (a) the project's CI / normal suite has no real DB or network, so a real-IO test placed in source silently breaks the pipeline; (b) it is an okstra verification artifact, and the artifact-home rule confines okstra outputs to `.okstra/`. **The dividing line is the IO, not the intent:** a unit test that stubs/spies only *injected collaborators* (mock — no real socket, no real DB handle) is a TDD red-green artifact and stays in source; the moment a test opens a real connection or makes a real network call it belongs in qa. A stage's real-IO requirement check is a Tier 3 conformance script under `<task_root>/qa/scripts/` (declared via the implementation-planning conformance entry) — never smuggle real IO into a `*.spec.*` in source to make it run "as a unit test". The `db-test` real-execution gate above is satisfied by the conformance/db-test path against the replica, NOT by adding a live-DB `*.spec.*` to the project suite. **Author qa specs with the project's own test framework — never hand-roll `describe`/`it`/`expect`.** When the project ships a test runner as a devDependency (jest / vitest / pytest …), the qa spec uses it, invoked with the project config plus a discovery override pointing at the qa scripts dir (jest: `npx jest --config <project jest config> --roots <task_root>/qa/scripts --runInBand <spec-name>`) — the project config keeps module aliases resolving while the default sweep never collects the file; never widen the project's own test config to include qa paths. For TypeScript qa specs also write `<task_root>/qa/scripts/tsconfig.json` (`extends` the project tsconfig, adds the runner's `types` entry, `"include": ["**/*.ts"]`) so editors resolve path aliases and test globals — it is a qa artifact like the rest (untracked). **These qa artifacts stay untracked — never commit them.** `.okstra/**` is gitignored (the artifact-home rule); conformance scripts and their results are *executed* and recorded in the carry sidecar / verifier result, never written into git history. A committed `.okstra/qa` file is a stage-branch defect that leaks okstra internals into the eventual PR (see the `git add` rules below).
54
56
  - **Stage conformance script (BLOCKING when the approved plan declared `Conformance tests:`).** Planning only declared the path and `requires`. This run MUST write the script to that path under `<task_root>/qa/scripts/` and add the matching `<task_root>/qa/conformance-manifest.json` entry: `stageKey` (= `<task-id>-stage-<N>`), `script`, `runCommand`, `requirementIds`, `requires` (the set the plan declared, widened by any db/io/http/external surface this stage's diff touches that the plan left out — never narrowed; `validate-run.py` `_declared_conformance_errors` accepts a superset and rejects a subset), `passContract`, `exemption: null`, `waiver: null`. Do not skip this when the plan declared tests. If the plan declared `Conformance exemption:`, do not invent a script — with one exception: when this stage's diff touches a db/io/http/external surface the exemption promised it would not (the verifier's diff-surface cross-check names the surface), write the script and the manifest entry for this stage exactly as for a declared stage, with `requires` covering those surfaces. The approved plan is not rewritten; `validate-run.py` `_declared_conformance_errors` accepts an entry for a stage the plan exempted and still rejects one for a stage the plan does not have. The script's standard interface: a `main` that exits `0`=PASS / non-zero=FAIL, and whose stdout ends with `QA-RESULT: PASS|FAIL` followed by one `REQ <id>: PASS|FAIL: <reason>` line per requirement. The verifier runs `runCommand` from the **worktree cwd**, and that cwd is the tree under test. `runCommand` MUST NOT repoint it: a leading `cd <checkout> &&` sends the script at a tree without this stage's changes. Absolute paths are fine and usually necessary — the script and its `tsconfig` live under `<task_root>/qa/scripts/`, i.e. under `.okstra/`, and a worktree does not carry `.okstra/`. Point at those by absolute path; leave the cwd alone. **Enforced:** `scripts/okstra_ctl/conformance.py` `_check_entry` rejects a `runCommand` whose first word in any `&&` / `;` segment changes directory; `validators/validate-run.py` `_validate_conformance` fails the run if the inherited declaration has no script file.
55
- - read the stage extract at this prompt's `**Approved plan stage extract:**` anchor end-to-end. It is the approved plan projected onto this run's stage: the whole Stage Map (`stageMap`), this stage's entry, the requirement-coverage, validation, rollback and risk rows that name this stage or name no stage, each with the `planItemId` (`P-Val-4`, `P-Rb-2`) directives cite it by, and the clarification items. Its `omitted` object names everything left out and why. The plan at the `**Approved plan:**` anchor stays the source of record: open it only for a targeted lookup of a key the extract omits, never end-to-end. When the prompt has no extract anchor (a Markdown plan, or a prompt published before the extract existed), read the approved plan end-to-end and parse its Stage Map instead. Read this prompt's `**Stage for this implementation run:**` anchor: the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`. Both anchors are generated headers; when either is missing, stop and report `contract-violated` rather than inferring the value.
57
+ - read the stage extract at this prompt's `**Approved plan stage extract:**` anchor end-to-end. It is the approved plan projected onto this run's stage: the whole Stage Map (`stageMap`), this stage's entry, the requirement-coverage and validation rows that name this stage, name no stage, or are cited by this stage's entry, every rollback and risk row, each of these with the `planItemId` (`P-Val-4`, `P-Rb-2`) directives cite it by, and the clarification items. Its `omitted` object names everything left out and why. The plan at the `**Approved plan:**` anchor stays the source of record: open it only for a targeted lookup of a key the extract omits, never end-to-end. When the prompt has no extract anchor (a Markdown plan, or a prompt published before the extract existed), read the approved plan end-to-end and parse its Stage Map instead. Read this prompt's `**Stage for this implementation run:**` anchor: the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`. Both anchors are generated headers; when either is missing, stop and report `contract-violated` rather than inferring the value.
56
58
  - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(this stage)` and inject them into the executor's working context as "runtime carry-in". For a `depends-on (none)` stage, no sidecar load — task-brief only.
57
59
  - this stage's `depends-on` are all already `status:done`. Its file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope.
58
60
  - **Clarification answers carried in (read before the first edit):** when the user answered the approved plan's `## 1. Clarification Items` rows, those answers arrive with this prompt under the heading `# Clarification answers carried in (authoritative)`, or as the `Clarification response` path under `## Inputs`. Treat each answer as an authoritative refinement of the plan's scope for the matching row; an answer that contradicts or expands the approved scope beyond the plan is a re-plan trigger (route to a new `implementation-planning` run), not a silent in-run change.
@@ -92,7 +94,7 @@ template's check; that template is gone.
92
94
  The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
93
95
  - **Verifier gates are not yours to run (BLOCKING).** The self-mock detector (`validators/detect_self_mock.py`) belongs to the implementation verifier and is never delegated to you (`_implementation-verifier.md` §"Self-mock detection"). The coding-conventions preflight names it as the enforcement behind the no-self-mocking principle — that names who will check your diff, not a command for you to run. You MUST NOT invoke it and MUST NOT write `<task_root>/qa/self-mock-*.json`; running it early does not pre-satisfy the gate, because the verifier runs it again under its own duty. **Enforced:** that sidecar is not among the paths your attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so the write audit closes the attempt as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`) — a stage whose every gate passed still lands as a failed run. The same holds for the conformance results `<task_root>/qa/result-*.json`: you may run a conformance script to check your work — a baseline capture or `--compare` target goes under `<task_root>/qa/baseline/` and anything else it writes (build logs, measurements) under `<task_root>/qa/output/`, the only qa directories besides `qa/scripts/` your attempt may write — but the verifier records every result, including an earlier stage's result that your rewrite of its script made stale. When the approved plan tells you to write one, leave it and name it in your result as a plan step the verifier owns.
94
96
  - **An external Tier 3 non-PASS does NOT withhold the carry evidence.** A Tier 3 entry whose `requires` include `http`, `external`, or `db` is advisory. Its FAIL, MISSING, no result, startup failure, or credential / network / service absence gets recorded honestly — exact command, exit code, output tail, marked `ADVISORY` in `Validation evidence` — and you emit the carry evidence anyway. Only Tier 1 and Tier 2 failures withhold it. Withholding on an external result is what actually blocks the stage: the carry file is the only thing that can mark a stage `done`, the verifier re-runs that same command from the host (where a call your sandbox could not complete often passes), and a stage the verifier then PASSes can never be closed because its evidence was never written.
95
- - **File size: aim for 300 lines, never exceed 400 (BLOCKING at 400).** Each threshold is broken the same three ways — a new file over it, an existing file taken past it, a file already over it that grows by any net line — counted in physical lines. Breaking 400 is a blocking finding; breaking only 300 is an advisory recommendation the verifiers record. Put a new responsibility — a group of functions, a class, a `describe` block — in a new module or test file beside the existing one instead of appending, and when a file would pass 400, split it by responsibility; never compress code or drop comments to meet the number. Lockfiles, data (JSON / YAML), Markdown, fixtures, snapshots, generated and vendored files are exempt, as are languages okstra has no coding preflight for. Check with `okstra correction file-size --base <stage-base>` before you emit the carry evidence; it writes nothing, so you may run it. **Enforced:** every verifier runs the same command and reports each `FILE-SIZE:` line (400) as a blocking finding and each `FILE-SIZE-ADVISORY:` line (300) as a recommendation, and `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range still breaks 400, so the stage goes to a correction round.
97
+ - **File size: aim for 300 lines, never take a file past 500 (BLOCKING at 500).** The 500 limit is broken by a new file over it or an existing file taken from 500 or fewer past it; the 300 target is broken those two ways and by a file already over it that grows by any net line, including a file already over 500 at the stage base. Lines are physical lines. Breaking 500 is a blocking finding; breaking only 300 is an advisory recommendation the verifiers record. Put a new responsibility — a group of functions, a class, a `describe` block — in a new module or test file beside the existing one instead of appending, and when a file would pass 500, split it by responsibility; never compress code or drop comments to meet the number. Lockfiles, data (JSON / YAML), Markdown, fixtures, snapshots, generated and vendored files are exempt, as are languages okstra has no coding preflight for. Check with `okstra correction file-size --base <stage-base>` before you emit the carry evidence; it writes nothing, so you may run it. **Enforced:** every verifier runs the same command and reports each `FILE-SIZE:` line (500) as a blocking finding and each `FILE-SIZE-ADVISORY:` line (300) as a recommendation, and `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range still breaks 500, so the stage goes to a correction round.
96
98
  - **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. The terminal row belongs to the lead's post-stage persistence and is verdict-gated — `status:"done"` with `carry_path` on a non-`FAIL` verdict, `status:"failed"` on `FAIL` (`_implementation-deliverable.md` §"Lead post-stage persistence").
97
99
  - **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.
98
100
 
@@ -17,7 +17,7 @@ fails, fix it or surface the violation — do not claim done on a failing item.
17
17
 
18
18
  - diff-review done: the `Pre-commit diff review sweep` ran over the full diff and its `Coverage:` footer is in your audit sidecar — every changed file named, with each applied rule set carrying its outcome (`clean` or `fixed <n>`). No footer, or entries with no outcome → the sweep is unfinished; do not claim done.
19
19
  - functions: every new/edited function ≤50 effective lines, single purpose — cite the longest function's actual line count, not "all under 50"
20
- - file size: no source or test file this diff adds or grows ends over 400 physical lines, and no file already over 400 grew — paste the output of `okstra correction file-size --base <stage-base>`; it must end `QA-RESULT: PASS`. Aim for 300: for each `FILE-SIZE-ADVISORY:` line it prints, split the file or say why not. A responsibility that would push a file over goes into its own new module or test file
20
+ - file size: no source or test file this diff adds ends over 500 physical lines, and no file at 500 or fewer at the stage base ends over 500 (a file already over 500 may grow; that is advisory) — paste the output of `okstra correction file-size --base <stage-base>`; it must end `QA-RESULT: PASS`. Aim for 300: for each `FILE-SIZE-ADVISORY:` line it prints, split the file or say why not. A responsibility that would push a file over goes into its own new module or test file
21
21
  - conventions: applied the routed pack + project patterns (name which ones)
22
22
  - names & comments: names say what, comments say why; no obvious-restatement comments; no truthful-name violations
23
23
  - verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"