okstra 0.231.0 → 0.232.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 (143) hide show
  1. package/README.md +15 -3
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +129 -2
  20. package/docs/architecture.md +11 -2
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/lead/convergence.md +3 -3
  43. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  44. package/runtime/prompts/lead/report-writer.md +1 -1
  45. package/runtime/prompts/lead/team-contract.md +1 -1
  46. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  47. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  48. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  49. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  50. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  51. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  52. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  53. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  54. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  55. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  56. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  57. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  58. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  59. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  60. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  61. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  62. package/runtime/python/okstra_ctl/consumers.py +12 -9
  63. package/runtime/python/okstra_ctl/convergence.py +112 -20
  64. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  65. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  66. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  67. package/runtime/python/okstra_ctl/design_review.py +207 -0
  68. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  69. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  70. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  71. package/runtime/python/okstra_ctl/doctor.py +8 -25
  72. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  73. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  74. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  75. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  76. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  77. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  78. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  79. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  80. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  81. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  82. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  83. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  84. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  85. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  86. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  87. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  88. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  89. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  90. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  91. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  92. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  93. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  94. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  95. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  96. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  97. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  98. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
  99. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  100. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  101. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
  102. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  103. package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
  104. package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
  105. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  106. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  107. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  108. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  109. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  110. package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
  111. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  112. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  113. package/runtime/python/okstra_ctl/run.py +24 -1
  114. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  115. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  116. package/runtime/python/okstra_ctl/team.py +3 -1
  117. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  118. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  119. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  120. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  121. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  122. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  123. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  124. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  125. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  126. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  127. package/runtime/python/okstra_project/__init__.py +2 -0
  128. package/runtime/python/okstra_project/dirs.py +18 -0
  129. package/runtime/python/okstra_project/state.py +25 -20
  130. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  131. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  132. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  133. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  134. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  135. package/runtime/schemas/record-secret-patterns.json +41 -0
  136. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  137. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  138. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  139. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  140. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  141. package/runtime/templates/implementation-worker-preamble.md +4 -9
  142. package/runtime/templates/worker-prompt-preamble.md +4 -12
  143. package/runtime/validators/validate-run.py +17 -8
