okstra 0.227.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 (74) hide show
  1. package/README.md +1 -1
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/docs/architecture/storage-model.md +77 -0
  5. package/docs/cli.md +15 -3
  6. package/docs/project-structure-overview.md +12 -2
  7. package/package.json +1 -1
  8. package/runtime/BUILD.json +2 -2
  9. package/runtime/prompts/duties/code-reviewer.json +1 -0
  10. package/runtime/prompts/lead/convergence.md +5 -19
  11. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  12. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  13. package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
  14. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
  15. package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
  16. package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
  17. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
  18. package/runtime/python/okstra_ctl/brief_sources.py +162 -44
  19. package/runtime/python/okstra_ctl/code_review_coverage.py +11 -1
  20. package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
  21. package/runtime/python/okstra_ctl/code_review_target.py +46 -10
  22. package/runtime/python/okstra_ctl/conformance.py +9 -3
  23. package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
  24. package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
  25. package/runtime/python/okstra_ctl/fixed_text.py +31 -9
  26. package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
  27. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
  28. package/runtime/python/okstra_ctl/json_registry.py +3 -18
  29. package/runtime/python/okstra_ctl/manager_split.py +201 -84
  30. package/runtime/python/okstra_ctl/model_io/references.py +31 -1
  31. package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
  32. package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
  33. package/runtime/python/okstra_ctl/path_hints.py +13 -1
  34. package/runtime/python/okstra_ctl/paths.py +4 -0
  35. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
  36. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
  37. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
  38. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
  39. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +3 -1
  40. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
  41. package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
  42. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
  43. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  44. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
  45. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/plan_items.py +9 -11
  47. package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
  48. package/runtime/python/okstra_ctl/prior_planning.py +6 -17
  49. package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
  50. package/runtime/python/okstra_ctl/qa_commands.py +66 -1
  51. package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
  52. package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
  53. package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
  54. package/runtime/python/okstra_ctl/render.py +10 -0
  55. package/runtime/python/okstra_ctl/report_assembly.py +12 -12
  56. package/runtime/python/okstra_ctl/run.py +108 -5
  57. package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
  58. package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
  59. package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
  60. package/runtime/python/okstra_ctl/verification_plan.py +116 -0
  61. package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
  62. package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
  63. package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
  64. package/runtime/python/okstra_project/dirs.py +22 -0
  65. package/runtime/python/okstra_project/resolver.py +10 -0
  66. package/runtime/schemas/final-report-v3.0.schema.json +5 -1
  67. package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
  68. package/runtime/skills/okstra-code-review/SKILL.md +39 -45
  69. package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
  70. package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
  71. package/runtime/skills/okstra-manager/SKILL.md +2 -2
  72. package/runtime/skills/okstra-setup/SKILL.md +2 -0
  73. package/runtime/skills/okstra-setup/references/project-config.md +2 -0
  74. package/runtime/validators/validate-brief.py +21 -5
@@ -0,0 +1,162 @@
1
+ """Preparation must allow inspection scripts that implementation creates later."""
2
+ from __future__ import annotations
3
+
4
+ from pathlib import Path
5
+ from typing import Any, Mapping, cast
6
+
7
+ from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
8
+
9
+ from .json_boundary import load_owned_object_snapshot, write_owned_object_atomic
10
+ from .paths import RunRef
11
+ from .qa_commands import QA_COMMAND_EXECUTING_TASK_TYPES, validate_qa_commands
12
+ from .qa_procedures import (
13
+ content_digest, existing_qa_file, load_qa_config, procedure_root,
14
+ read_validated_procedure, safe_qa_path, validate_procedure_sections,
15
+ )
16
+
17
+ from .verification_input_types import (
18
+ INPUT_KIND, INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION,
19
+ FrozenProcedure, VerificationInputs,
20
+ )
21
+ from .verification_plan import (
22
+ VERIFICATION_PLAN_SCHEMA, capture_verification_plan, verification_plan_errors,
23
+ )
24
+
25
+ INPUT_ARTIFACT = "verification inputs"
26
+ QA_INPUT_FIELDS = (
27
+ "label", "cmd", "id", "procedurePath", "sourcePaths", "resourceKeys",
28
+ "sourceBaselineDigest",
29
+ )
30
+
31
+
32
+ INPUT_SCHEMA = {
33
+ "type": "object",
34
+ "additionalProperties": False,
35
+ "required": ["schemaVersion", "kind", "sourceRoot", "qaCommands", "procedures"],
36
+ "properties": {
37
+ "schemaVersion": {"enum": [INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION]},
38
+ "kind": {"const": INPUT_KIND},
39
+ "sourceRoot": {"type": "string", "minLength": 1},
40
+ "qaCommands": {"type": "object"},
41
+ "procedures": {"type": "object"},
42
+ "approvedPlan": VERIFICATION_PLAN_SCHEMA,
43
+ },
44
+ }
45
+
46
+
47
+ def _procedure_paths(commands: Mapping[str, list[dict[str, Any]]]) -> tuple[str, ...]:
48
+ return tuple(dict.fromkeys(
49
+ entry["procedurePath"]
50
+ for entries in commands.values()
51
+ for entry in entries
52
+ if entry.get("procedurePath")
53
+ ))
54
+
55
+
56
+ def _verification_input_errors(payload: dict[str, Any]) -> list[str]:
57
+ has_plan = "approvedPlan" in payload
58
+ if payload["schemaVersion"] == PLAN_INPUT_SCHEMA_VERSION and not has_plan:
59
+ return ["verification inputs 2.0 requires approvedPlan"]
60
+ if payload["schemaVersion"] == INPUT_SCHEMA_VERSION and has_plan:
61
+ return ["legacy verification inputs must not contain approvedPlan"]
62
+ if has_plan:
63
+ errors = verification_plan_errors(payload["approvedPlan"])
64
+ if errors:
65
+ return errors
66
+ commands = payload["qaCommands"]
67
+ errors = validate_qa_commands(commands)
68
+ if errors:
69
+ return errors
70
+ if any(set(entry).difference(QA_INPUT_FIELDS)
71
+ for entries in commands.values() for entry in entries):
72
+ errors.append("unsupported QA declaration fields in verification inputs")
73
+ if not Path(payload["sourceRoot"]).is_absolute():
74
+ errors.append("verification source root must be absolute")
75
+ procedures = payload["procedures"]
76
+ if set(_procedure_paths(commands)) != set(procedures):
77
+ errors.append("frozen procedure references must match qaCommands")
78
+ for relative, procedure in procedures.items():
79
+ if (not isinstance(procedure, dict)
80
+ or set(procedure) != {"body", "digest"}
81
+ or not all(isinstance(value, str) for value in procedure.values())):
82
+ errors.append(
83
+ f"invalid frozen procedure {relative}: expected body and digest strings"
84
+ )
85
+ continue
86
+ try:
87
+ raw = procedure["body"].encode("utf-8")
88
+ validate_procedure_sections(raw)
89
+ except ValueError as exc:
90
+ errors.append(f"invalid frozen procedure {relative}: {exc}")
91
+ continue
92
+ if content_digest(raw) != procedure["digest"]:
93
+ errors.append(f"frozen procedure digest mismatch: {relative}")
94
+ return errors
95
+
96
+
97
+ def capture_verification_inputs(
98
+ project: Path, source: Path, *, approved_plan: Path | None = None,
99
+ ) -> VerificationInputs:
100
+ declared = load_qa_config(project).get("qaCommands") or {}
101
+ commands = {
102
+ category: [{key: entry[key] for key in QA_INPUT_FIELDS if key in entry}
103
+ for entry in entries]
104
+ for category, entries in declared.items()
105
+ }
106
+ procedures: dict[str, FrozenProcedure] = {}
107
+ for relative in _procedure_paths(commands):
108
+ root = procedure_root(project, source, relative)
109
+ try:
110
+ raw = read_validated_procedure(existing_qa_file(root, relative))
111
+ except (OSError, ValueError) as exc:
112
+ raise ValueError(f"verification procedure {relative}: {exc}") from exc
113
+ procedures[relative] = {
114
+ "body": raw.decode("utf-8"), "digest": content_digest(raw),
115
+ }
116
+ payload: VerificationInputs = {
117
+ "schemaVersion": INPUT_SCHEMA_VERSION, "kind": INPUT_KIND,
118
+ "sourceRoot": str(source.resolve()), "qaCommands": commands,
119
+ "procedures": procedures,
120
+ }
121
+ if approved_plan is not None:
122
+ payload["schemaVersion"] = PLAN_INPUT_SCHEMA_VERSION
123
+ payload["approvedPlan"] = capture_verification_plan(approved_plan)
124
+ return payload
125
+
126
+
127
+ def read_verification_inputs(path: Path, expected_digest: str) -> VerificationInputs:
128
+ snapshot = load_owned_object_snapshot(
129
+ path, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
130
+ validate_cross_fields=_verification_input_errors,
131
+ )
132
+ if content_digest(snapshot.raw_bytes) != expected_digest:
133
+ raise ValueError("verification input digest mismatch")
134
+ return cast(VerificationInputs, snapshot.value)
135
+
136
+
137
+ def prepare_verification_inputs(
138
+ project: Path, source: Path, ref: RunRef, *, approved_plan: Path | None = None,
139
+ ) -> tuple[Path, str]:
140
+ if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
141
+ raise ValueError("verification inputs require a QA-executing phase")
142
+ destination = ref.verification_inputs.absolute()
143
+ project_root = project.absolute()
144
+ if not destination.is_relative_to(project_root / OKSTRA_DIR_NAME):
145
+ raise ValueError("verification inputs must remain in the project artifact tree")
146
+ artifact_relative = destination.relative_to(project_root)
147
+ path = safe_qa_path(project, artifact_relative.as_posix())
148
+ lock = safe_qa_path(project, json_lock_path(artifact_relative).as_posix())
149
+ payload = capture_verification_inputs(project, source, approved_plan=approved_plan)
150
+ with registry_lock(lock):
151
+ if not path.exists():
152
+ write_owned_object_atomic(
153
+ path, payload, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
154
+ validate_cross_fields=_verification_input_errors,
155
+ )
156
+ snapshot = load_owned_object_snapshot(
157
+ path, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
158
+ validate_cross_fields=_verification_input_errors,
159
+ )
160
+ if snapshot.value != payload:
161
+ raise ValueError("verification input snapshot is immutable")
162
+ return path, content_digest(snapshot.raw_bytes)
@@ -0,0 +1,116 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from typing import Any, cast
5
+
6
+ from .conformance import CAPABILITY_WHITELIST, parse_conformance_tests
7
+ from .final_report_paths import is_report_record_path, require_approved_plan_record
8
+ from .final_report_schema import json_schema_number_key, load_schema_version, validate
9
+ from .json_boundary import load_owned_object_snapshot
10
+ from .qa_procedures import content_digest
11
+ from .verification_input_types import FrozenVerificationPlan
12
+
13
+ VERIFICATION_PLAN_SCHEMA = {
14
+ "type": "object", "additionalProperties": False,
15
+ "required": ["path", "digest", "reportSchemaVersion",
16
+ "validationChecklist", "conformance"],
17
+ "properties": {
18
+ "path": {"type": "string", "minLength": 1},
19
+ "digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
20
+ "reportSchemaVersion": {"enum": ["2.0", "3.0"]},
21
+ "validationChecklist": {"type": "array"},
22
+ "conformance": {"type": "array", "items": {
23
+ "type": "object", "additionalProperties": False,
24
+ "required": ["stage"],
25
+ "properties": {
26
+ "stage": {"type": "integer", "minimum": 1},
27
+ "script": {"type": "string", "minLength": 1},
28
+ "requires": {"type": "array", "minItems": 1,
29
+ "uniqueItems": True,
30
+ "items": {"enum": list(CAPABILITY_WHITELIST)}},
31
+ "exemption": {"type": "string", "minLength": 1},
32
+ },
33
+ "oneOf": [
34
+ {"required": ["script", "requires"],
35
+ "not": {"required": ["exemption"]}},
36
+ {"required": ["exemption"],
37
+ "properties": {"script": False, "requires": False}},
38
+ ],
39
+ }},
40
+ },
41
+ }
42
+
43
+
44
+ def verification_plan_errors(plan: dict[str, Any]) -> list[str]:
45
+ errors = validate(plan, VERIFICATION_PLAN_SCHEMA)
46
+ if errors:
47
+ return errors
48
+ if not Path(plan["path"]).is_absolute():
49
+ return ["approved plan path must be absolute"]
50
+ if not is_report_record_path(Path(plan["path"])):
51
+ return ["approved plan path must name a .data.json record"]
52
+ report_schema = load_schema_version(plan["reportSchemaVersion"])
53
+ errors = validate(plan["validationChecklist"], {
54
+ "$defs": report_schema["$defs"], "type": "array",
55
+ "items": {"$ref": "#/$defs/ValidationCheckRow"},
56
+ })
57
+ if errors:
58
+ return errors
59
+ ids = [row["id"] for row in plan["validationChecklist"]]
60
+ stage_keys = [json_schema_number_key(row["stage"]) for row in plan["conformance"]]
61
+ if len(ids) != len(set(ids)):
62
+ errors.append("duplicate validation check identity in approved plan")
63
+ if len(stage_keys) != len(set(stage_keys)):
64
+ errors.append("duplicate conformance stage in approved plan")
65
+ for row in plan["conformance"]:
66
+ if "script" in row:
67
+ parsed = parse_conformance_tests(
68
+ f"{row['script']} (requires=[{','.join(row['requires'])}])"
69
+ )
70
+ if parsed is None or parsed[0] != row["script"]:
71
+ errors.append("invalid frozen conformance script declaration")
72
+ elif not row["exemption"].strip():
73
+ errors.append("frozen conformance exemption must be non-blank")
74
+ return errors
75
+
76
+
77
+ def _conformance_expectations(stages: object) -> list[dict[str, Any]]:
78
+ if not isinstance(stages, list):
79
+ raise ValueError("approved plan stages must be an array")
80
+ rows: list[dict[str, Any]] = []
81
+ for stage in stages:
82
+ if not isinstance(stage, dict):
83
+ raise ValueError("approved plan stage must be an object")
84
+ if "conformanceTests" in stage and "conformanceExemption" in stage:
85
+ raise ValueError(
86
+ "approved plan conformance declares both test and exemption"
87
+ )
88
+ if "conformanceTests" in stage:
89
+ parsed = parse_conformance_tests(stage["conformanceTests"])
90
+ if parsed is None:
91
+ raise ValueError("approved plan has malformed conformanceTests")
92
+ script, requires = parsed
93
+ rows.append({"stage": stage.get("stage"), "script": script,
94
+ "requires": sorted(requires)})
95
+ elif "conformanceExemption" in stage:
96
+ rows.append({"stage": stage.get("stage"),
97
+ "exemption": stage["conformanceExemption"]})
98
+ return rows
99
+
100
+
101
+ def capture_verification_plan(path: Path) -> FrozenVerificationPlan:
102
+ path = require_approved_plan_record(path).resolve()
103
+ snapshot = load_owned_object_snapshot(path, artifact="approved verification plan")
104
+ planning = snapshot.value.get("implementationPlanning")
105
+ if not isinstance(planning, dict):
106
+ raise ValueError("approved plan has no implementationPlanning object")
107
+ plan = {
108
+ "path": str(path), "digest": content_digest(snapshot.raw_bytes),
109
+ "reportSchemaVersion": snapshot.value.get("schemaVersion"),
110
+ "validationChecklist": planning.get("validationChecklist", []),
111
+ "conformance": _conformance_expectations(planning.get("stages", [])),
112
+ }
113
+ errors = verification_plan_errors(plan)
114
+ if errors:
115
+ raise ValueError(f"approved verification plan: {errors[0]}")
116
+ return cast(FrozenVerificationPlan, plan)
@@ -72,14 +72,20 @@ def analysis_input_lines(
72
72
  # The packet already carries the brief extract, the reference
73
73
  # expectations, the profile prelude and the directive; the task brief,
74
74
  # analysis material, profile and reference files repeat them in full.
75
- # Measured 2026-10-30 (dev-11562): those four files were 1,929 lines
76
- # beside a 4,865-line packet. The clarification file stays: the
77
- # packet keeps only its extract, and a lazy-delivery prompt has no
78
- # inlined authority block.
75
+ # The clarification file stays: the packet keeps only its extract, and
76
+ # a lazy-delivery prompt has no inlined authority block.
79
77
  return existing_input_lines((
80
- ("Primary analysis packet", instruction_path(manifest, active_context, "analysisPacketPath")),
78
+ (
79
+ "Primary analysis packet",
80
+ instruction_path(manifest, active_context, "analysisPacketPath"),
81
+ ),
81
82
  ("Approved plan stage extract", stage_extract_path),
82
- ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
83
+ (
84
+ "Clarification response",
85
+ instruction_path(
86
+ manifest, active_context, "clarificationResponsePath"
87
+ ),
88
+ ),
83
89
  ))
84
90
  if plan.packet_only:
85
91
  packet_path = instruction_path(manifest, active_context, "analysisPacketPath")
@@ -25,7 +25,10 @@ from .worker_prompt_policy import (
25
25
  resolve_prompt_plan_for_manifest,
26
26
  verification_dispatch_round,
27
27
  )
28
- from .worker_prompt_headers import EVIDENCE_LEDGER_HEADER
28
+ from .worker_prompt_headers import (
29
+ EVIDENCE_LEDGER_HEADER,
30
+ VERIFICATION_INPUT_HEADER_PREFIXES,
31
+ )
29
32
 
30
33
 
31
34
  MAX_FINAL_VERIFICATION_DIRECTIVE_LINES = 40
@@ -76,6 +79,7 @@ _NON_BODY_PREFIXES = (
76
79
  "**Verification head ref:**",
77
80
  "**Verification target path:**",
78
81
  "**Verification target digest:**",
82
+ *VERIFICATION_INPUT_HEADER_PREFIXES,
79
83
  PROMPT_DELIVERY_MODE_HEADER,
80
84
  )
81
85
  _REQUIRED_TARGET_PREFIXES = (
@@ -2,9 +2,13 @@
2
2
  from __future__ import annotations
3
3
 
4
4
  from pathlib import Path
5
+ import shlex
5
6
  from typing import Any, Mapping
6
7
 
8
+ from .analysis_packet import PACKET_PAGE_LINES
9
+ from .fixed_text import block
7
10
  from .paths import okstra_home
11
+ from .verification_input_ref import VerificationInputReference
8
12
  from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
9
13
  from .worker_prompt_policy import (
10
14
  GRILLING_LOG_HEADER,
@@ -42,12 +46,22 @@ READ_SCOPE_HEADER = (
42
46
  "`SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an "
43
47
  "un-enumerated file seems essential, record it under *Missing Information "
44
48
  "or Assumptions* instead of reading it. Read the primary analysis packet "
45
- "in pages of at most 200 lines (`sed -n '1,200p'`, then `'201,400p'`, …), "
49
+ f"in pages of at most {PACKET_PAGE_LINES} lines "
50
+ f"(`sed -n '1,{PACKET_PAGE_LINES}p'`, "
51
+ f"then `'{PACKET_PAGE_LINES + 1},{2 * PACKET_PAGE_LINES}p'`, …), "
46
52
  "never with one whole-file `cat` or view: worker CLIs cut long output "
47
53
  "without saying so, and the packet's `## Section Index` gives each "
48
54
  "section's line range."
49
55
  )
50
56
  EVIDENCE_LEDGER_HEADER = "**Evidence ledger:** required-v1"
57
+ VERIFICATION_INPUT_PATH_HEADER = "**Verification inputs:**"
58
+ VERIFICATION_INPUT_DIGEST_HEADER = "**Verification inputs digest:**"
59
+ VERIFICATION_INPUT_SOURCE_HEADER = "**Verification input source:**"
60
+ VERIFICATION_INPUT_HEADER_PREFIXES = (
61
+ VERIFICATION_INPUT_PATH_HEADER,
62
+ VERIFICATION_INPUT_DIGEST_HEADER,
63
+ VERIFICATION_INPUT_SOURCE_HEADER,
64
+ )
51
65
 
52
66
  # `required-v1` is a mode name; what it demands lives in the Worker Preamble's
53
67
  # "Evidence read ledger". But the preamble reaches the worker as a *path* —
@@ -167,9 +181,44 @@ def worker_prompt_headers(
167
181
  headers.extend(_final_verification_target_headers(active_context))
168
182
  else:
169
183
  headers.extend(source_worktree_headers(active_context))
184
+ headers.extend(verification_input_headers(project_root, manifest))
170
185
  return headers
171
186
 
172
187
 
188
+ def verification_input_headers(
189
+ project_root: Path, manifest: Mapping[str, Any],
190
+ ) -> list[str]:
191
+ try:
192
+ reference = VerificationInputReference.from_artifact_fields(manifest)
193
+ except ValueError as exc:
194
+ raise WorkerPromptHeaderError(str(exc)) from exc
195
+ if reference is None:
196
+ return []
197
+ manifest_ref = _string_value(manifest.get("runManifestPath"))
198
+ if not manifest_ref:
199
+ raise WorkerPromptHeaderError(
200
+ "verification input reference requires runManifestPath for projection"
201
+ )
202
+ command = shlex.join([
203
+ "okstra", "model-io", "verification-input", "--run-manifest",
204
+ str(project_root / manifest_ref),
205
+ ])
206
+ return [
207
+ f"{VERIFICATION_INPUT_PATH_HEADER} "
208
+ f"{block(str(project_root / reference.relative_path))}",
209
+ f"{VERIFICATION_INPUT_DIGEST_HEADER} {block(reference.digest)}",
210
+ f"{VERIFICATION_INPUT_SOURCE_HEADER} "
211
+ f"Read frozen declarations with `{block(command)}`. "
212
+ "Read Tier 2 qaCommands from Verification inputs, including an empty "
213
+ "collection. Read Tier 1 from approvedPlan.validationChecklist when "
214
+ "approvedPlan is present; otherwise retain this phase's approved-plan "
215
+ "or brief source. Preserve existing phase, stage and QA ownership rules. "
216
+ "Use frozen declarations; do not replace them with current project QA "
217
+ "settings. Do not open the snapshot JSON directly. "
218
+ "The snapshot is not command-execution evidence.",
219
+ ]
220
+
221
+
173
222
  def source_worktree_headers(active_context: Mapping[str, Any]) -> list[str]:
174
223
  worktree = active_context.get("executorWorktree")
175
224
  path = _string_value(worktree.get("path")) if isinstance(worktree, Mapping) else ""
@@ -14,9 +14,12 @@ DRY 위반의 비용: 이전에는 동일 path 문자열이 50+ Python·Shell·m
14
14
  """
15
15
  from __future__ import annotations
16
16
 
17
+ import contextlib
18
+ import fcntl
17
19
  import os
18
20
  import sys
19
21
  import tempfile
22
+ from collections.abc import Iterator
20
23
  from pathlib import Path
21
24
 
22
25
  OKSTRA_DIR_NAME = ".okstra"
@@ -114,3 +117,22 @@ def tasks_root(project_root: Path) -> Path:
114
117
  def discovery_dir(project_root: Path) -> Path:
115
118
  """`<project_root>/.okstra/discovery` 절대 path."""
116
119
  return Path(project_root) / DISCOVERY_RELATIVE
120
+
121
+
122
+ def json_lock_path(path: Path) -> Path:
123
+ return path.with_suffix(path.suffix + ".lock")
124
+
125
+
126
+ @contextlib.contextmanager
127
+ def registry_lock(lock_path: Path) -> Iterator[None]:
128
+ """Hold an exclusive flock on ``lock_path``."""
129
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
130
+ if not lock_path.exists():
131
+ lock_path.touch()
132
+ handle = lock_path.open("r+")
133
+ try:
134
+ fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
135
+ yield
136
+ finally:
137
+ fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
138
+ handle.close()
@@ -12,7 +12,9 @@ from .dirs import (
12
12
  OKSTRA_DIR_NAME,
13
13
  PROJECT_JSON_RELATIVE,
14
14
  ensure_okstra_gitignore,
15
+ json_lock_path,
15
16
  project_json_path,
17
+ registry_lock,
16
18
  )
17
19
 
18
20
 
@@ -152,6 +154,14 @@ def upsert_project_json(project_root: Path, project_id: str, *,
152
154
  - 파일이 없으면 디렉터리를 만들고 4-필드 JSON 을 작성한다.
153
155
  반환값은 결과 dict.
154
156
  """
157
+ lock_path = json_lock_path(project_json_path(project_root))
158
+ with registry_lock(lock_path):
159
+ return _upsert_project_json(project_root, project_id, now=now)
160
+
161
+
162
+ def _upsert_project_json(
163
+ project_root: Path, project_id: str, *, now: str | None = None,
164
+ ) -> dict:
155
165
  if not project_id:
156
166
  raise ResolverError("project_id is required for upsert_project_json")
157
167
  target = project_json_path(project_root)
@@ -3944,7 +3944,7 @@
3944
3944
  },
3945
3945
  "ImplementationOptionSplitAcceptance": {
3946
3946
  "type": "object",
3947
- "description": "The user's accept-risk answer that settles a split feasibility vote. Report assembly checks that clarificationRef names a blocks: approval row answered with accept-risk.",
3947
+ "description": "The user's accept-risk answer that settles a split feasibility vote. Report assembly checks that clarificationRef names a blocks: approval row whose candidateRef is this candidate and that the user answered with accept-risk.",
3948
3948
  "required": ["clarificationRef"],
3949
3949
  "additionalProperties": false,
3950
3950
  "properties": {
@@ -10957,6 +10957,10 @@
10957
10957
  "approvalContext": {
10958
10958
  "$ref": "#/$defs/ApprovalContext"
10959
10959
  },
10960
+ "candidateRef": {
10961
+ "description": "The implementation option this approval decides. A candidate's splitAcceptance may cite only a row whose candidateRef is that candidate's id.",
10962
+ "$ref": "#/$defs/ImplementationOptionId"
10963
+ },
10960
10964
  "resolution": {
10961
10965
  "$ref": "#/$defs/ApprovalResolution"
10962
10966
  }
@@ -195,7 +195,11 @@ for every variant and every source type below.
195
195
  the task worktree is a checkout without that file, and prepare copies it
196
196
  read-only into the analysis packet's `## Cited Local Documents` on every
197
197
  run, so later revisions of the document reach the next phase. A tracked
198
- file is in the worktree; capture it as-is per rule 1.
198
+ file is in the worktree; capture it as-is per rule 1. Check the size
199
+ first: prepare does not copy a file over 200,000 bytes
200
+ (`MAX_CITED_DOCUMENT_BYTES` in `scripts/okstra_ctl/analysis_packet.py`)
201
+ and shows workers only a "not read" line for it, so capture a larger
202
+ untracked document as-is per rule 1 instead of by reference.
199
203
 
200
204
  **Enforced:** `validators/validate-brief.py`
201
205
  (`check_cited_local_documents`) refuses a brief that names a git-untracked
@@ -252,9 +256,11 @@ each source's raw content **separately** under the `Source Material
252
256
  Take an absolute or project-relative path via free-text. Read the entire
253
257
  file. Re-ask if it doesn't exist. Captured content is preserved **verbatim**
254
258
  in Source Material.
255
- When the file is under the project root and git does not track it, record
256
- it by reference instead (capture contract rule 4): the entry's `ref` is the
257
- project-relative path, `format: by-reference`, and the fence stays empty.
259
+ When the file is under the project root, git does not track it, and it is
260
+ at most 200,000 bytes, record it by reference instead (capture contract
261
+ rule 4): the entry's `ref` is the project-relative path, `format:
262
+ by-reference`, and the fence stays empty. A larger untracked file stays
263
+ captured verbatim, because prepare does not copy it into the packet.
258
264
 
259
265
  ### 1b. `Issue tracker ticket`
260
266