@@ -3414,6 +3414,8 @@ def _load_recorded_run_manifest_strict(
3414
3414
  def _verification_input_source(
3415
3415
  ctx: dict, reference: VerificationInputReference | None,
3416
3416
  ) -> Path | None:
3417
+ if ctx["TASK_TYPE"] == "implementation-planning":
3418
+ return Path(ctx.get("EXECUTOR_WORKTREE_PATH") or ctx["PROJECT_ROOT"]).resolve()
3417
3419
  source_key = ("EXECUTOR_WORKTREE_PATH" if ctx["TASK_TYPE"] == "implementation"
3418
3420
  else "VERIFICATION_WORKTREE_PATH")
3419
3421
  source_path = ctx.get(source_key, "")
@@ -3459,7 +3461,7 @@ def _validate_recorded_verification_inputs(
3459
3461
  def _prepare_verification_input_reference(
3460
3462
  ctx: dict, store: VerificationInputStore,
3461
3463
  ) -> None:
3462
- if ctx["TASK_TYPE"] not in QA_COMMAND_EXECUTING_TASK_TYPES:
3464
+ if ctx["TASK_TYPE"] not in (*QA_COMMAND_EXECUTING_TASK_TYPES, "implementation-planning"):
3463
3465
  return
3464
3466
  try:
3465
3467
  project_root = Path(ctx["PROJECT_ROOT"]).resolve()
@@ -4257,11 +4259,32 @@ def _prepare_mcp_block(
4257
4259
  return prepared.block
4258
4260
 
4259
4261
 
4262
+ def _validate_new_review_policy(inp: PrepareInputs, project: Path) -> None:
4263
+ from .review_policy import capture_review_policy
4264
+
4265
+ if inp.task_type not in (*QA_COMMAND_EXECUTING_TASK_TYPES, "implementation-planning"):
4266
+ return
4267
+ override = os.environ.get("OKSTRA_RUN_SEQ_OVERRIDE", "")
4268
+ if override.isdecimal() and int(override) > 0:
4269
+ ref = RunRef(project_root=project, task_group=inp.task_group, task_id=inp.task_id,
4270
+ task_type=inp.task_type, seq=int(override))
4271
+ recorded = [ref.manifest, *ref.run_dir.glob(f"stage-*/manifests/{ref.manifest.name}")]
4272
+ if any(path.is_file() for path in recorded):
4273
+ return
4274
+ try:
4275
+ config_path = project_json_path(project)
4276
+ config = load_owned_object(config_path, artifact="project config") if config_path.exists() else {}
4277
+ capture_review_policy(project, config)
4278
+ except (OSError, ValueError) as exc:
4279
+ raise PrepareError(f"review policy preflight failed: {exc}") from exc
4280
+
4281
+
4260
4282
  def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
4261
4283
  """Produce a complete okstra task bundle on disk. See module docstring."""
4262
4284
  user_authorization = _prepare_user_authorization(inp)
4263
4285
  workspace_root = Path(inp.workspace_root)
4264
4286
  project_root = Path(inp.project_root)
4287
+ _validate_new_review_policy(inp, project_root)
4265
4288
  lead_runtime = _normalize_lead_runtime(inp.lead_runtime)
4266
4289
  lead_runtime_request = (inp.lead_runtime_request or lead_runtime).strip()
4267
4290
  runtime_resolution_json = (inp.runtime_resolution_json or "{}").strip()
@@ -108,6 +108,14 @@ def done_stage(
108
108
  head = carry_head_commit(carry)
109
109
  file_size_cap = _check_file_size(project_root, carry, head)
110
110
  report = report if report.is_absolute() else project_root / report
111
+ try:
112
+ from .design_review_evidence import validate_stage_design_report
113
+
114
+ rng = carry.get("stageCommitRange") or {}
115
+ validate_stage_design_report(project_root, report, stage, head=head,
116
+ base=str(rng.get("base") or ""), task_key=task_key)
117
+ except (OSError, ValueError) as exc:
118
+ raise StateError(f"design review prevents stage completion: {exc}", stage="design-review") from exc
111
119
  try:
112
120
  report_rel = report.relative_to(RunRef.from_report_path(report).run_dir).as_posix()
113
121
  except ValueError as exc:
@@ -169,6 +177,9 @@ over the 500-line limit or takes one past it (`okstra correction file-size`); a
169
177
  file already over 500 at the stage base may grow. Re-running with the
170
178
  same carry writes nothing new.
171
179
 
180
+ Input-4.0 runs also require the latest accepted report for this task/stage and
181
+ matching base/head, current sealed verifier results and complete design coverage.
182
+
172
183
  Output: JSON { ok, taskKey, stage, headCommit, carryPath, supersededCarryPath,
173
184
  reportPath, consumersPath, fileSizeCap }. Exit 1 on a refusal, 2 when
174
185
  PROJECT_ROOT cannot be resolved.
@@ -0,0 +1,28 @@
1
+ """Post-execution integrity checks for independent code review."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import replace
5
+
6
+ from .execution_mutation_audit import (
7
+ ExecutionMutationAudit,
8
+ MutationAuditResult,
9
+ MutationSnapshot,
10
+ )
11
+ from .write_policy import WritePolicy
12
+
13
+ REVIEW_WRITE_VIOLATION_EXIT_CODE = 77
14
+
15
+
16
+ def compare_standalone_review(
17
+ before: MutationSnapshot, policy: WritePolicy, *, succeeded: bool,
18
+ ) -> MutationAuditResult:
19
+ result = ExecutionMutationAudit().compare(
20
+ before, (policy,), attempt_succeeded=succeeded,
21
+ )
22
+ if result.untracked_paths:
23
+ result = replace(
24
+ result, status="contract-failed-unattributed", source_changed=True,
25
+ retry_allowed=False,
26
+ violations=(*result.violations, "readonly review created untracked source paths"),
27
+ )
28
+ return result
@@ -101,7 +101,9 @@ wrapper subprocess holding no pane, so there is nothing to close.
101
101
  that never reached a terminal status.
102
102
 
103
103
  On a cmux-pane run, dispatch records `phase-3-team-create` when it writes the
104
- implicit-team marker, `phase-4-dispatch` for each `initial` job and
104
+ implicit-team marker, `phase-4-dispatch` for each `initial` job and each
105
+ job of an implementation correction round (`correction-r<N>`, and a
106
+ `reverify-r<k>` whose invocation id carries `-correction-r<N>-`), and
105
107
  `phase-6-synthesis` on the first report-writer dispatch; await records
106
108
  `phase-5-poll` on entry and again when the counts changed, and
107
109
  `phase-5-collect` for each `initial` dispatch it settled. The lead does not
@@ -24,6 +24,10 @@ from .verification_inputs import (
24
24
  canonical_run_ref, publish_verification_snapshot, read_verification_inputs,
25
25
  )
26
26
  from .verification_target import read_verification_head
27
+ from .verification_input_types import DESIGN_REVIEW_INPUT_SCHEMA_VERSION
28
+ from .design_review import (
29
+ DesignReviewSnapshot, DESIGN_REVIEW_SCHEMA, capture_design_review,
30
+ )
27
31
 
28
32
 
29
33
  class _OptionalFrozenVerificationSource(TypedDict, total=False):
@@ -40,6 +44,7 @@ class FrozenVerificationSource(_OptionalFrozenVerificationSource):
40
44
 
41
45
  class _OptionalGenerationConformance(TypedDict, total=False):
42
46
  conformanceStages: list[int]
47
+ designReview: DesignReviewSnapshot
43
48
 
44
49
 
45
50
  class VerificationGenerationRecord(_OptionalGenerationConformance):
@@ -85,12 +90,23 @@ _SCHEMA = {
85
90
  "sourceRoot": _PATH, "source": _SOURCE, "artifactInputs": _FILES,
86
91
  "conformanceStages": {"type": "array",
87
92
  "items": {"type": "integer", "minimum": 1}},
93
+ "designReview": DESIGN_REVIEW_SCHEMA,
88
94
  },
89
95
  }
90
96
  _ARTIFACT = "verification generation"
91
97
 
92
98
 
93
99
  def _generation_errors(payload: dict[str, Any]) -> list[str]:
100
+ if "designReview" in payload:
101
+ from .review_verdicts import parse_review_census
102
+
103
+ review = payload["designReview"]
104
+ if payload["taskType"] != "implementation" or review["head"] != payload["head"]:
105
+ return ["design review must name this implementation head"]
106
+ try:
107
+ parse_review_census(review["census"], allow_empty=True)
108
+ except ValueError as exc:
109
+ return [f"invalid design review census: {exc}"]
94
110
  stages = payload.get("conformanceStages", [])
95
111
  if any(left >= right for left, right in pairwise(stages)):
96
112
  return ["generation conformance stages must be strictly increasing"]
@@ -177,7 +193,7 @@ def _capture_generation(
177
193
  if artifacts[relative] != digest:
178
194
  raise ValueError("verification conformance manifest changed during capture")
179
195
  read_verification_head(source_root, head)
180
- return {
196
+ result: VerificationGenerationRecord = {
181
197
  "schemaVersion": "1.0", "kind": "verification-generation",
182
198
  "generation": generation, "taskType": ref.task_type,
183
199
  "runManifestPath": ref.manifest.relative_to(project).as_posix(),
@@ -196,6 +212,12 @@ def _capture_generation(
196
212
  **({"conformanceStages": list(conformance.stages)}
197
213
  if conformance is not None else {}),
198
214
  }
215
+ if ref.task_type == "implementation" and inputs["schemaVersion"] == DESIGN_REVIEW_INPUT_SCHEMA_VERSION:
216
+ result["designReview"] = capture_design_review(
217
+ source_root, inputs["reviewBase"], head, inputs["reviewPolicy"],
218
+ ref.verification_generation(generation).with_suffix(".functions.json"),
219
+ )
220
+ return result
199
221
 
200
222
 
201
223
  def prepare_verification_generation(
@@ -5,6 +5,8 @@ from typing import Any, Literal, TypedDict
5
5
  INPUT_SCHEMA_VERSION: Literal["1.0"] = "1.0"
6
6
  INPUT_KIND: Literal["verification-inputs"] = "verification-inputs"
7
7
  PLAN_INPUT_SCHEMA_VERSION: Literal["2.0"] = "2.0"
8
+ REVIEW_INPUT_SCHEMA_VERSION: Literal["3.0"] = "3.0"
9
+ DESIGN_REVIEW_INPUT_SCHEMA_VERSION: Literal["4.0"] = "4.0"
8
10
 
9
11
 
10
12
  class FrozenProcedure(TypedDict):
@@ -12,6 +14,16 @@ class FrozenProcedure(TypedDict):
12
14
  digest: str
13
15
 
14
16
 
17
+ class _OptionalFrozenReviewPolicy(TypedDict, total=False):
18
+ authorPolicyDigest: str
19
+
20
+
21
+ class FrozenReviewPolicy(_OptionalFrozenReviewPolicy):
22
+ schemaVersion: str
23
+ architecture: str
24
+ sources: dict[str, FrozenProcedure]
25
+
26
+
15
27
  QaSourceStatus = Literal[
16
28
  "not-declared", "not-queried", "no-baseline", "unchanged", "changed",
17
29
  ]
@@ -39,6 +51,8 @@ class FrozenVerificationPlan(TypedDict):
39
51
 
40
52
 
41
53
  class _OptionalVerificationInputs(TypedDict, total=False):
54
+ reviewBase: str
55
+ reviewPolicy: FrozenReviewPolicy
42
56
  approvedPlan: FrozenVerificationPlan
43
57
  qaSourceObservations: dict[str, list[FrozenQaSourceObservation]]
44
58
  conformanceBaseline: dict[str, str]
@@ -46,7 +60,7 @@ class _OptionalVerificationInputs(TypedDict, total=False):
46
60
 
47
61
 
48
62
  class VerificationInputs(_OptionalVerificationInputs):
49
- schemaVersion: Literal["1.0", "2.0"]
63
+ schemaVersion: Literal["1.0", "2.0", "3.0", "4.0"]
50
64
  kind: Literal["verification-inputs"]
51
65
  sourceRoot: str
52
66
  qaCommands: dict[str, list[dict[str, Any]]]
@@ -10,6 +10,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
10
10
 
11
11
  from .json_boundary import load_owned_object_snapshot, write_owned_object_atomic
12
12
  from .paths import RunRef
13
+ from .review_policy import capture_review_policy, review_policy_errors
13
14
  from .qa_commands import (
14
15
  QA_COMMAND_EXECUTING_TASK_TYPES, QA_SOURCE_DIGEST_PATTERN, qa_relative_path_valid,
15
16
  validate_qa_commands,
@@ -22,12 +23,14 @@ from .qa_procedures import (
22
23
 
23
24
  from .verification_input_types import (
24
25
  INPUT_KIND, INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION,
26
+ REVIEW_INPUT_SCHEMA_VERSION, DESIGN_REVIEW_INPUT_SCHEMA_VERSION,
25
27
  FrozenProcedure, VerificationInputs,
26
28
  )
27
29
  from .verification_conformance import capture_conformance_baseline
28
30
  from .verification_plan import (
29
31
  VERIFICATION_PLAN_SCHEMA, capture_verification_plan, verification_plan_errors,
30
32
  )
33
+ from .verification_target import read_worktree_head
31
34
 
32
35
  INPUT_ARTIFACT = "verification inputs"
33
36
  QA_INPUT_FIELDS = (
@@ -41,11 +44,14 @@ INPUT_SCHEMA = {
41
44
  "additionalProperties": False,
42
45
  "required": ["schemaVersion", "kind", "sourceRoot", "qaCommands", "procedures"],
43
46
  "properties": {
44
- "schemaVersion": {"enum": [INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION]},
47
+ "schemaVersion": {"enum": [INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION,
48
+ REVIEW_INPUT_SCHEMA_VERSION, DESIGN_REVIEW_INPUT_SCHEMA_VERSION]},
45
49
  "kind": {"const": INPUT_KIND},
46
50
  "sourceRoot": {"type": "string", "minLength": 1},
47
51
  "qaCommands": {"type": "object"},
48
52
  "procedures": {"type": "object"},
53
+ "reviewPolicy": {"type": "object"},
54
+ "reviewBase": {"type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$"},
49
55
  "approvedPlan": VERIFICATION_PLAN_SCHEMA,
50
56
  "qaSourceObservations": {"type": "object"},
51
57
  "conformanceBaseline": {
@@ -101,6 +107,16 @@ def _verification_source_errors(
101
107
 
102
108
 
103
109
  def _verification_input_errors(payload: dict[str, Any]) -> list[str]:
110
+ if payload["schemaVersion"] == DESIGN_REVIEW_INPUT_SCHEMA_VERSION and not {"reviewBase", "approvedPlan"}.issubset(payload):
111
+ return ["verification inputs 4.0 requires reviewBase and approvedPlan"]
112
+ if payload["schemaVersion"] != DESIGN_REVIEW_INPUT_SCHEMA_VERSION and "reviewBase" in payload:
113
+ return ["reviewBase requires verification inputs 4.0"]
114
+ if payload["schemaVersion"] in (REVIEW_INPUT_SCHEMA_VERSION, DESIGN_REVIEW_INPUT_SCHEMA_VERSION) and "reviewPolicy" not in payload:
115
+ return ["review policy: verification inputs 3.0 requires reviewPolicy"]
116
+ if "reviewPolicy" in payload:
117
+ policy_errors = review_policy_errors(payload["reviewPolicy"])
118
+ if policy_errors:
119
+ return policy_errors
104
120
  has_plan = "approvedPlan" in payload
105
121
  if payload["schemaVersion"] == PLAN_INPUT_SCHEMA_VERSION and not has_plan:
106
122
  return ["verification inputs 2.0 requires approvedPlan"]
@@ -167,7 +183,8 @@ def _conformance_baseline_errors(payload: Mapping[str, Any]) -> list[str]:
167
183
  def capture_verification_inputs(
168
184
  project: Path, source: Path, *, approved_plan: Path | None = None,
169
185
  ) -> VerificationInputs:
170
- declared = load_qa_config(project).get("qaCommands") or {}
186
+ config = load_qa_config(project)
187
+ declared = config.get("qaCommands") or {}
171
188
  read_digest = new_qa_source_digest_reader()
172
189
  commands = {
173
190
  category: [{key: entry[key] for key in QA_INPUT_FIELDS if key in entry}
@@ -185,9 +202,10 @@ def capture_verification_inputs(
185
202
  "body": raw.decode("utf-8"), "digest": content_digest(raw),
186
203
  }
187
204
  payload: VerificationInputs = {
188
- "schemaVersion": INPUT_SCHEMA_VERSION, "kind": INPUT_KIND,
205
+ "schemaVersion": REVIEW_INPUT_SCHEMA_VERSION, "kind": INPUT_KIND,
189
206
  "sourceRoot": str(source.resolve()), "qaCommands": commands,
190
207
  "procedures": procedures,
208
+ "reviewPolicy": capture_review_policy(project, config),
191
209
  "qaSourceObservations": {
192
210
  category: [{**observe_qa_sources(source, entry, read_digest),
193
211
  "entryDigest": canonical_json_digest(entry)}
@@ -196,7 +214,6 @@ def capture_verification_inputs(
196
214
  },
197
215
  }
198
216
  if approved_plan is not None:
199
- payload["schemaVersion"] = PLAN_INPUT_SCHEMA_VERSION
200
217
  payload["approvedPlan"] = capture_verification_plan(approved_plan)
201
218
  return payload
202
219
 
@@ -288,8 +305,8 @@ def canonical_run_ref(project: Path, ref: RunRef) -> RunRef:
288
305
  def prepare_verification_inputs(
289
306
  project: Path, source: Path, ref: RunRef, *, approved_plan: Path | None = None,
290
307
  ) -> tuple[Path, str]:
291
- if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
292
- raise ValueError("verification inputs require a QA-executing phase")
308
+ if ref.task_type not in (*QA_COMMAND_EXECUTING_TASK_TYPES, "implementation-planning"):
309
+ raise ValueError("verification inputs require a QA-executing or planning phase")
293
310
  payload = capture_verification_inputs(project, source, approved_plan=approved_plan)
294
311
  if conformance_baseline_required(ref.task_type, payload):
295
312
  # The executor may rename or delete an earlier stage's script; only the
@@ -303,6 +320,11 @@ def prepare_verification_inputs(
303
320
  # Runs without the evidence contract keep preparing over a malformed
304
321
  # manifest; the recorded cause lets a marked seal refuse it by name.
305
322
  payload["conformanceBaselineError"] = str(exc)
323
+ if approved_plan is not None and ref.task_type in ("implementation", "final-verification"):
324
+ if not evidence_contract_applies(payload):
325
+ raise ValueError("design-review inputs require stable QA ids and a valid conformance baseline")
326
+ payload["schemaVersion"] = DESIGN_REVIEW_INPUT_SCHEMA_VERSION
327
+ payload["reviewBase"] = read_worktree_head(source)
306
328
  return publish_verification_snapshot(
307
329
  project, ref.verification_inputs, capture=partial(dict, payload),
308
330
  artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
@@ -9,13 +9,14 @@ from okstra_project.dirs import OKSTRA_DIR_NAME
9
9
  from .qa_commands import (
10
10
  QA_SOURCE_DIGEST_PATTERN, QA_VERIFIER_AUDIENCE_BY_TASK_TYPE, qa_relative_path_valid,
11
11
  )
12
- from .qa_procedures import safe_qa_path
12
+ from .qa_procedures import canonical_json_digest, safe_qa_path
13
13
  from .verification_generation import (
14
14
  VERIFICATION_GENERATION_PATH_MAX_LENGTH, VerificationGenerationRecord,
15
15
  read_verification_generation,
16
16
  )
17
17
  from .verification_input_ref import VerificationInputReference
18
18
  from .verification_inputs import read_verification_inputs
19
+ from .verification_input_types import DESIGN_REVIEW_INPUT_SCHEMA_VERSION
19
20
 
20
21
  VERIFICATION_EVIDENCE_VERSION = "1.0"
21
22
  VERIFICATION_GENERATION_HEADER_PREFIXES = (
@@ -118,6 +119,11 @@ def _read_bound_generation(
118
119
  )
119
120
  if record["sourceRoot"] != inputs["sourceRoot"]:
120
121
  raise ValueError("verification generation source differs from frozen inputs")
122
+ if inputs["schemaVersion"] == DESIGN_REVIEW_INPUT_SCHEMA_VERSION and task_type == "implementation":
123
+ review = record.get("designReview")
124
+ if (review is None or review["base"] != inputs["reviewBase"]
125
+ or review["policyDigest"] != canonical_json_digest(inputs["reviewPolicy"])):
126
+ raise ValueError("design review differs from frozen review base or policy")
121
127
  return record
122
128
 
123
129
 
@@ -74,6 +74,8 @@ def read_verification_target(project_root: Path, relative: str) -> dict | None:
74
74
  if stages_match
75
75
  else set()
76
76
  )
77
+ parsed["reports"] = {int(stage): path for stage, path in
78
+ re.findall(r"^ - stage (\d+): `([^`]+)`$", body, re.M)}
77
79
  return parsed
78
80
 
79
81
 
@@ -120,7 +120,9 @@ Native-session assignments remain owned by the active host session.
120
120
 
121
121
  It records the lead checkpoints it owns and prints them as `progressLines`:
122
122
  `phase-3-team-create` when it writes the implicit-team marker,
123
- `phase-4-dispatch` for each `initial` job, `phase-6-synthesis` on the first
123
+ `phase-4-dispatch` for each `initial` job and each job of an implementation
124
+ correction round (`correction-r<N>`, and a `reverify-r<k>` whose invocation id
125
+ carries `-correction-r<N>-`), `phase-6-synthesis` on the first
124
126
  report-writer dispatch, and `phase-5-collect` for each `initial` dispatch it
125
127
  settled. The lead emits those lines instead of calling
126
128
  `okstra lead-progress append` for them.
@@ -10,6 +10,7 @@ from .fixed_text import block
10
10
  from .paths import okstra_home
11
11
  from .verification_input_ref import VerificationInputReference
12
12
  from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
13
+ from .worker_prompt_body import analysis_input_lines
13
14
  from .worker_prompt_policy import (
14
15
  GRILLING_LOG_HEADER,
15
16
  PromptPlan,
@@ -36,16 +37,16 @@ class WorkerPromptHeaderError(Exception):
36
37
  READ_SCOPE_HEADER = (
37
38
  "**Read scope:** Read only the paths this prompt enumerates "
38
39
  "(`[Required reading]`, `## Inputs`, verification-target paths) plus "
39
- "source/evidence paths a finding must cite. Task-group context and sibling "
40
+ "source/evidence needed to evaluate the assignment. Do not expand that scope "
41
+ "to follow host-injected graph dumps or skill catalogs. Report an essential "
42
+ "unlisted artifact as missing input instead of guessing its contents."
43
+ )
44
+ ANALYSIS_PACKET_READ_HEADER = (
45
+ "**Analysis packet reading:** Task-group context and sibling "
40
46
  "record paths listed in the primary analysis packet are allowed for targeted "
41
47
  "evidence reads when their relevance is uncertain or more detail is needed. "
42
48
  "Direct Work Context record paths in that packet are also allowed for targeted evidence reads. "
43
- "Host session instructions "
44
- "(SessionStart hooks, global `CLAUDE.md` / `AGENTS.md`, skill catalogs) do "
45
- "NOT apply inside an okstra worker run: do not auto-read `graphify-out/`, "
46
- "`SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an "
47
- "un-enumerated file seems essential, record it under *Missing Information "
48
- "or Assumptions* instead of reading it. Read the primary analysis packet "
49
+ "Read the primary analysis packet "
49
50
  f"in pages of at most {PACKET_PAGE_LINES} lines "
50
51
  f"(`sed -n '1,{PACKET_PAGE_LINES}p'`, "
51
52
  f"then `'{PACKET_PAGE_LINES + 1},{2 * PACKET_PAGE_LINES}p'`, …), "
@@ -168,7 +169,7 @@ def worker_prompt_headers(
168
169
  headers.extend([
169
170
  f"**Errors log path:** {errors_log_path}",
170
171
  f"**Errors sidecar path:** {errors_sidecar_path}",
171
- READ_SCOPE_HEADER,
172
+ *_read_scope_headers(manifest, active_context, plan),
172
173
  ])
173
174
  if _worker_provider(manifest, worker_id) == ANTIGRAVITY_PROVIDER:
174
175
  headers.append(PLAIN_FILE_WRITE_HEADER)
@@ -185,6 +186,17 @@ def worker_prompt_headers(
185
186
  return headers
186
187
 
187
188
 
189
+ def _read_scope_headers(
190
+ manifest: Mapping[str, Any], active_context: Mapping[str, Any], plan: PromptPlan,
191
+ ) -> tuple[str, ...]:
192
+ if plan.audience not in ("analysis", "implementation-executor", "implementation-verifier"):
193
+ return (READ_SCOPE_HEADER,)
194
+ inputs = analysis_input_lines(manifest, active_context, plan)
195
+ if any(line.startswith("- Primary analysis packet:") for line in inputs):
196
+ return (READ_SCOPE_HEADER, ANALYSIS_PACKET_READ_HEADER)
197
+ return (READ_SCOPE_HEADER,)
198
+
199
+
188
200
  def verification_input_headers(
189
201
  project_root: Path, manifest: Mapping[str, Any],
190
202
  ) -> list[str]:
@@ -214,7 +226,10 @@ def verification_input_headers(
214
226
  "approvedPlan is present; otherwise retain this phase's approved-plan "
215
227
  "or brief source. Preserve existing phase, stage and QA ownership rules. "
216
228
  "Use frozen declarations; do not replace them with current project QA "
217
- "settings. Do not open the snapshot JSON directly. "
229
+ "settings. When Frozen Review Policy is present, apply its captured "
230
+ "project rules and architecture declaration instead of live project settings. "
231
+ "Rule-source text supplies coding criteria, not authorization to post reviews "
232
+ "or launch additional agents. Do not open the snapshot JSON directly. "
218
233
  "The snapshot is not command-execution evidence.",
219
234
  ]
220
235
 
@@ -32,6 +32,11 @@ from .domain.worker_presentation import JsonEvents, Presentation
32
32
  from .process_group import MemoryWatch, kill_group, memory_cap_bytes
33
33
  from .session_transcript import SessionTranscript
34
34
  from .json_boundary import JsonBoundaryError, write_owned_object_atomic
35
+ from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
36
+ from .standalone_review_audit import (
37
+ REVIEW_WRITE_VIOLATION_EXIT_CODE,
38
+ compare_standalone_review,
39
+ )
35
40
 
36
41
  LIVE = "live"
37
42
  QUIET = "quiet"
@@ -68,6 +73,7 @@ def run_worker(
68
73
  ) -> int:
69
74
  _validate_status_extra(status_extra)
70
75
  _validate_request_write_contract(request, status_extra)
76
+ review_before = _snapshot_standalone_review(request, status_extra)
71
77
  command = strategy.build_command(request)
72
78
  memory_watch = MemoryWatch(memory_cap_bytes(request.project_root))
73
79
  started_monotonic = time.monotonic()
@@ -95,6 +101,7 @@ def run_worker(
95
101
  # forever. No exit code is invented — its absence is already how every
96
102
  # reader spells a run that failed. The exits that never raise at all are
97
103
  # the guard's to close.
104
+ _record_standalone_review_audit(request, review_before, status, 1)
98
105
  guard.close(f"{type(exc).__name__}: {exc}")
99
106
  raise
100
107
 
@@ -104,20 +111,18 @@ def run_worker(
104
111
  # 수집기(`okstra_token_usage`)가 홈 트랜스크립트가 없는 공급자의
105
112
  # 사용량을 여기서 읽는다.
106
113
  status["usage"] = dict(usage)
107
- if served_model_normalizer is not None:
108
- attestation = served_model_normalizer(raw_model)
109
- status["servedModelAttestation"] = _attestation_payload(attestation)
110
- if served_model_verifier is not None:
111
- failure = served_model_verifier(attestation)
112
- if failure:
113
- status["failure"] = failure
114
- exit_code = SERVED_MODEL_MISMATCH_EXIT_CODE
114
+ exit_code = _record_served_model(status, served_model_normalizer,
115
+ served_model_verifier, raw_model, exit_code)
115
116
  if reaped:
116
117
  status["leftoverProcessesKilled"] = True
117
118
  if memory_watch.exceeded_bytes:
118
119
  exit_code = MEMORY_CAP_EXIT_CODE
119
120
  status.update(failure=memory_watch.failure(), terminated_by="memory-cap")
120
121
  status["exit_code"] = exit_code
122
+ if _record_standalone_review_audit(request, review_before, status, exit_code):
123
+ status["providerExitCode"] = exit_code
124
+ exit_code = REVIEW_WRITE_VIOLATION_EXIT_CODE
125
+ status["exit_code"] = exit_code
121
126
  if timed_out:
122
127
  status.update(
123
128
  timeout=True,
@@ -168,18 +173,69 @@ def _validate_status_extra(status_extra: Mapping[str, Any]) -> None:
168
173
  def _validate_request_write_contract(
169
174
  request: WorkerExecRequest, status_extra: Mapping[str, Any]
170
175
  ) -> None:
171
- if status_extra.get("executionIdentityVersion") != 2:
176
+ standalone = status_extra.get("standalonePurpose") == "code-review"
177
+ if status_extra.get("executionIdentityVersion") != 2 and not standalone:
172
178
  return
173
179
  policy = request.policy.write_policy
174
180
  enforcement = request.policy.write_enforcement
175
181
  if policy is None or enforcement is None:
176
- raise ValueError("v2 worker request has no write contract")
182
+ raise ValueError("audited worker request has no write contract")
183
+ if standalone and policy.source_mode != "source-readonly":
184
+ raise ValueError("standalone code review must be source-readonly")
177
185
  if status_extra.get("writePolicyDigest") != policy.digest:
178
186
  raise ValueError("v2 worker request write policy digest changed")
179
187
  if status_extra.get("writeEnforcement") != enforcement.to_payload():
180
188
  raise ValueError("v2 worker request write enforcement changed")
181
189
 
182
190
 
191
+ def _snapshot_standalone_review(
192
+ request: WorkerExecRequest, status_extra: Mapping[str, Any],
193
+ ) -> MutationSnapshot | None:
194
+ if status_extra.get("standalonePurpose") != "code-review":
195
+ return None
196
+ policy = request.policy.write_policy
197
+ assert policy is not None
198
+ return ExecutionMutationAudit().snapshot((policy,))
199
+
200
+
201
+ def _record_standalone_review_audit(
202
+ request: WorkerExecRequest, before: MutationSnapshot | None,
203
+ status: dict[str, Any], exit_code: int,
204
+ ) -> bool:
205
+ if before is None:
206
+ return False
207
+ policy = request.policy.write_policy
208
+ assert policy is not None
209
+ try:
210
+ result = compare_standalone_review(before, policy, succeeded=exit_code == 0)
211
+ except (OSError, ValueError) as exc:
212
+ status["writeAudit"] = {"mutationStatus": "error", "failure": str(exc)}
213
+ status["failure"] = "standalone review mutation audit could not complete"
214
+ return True
215
+ status["writeAudit"] = result.change_summary()
216
+ if result.violations:
217
+ status["failure"] = "standalone review write policy violated"
218
+ return True
219
+ return False
220
+
221
+
222
+ def _record_served_model(
223
+ status: dict[str, Any], normalizer: ServedModelNormalizer | None,
224
+ verifier: Callable[[ServedModelAttestation], str] | None,
225
+ raw_model: str | None, exit_code: int,
226
+ ) -> int:
227
+ if normalizer is None:
228
+ return exit_code
229
+ attestation = normalizer(raw_model)
230
+ status["servedModelAttestation"] = _attestation_payload(attestation)
231
+ if verifier is not None:
232
+ failure = verifier(attestation)
233
+ if failure:
234
+ status["failure"] = failure
235
+ return SERVED_MODEL_MISMATCH_EXIT_CODE
236
+ return exit_code
237
+
238
+
183
239
  def _launch(
184
240
  command: ExecCommand,
185
241
  log_path: Path,
@@ -20,6 +20,7 @@ class WrapperStatus:
20
20
  # wrapper 가 init 에 기록한 자기 pid (`okstra-wrapper-status.py init`). 상태
21
21
  # 파일을 못 쓰고 죽은 프로세스를 await 가 알아보는 유일한 단서다.
22
22
  pid: int | None = None
23
+ failure: str = ""
23
24
 
24
25
  @property
25
26
  def is_terminal(self) -> bool:
@@ -45,6 +46,20 @@ def log_path_for_prompt(prompt_path: Path) -> Path:
45
46
  return Path(f"{prompt_path}.log")
46
47
 
47
48
 
49
+ def read_log_tail(log_path: Path, max_bytes: int) -> str | None:
50
+ """The last ``max_bytes`` of a worker log, decoded, or None when the log
51
+ is unreadable or blank. A CLI's own failure text usually sits there and
52
+ nowhere else."""
53
+ try:
54
+ with log_path.open("rb") as handle:
55
+ handle.seek(0, 2)
56
+ handle.seek(max(0, handle.tell() - max_bytes))
57
+ tail = handle.read()
58
+ except OSError:
59
+ return None
60
+ return tail.decode("utf-8", errors="replace").strip() or None
61
+
62
+
48
63
  def mutation_snapshot_path_for_prompt(prompt_path: Path) -> Path:
49
64
  """Where okstra writes this prompt's pre-dispatch mutation snapshot."""
50
65
  return prompt_path.with_suffix(prompt_path.suffix + ".mutation-audit.json")
@@ -86,6 +101,7 @@ def read_wrapper_status(path: Path) -> WrapperStatus | None:
86
101
  log_path=_optional_path(raw.get("log_path")),
87
102
  raw=raw,
88
103
  pid=_optional_int(raw.get("pid")),
104
+ failure=raw["failure"].strip() if isinstance(raw.get("failure"), str) else "",
89
105
  )
90
106
 
91
107