okstra 0.228.2 → 0.230.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 (124) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +179 -13
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +16 -21
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/bin/okstra-provider-exec.py +53 -4
  16. package/runtime/prompts/duties/code-reviewer.json +5 -2
  17. package/runtime/prompts/launch.template.md +5 -5
  18. package/runtime/prompts/lead/convergence.md +4 -4
  19. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  20. package/runtime/prompts/lead/phase-routing.md +1 -1
  21. package/runtime/prompts/lead/report-writer.md +3 -3
  22. package/runtime/prompts/lead/team-contract.md +3 -3
  23. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  24. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  25. package/runtime/python/okstra_ctl/cmux.py +4 -2
  26. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  27. package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
  28. package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
  29. package/runtime/python/okstra_ctl/code_review_target.py +79 -25
  30. package/runtime/python/okstra_ctl/conformance.py +61 -0
  31. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  32. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  33. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  34. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  35. package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
  36. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  37. package/runtime/python/okstra_ctl/ids.py +1 -41
  38. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  39. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  40. package/runtime/python/okstra_ctl/locks.py +28 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
  42. package/runtime/python/okstra_ctl/paths.py +84 -31
  43. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  44. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  46. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  47. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  48. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  50. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  51. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  53. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  55. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  57. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  58. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  59. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  62. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  63. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  66. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  67. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  68. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  69. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  70. package/runtime/python/okstra_ctl/process_group.py +26 -3
  71. package/runtime/python/okstra_ctl/qa_commands.py +7 -2
  72. package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
  73. package/runtime/python/okstra_ctl/recap.py +1 -2
  74. package/runtime/python/okstra_ctl/render.py +10 -2
  75. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  76. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  77. package/runtime/python/okstra_ctl/run.py +24 -20
  78. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  79. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  80. package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
  81. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  82. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  83. package/runtime/python/okstra_ctl/verification_generation.py +248 -0
  84. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  85. package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
  86. package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
  87. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  88. package/runtime/python/okstra_ctl/verification_target.py +20 -5
  89. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  90. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  91. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  92. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  93. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  94. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  95. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +84 -48
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
  99. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +6 -6
  101. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  102. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  103. package/runtime/validators/validate-run.py +118 -52
  104. package/docs/cli.md +0 -1060
  105. package/docs/container.md +0 -100
  106. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  107. package/docs/performance-improvement-plan-v2.md +0 -369
  108. package/runtime/python/okstra_ctl/container.py +0 -702
  109. package/runtime/python/okstra_ctl/rollup.py +0 -241
  110. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  111. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  112. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  113. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  114. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  115. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  116. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  117. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  118. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  119. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  120. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  121. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  122. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  123. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  124. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -0,0 +1,139 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path, PurePosixPath
5
+ from typing import Any, Iterable, Mapping
6
+
7
+ from okstra_project.dirs import OKSTRA_DIR_NAME
8
+
9
+ from .qa_commands import (
10
+ QA_SOURCE_DIGEST_PATTERN, QA_VERIFIER_AUDIENCE_BY_TASK_TYPE, qa_relative_path_valid,
11
+ )
12
+ from .qa_procedures import safe_qa_path
13
+ from .verification_generation import (
14
+ VERIFICATION_GENERATION_PATH_MAX_LENGTH, VerificationGenerationRecord,
15
+ read_verification_generation,
16
+ )
17
+ from .verification_input_ref import VerificationInputReference
18
+ from .verification_inputs import read_verification_inputs
19
+
20
+ VERIFICATION_GENERATION_HEADER_PREFIXES = (
21
+ "**Verification generation path:**", "**Verification generation digest:**",
22
+ )
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class VerificationGenerationReference:
27
+ path: str
28
+ digest: str
29
+
30
+ def __post_init__(self) -> None:
31
+ if (not isinstance(self.path, str)
32
+ or len(self.path) > VERIFICATION_GENERATION_PATH_MAX_LENGTH
33
+ or _has_c0_control_characters(self.path)
34
+ or self.path.splitlines() != [self.path]
35
+ or not qa_relative_path_valid(self.path)):
36
+ raise ValueError("verification generation path is invalid")
37
+ relative = PurePosixPath(self.path)
38
+ if (relative.parts[0] != OKSTRA_DIR_NAME
39
+ or relative.as_posix() != self.path):
40
+ raise ValueError(
41
+ "verification generation requires a canonical artifact path"
42
+ )
43
+ if (not isinstance(self.digest, str)
44
+ or not QA_SOURCE_DIGEST_PATTERN.fullmatch(self.digest)):
45
+ raise ValueError("verification generation digest is invalid")
46
+
47
+ @classmethod
48
+ def from_payload(cls, value: object) -> VerificationGenerationReference:
49
+ if not isinstance(value, dict) or set(value) != {"path", "digest"}:
50
+ raise ValueError("verification generation requires path and digest")
51
+ return cls(value["path"], value["digest"])
52
+
53
+ def to_payload(self) -> dict[str, str]:
54
+ return {"path": self.path, "digest": self.digest}
55
+
56
+
57
+ def _has_c0_control_characters(value: str) -> bool:
58
+ # A control character could forge an extra header line in the prompt prefix.
59
+ return any(ord(char) < 32 for char in value)
60
+
61
+
62
+ def read_invocation_generation(
63
+ project: Path, manifest_path: Path | None, manifest: Mapping[str, Any],
64
+ reference: VerificationGenerationReference | None, audience: str,
65
+ ) -> VerificationGenerationRecord | None:
66
+ if not _generation_required(manifest, reference, audience):
67
+ return None
68
+ if reference is None or manifest_path is None:
69
+ raise ValueError("verifier invocation requires a verification generation")
70
+ return _read_bound_generation(project, manifest_path, manifest, reference)
71
+
72
+
73
+ def verification_generation_required(
74
+ manifest: Mapping[str, Any], audience: str,
75
+ ) -> bool:
76
+ return _generation_required(manifest, None, audience)
77
+
78
+
79
+ def _generation_required(
80
+ manifest: Mapping[str, Any],
81
+ reference: VerificationGenerationReference | None, audience: str,
82
+ ) -> bool:
83
+ if "verificationEvidenceVersion" not in manifest:
84
+ if reference is not None:
85
+ raise ValueError("verification generation requires evidence contract 1.0")
86
+ return False
87
+ if manifest["verificationEvidenceVersion"] != "1.0":
88
+ raise ValueError("unsupported verification evidence version")
89
+ task_type = manifest.get("taskType")
90
+ if (not isinstance(task_type, str)
91
+ or task_type not in QA_VERIFIER_AUDIENCE_BY_TASK_TYPE):
92
+ raise ValueError("verification evidence requires a QA-executing run")
93
+ if audience != QA_VERIFIER_AUDIENCE_BY_TASK_TYPE[task_type]:
94
+ if reference is not None:
95
+ raise ValueError("verification generation requires a verifier invocation")
96
+ return False
97
+ return True
98
+
99
+
100
+ def _read_bound_generation(
101
+ project: Path, manifest_path: Path, manifest: Mapping[str, Any],
102
+ reference: VerificationGenerationReference,
103
+ ) -> VerificationGenerationRecord:
104
+ task_type = manifest["taskType"]
105
+ project = project.resolve()
106
+ path = safe_qa_path(project, reference.path)
107
+ record = read_verification_generation(path, reference.digest)
108
+ relative_manifest = manifest_path.resolve().relative_to(project).as_posix()
109
+ if (record["runManifestPath"] != relative_manifest
110
+ or record["taskType"] != task_type):
111
+ raise ValueError("verification generation belongs to a different run")
112
+ expected = VerificationInputReference.required_from_artifact_fields(manifest)
113
+ if VerificationInputReference.from_artifact_fields(record) != expected:
114
+ raise ValueError("verification generation input reference differs from run")
115
+ inputs = read_verification_inputs(
116
+ safe_qa_path(project, expected.relative_path), expected.digest,
117
+ )
118
+ if record["sourceRoot"] != inputs["sourceRoot"]:
119
+ raise ValueError("verification generation source differs from frozen inputs")
120
+ return record
121
+
122
+
123
+ def verification_generation_headers(
124
+ reference: VerificationGenerationReference,
125
+ ) -> tuple[str, str]:
126
+ path_prefix, digest_prefix = VERIFICATION_GENERATION_HEADER_PREFIXES
127
+ return (
128
+ f"{path_prefix} {reference.path}",
129
+ f"{digest_prefix} {reference.digest}",
130
+ )
131
+
132
+
133
+ def select_verification_generation_header_lines(
134
+ lines: Iterable[str],
135
+ ) -> tuple[str, ...]:
136
+ return tuple(
137
+ line for line in lines
138
+ if line.startswith(VERIFICATION_GENERATION_HEADER_PREFIXES)
139
+ )
@@ -77,6 +77,25 @@ def read_verification_target(project_root: Path, relative: str) -> dict | None:
77
77
  return parsed
78
78
 
79
79
 
80
+ def read_worktree_head(worktree: Path) -> str:
81
+ return subprocess.check_output(
82
+ ["git", "-C", str(worktree), "rev-parse", "HEAD"], text=True,
83
+ ).strip()
84
+
85
+
86
+ def read_verification_head(worktree: Path, expected_head: str) -> str:
87
+ head = read_worktree_head(worktree)
88
+ actual_root = subprocess.check_output(
89
+ ["git", "-C", str(worktree), "rev-parse", "--show-toplevel"], text=True,
90
+ ).strip()
91
+ if head != expected_head or Path(actual_root).resolve() != worktree:
92
+ raise ValueError(
93
+ f"verification target mismatch: expected HEAD {expected_head}, "
94
+ f"actual {head}, root {actual_root}"
95
+ )
96
+ return head
97
+
98
+
80
99
  def capture_verification_target(
81
100
  project_root: Path, manifest_path: Path, expected_head: str, command: str,
82
101
  ) -> dict:
@@ -106,11 +125,7 @@ def capture_verification_target(
106
125
  defects = verification_command_defects(command)
107
126
  if defects:
108
127
  raise ValueError("; ".join(defects))
109
- git = ["git", "-C", str(worktree), "rev-parse"]
110
- head = subprocess.check_output([*git, "HEAD"], text=True).strip()
111
- actual_root = subprocess.check_output([*git, "--show-toplevel"], text=True).strip()
112
- if head != expected_head or Path(actual_root).resolve() != worktree:
113
- raise ValueError(f"verification target mismatch: expected HEAD {expected_head}, actual {head}, root {actual_root}")
128
+ head = read_verification_head(worktree, expected_head)
114
129
  files = source_content_snapshot(worktree, frozenset({".okstra"}))
115
130
  digest = hashlib.sha256(json.dumps(files, sort_keys=True).encode()).hexdigest()
116
131
  result = {
@@ -24,6 +24,7 @@ from okstra_ctl.phases.implementation_planning.wizard import (
24
24
 
25
25
  from typing import Optional
26
26
 
27
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
27
28
  from .ids import (
28
29
  BRIEF_CARRY_ABORT,
29
30
  BRIEF_CARRY_SWITCH_ENTRY,
@@ -348,7 +349,7 @@ STEPS: list[Step] = [
348
349
  applies=lambda s: (S_TASK_TYPE in s.answered
349
350
  and bool(s.task_type)
350
351
  and s.task_type not in _BRIEF_ENTRY_TASK_TYPES
351
- and s.task_type not in ("release-handoff", "discussion")
352
+ and s.task_type not in INPUT_DOCUMENT_TASK_TYPES
352
353
  and not s.brief_path
353
354
  and not s.brief_path_pending_text),
354
355
  build=_build_brief_carry, submit=_submit_brief_carry,
@@ -11,6 +11,7 @@ from okstra_ctl.wizard_stage_intent import (
11
11
  resolve_wizard_stage_intent,
12
12
  )
13
13
 
14
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
14
15
  from .state import (
15
16
  WizardError,
16
17
  WizardState,
@@ -99,7 +100,7 @@ def render_args(state: WizardState) -> dict[str, Any]:
99
100
  "task-id": state.task_id,
100
101
  "task-type": state.task_type,
101
102
  "task-brief": (
102
- "" if state.task_type in ("release-handoff", "discussion")
103
+ "" if state.task_type in INPUT_DOCUMENT_TASK_TYPES
103
104
  else state.brief_path
104
105
  ),
105
106
  "analysis-target": state.analysis_target,
@@ -29,7 +29,9 @@ from okstra_ctl.wizard_stage_intent import WHOLE_TASK_STAGE
29
29
  from okstra_ctl import worktree_registry
30
30
  from okstra_ctl.worktree import is_git_work_tree, main_worktree_path
31
31
  from okstra_ctl.paths import RunRef, task_runs_dir
32
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
32
33
  from okstra_ctl.run_context import latest_run_inputs
34
+ from okstra_ctl.generated_input import names_generated_input_document
33
35
  from okstra_project.state import (
34
36
  StateError,
35
37
  list_project_tasks,
@@ -200,7 +202,7 @@ def _resolve_reuse_worktree(state: WizardState) -> bool:
200
202
 
201
203
  def _brief_resolved(state: WizardState) -> bool:
202
204
  """brief 입력이 끝났는가. release-handoff·discussion 은 brief 를 받지 않아 항상 True."""
203
- return bool(state.brief_path) or state.task_type in ("release-handoff", "discussion")
205
+ return bool(state.brief_path) or state.task_type in INPUT_DOCUMENT_TASK_TYPES
204
206
 
205
207
 
206
208
  def _parse_stage_objects(state: WizardState) -> list:
@@ -251,13 +253,22 @@ def _reserved_stage_numbers(state: WizardState) -> set:
251
253
 
252
254
 
253
255
  def _existing_task_brief(project_root: Path, task_key: str) -> str:
254
- """Read taskBriefPath from manifest for an existing task. Empty if none."""
256
+ """Read taskBriefPath from manifest for an existing task.
257
+
258
+ Empty if none, or if it points at an input document a release-handoff or
259
+ discussion run generated.
260
+ """
255
261
  root = find_task_root(project_root, task_key)
256
262
  if root is None:
257
263
  return ""
258
264
  manifest = read_task_manifest(root) or {}
259
265
  val = manifest.get("taskBriefPath") or ""
260
- return val if isinstance(val, str) else ""
266
+ if not isinstance(val, str):
267
+ return ""
268
+ # Manifests written before render kept the task brief can still name one.
269
+ if names_generated_input_document(Path(project_root), task_key, val):
270
+ return ""
271
+ return val
261
272
 
262
273
 
263
274
  def _recently_used_brief_times(state: WizardState) -> dict[str, float]:
@@ -29,6 +29,7 @@ from okstra_project.state import (
29
29
  find_task_root,
30
30
  )
31
31
 
32
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
32
33
  from .ids import (
33
34
  BRIEF_CARRY_SWITCH_ENTRY,
34
35
  BASE_REF_FREE_INPUT_TOKEN,
@@ -656,7 +657,7 @@ def _carry_in_existing_brief(state: WizardState) -> str:
656
657
  """downstream task-type 이 등록된 brief 를 자동 carry-in 한다. 주입한 경로(또는 '')."""
657
658
  if state.task_type in _BRIEF_ENTRY_TASK_TYPES:
658
659
  return ""
659
- if state.task_type in ("release-handoff", "discussion"):
660
+ if state.task_type in INPUT_DOCUMENT_TASK_TYPES:
660
661
  return "" # prepare 가 brief 자리의 input 문서를 직접 생성한다
661
662
  if state.brief_path or not state.existing_brief_path:
662
663
  return ""
@@ -470,7 +470,7 @@ def _drain_deadline(
470
470
 
471
471
  Without this the loop ends only at EOF on every stream, and a worker that
472
472
  leaves a background process behind — a dev server, a file watcher, the
473
- watcher the container-build skill starts on purpose — leaves that process
473
+ watcher started on purpose — leaves that process
474
474
  holding the write end of the pipe open for as long as it lives. The shell
475
475
  wrappers returned as soon as `wait <pid>` did, so blocking on a grandchild is
476
476
  a regression rather than a policy, and the exit code the caller gets stays
@@ -3,7 +3,6 @@ from __future__ import annotations
3
3
 
4
4
  import argparse
5
5
  import contextlib
6
- import os
7
6
  import subprocess
8
7
  import sys
9
8
  from pathlib import Path
@@ -11,6 +10,11 @@ from pathlib import Path
11
10
  from okstra_project.dirs import okstra_home
12
11
 
13
12
  from .locks import worktree_exec_lock
13
+ from .registry.verification_inputs_store import default_verification_input_store
14
+ from .verification_evidence import (
15
+ EvidenceRefused, resolve_evidence_check, run_evidence_check, shell_argv,
16
+ shell_exit_code,
17
+ )
14
18
 
15
19
  _CLI_EPILOG = r"""Every verifier of a stage runs in the same worktree at the same time, and each
16
20
  re-runs the plan's Tier 1 commands itself. A command that starts a server on a
@@ -28,24 +32,60 @@ The lock file is <okstra home>/.locks/worktree-exec/<hash of the worktree
28
32
  realpath>.lock, outside the worktree and the project's .okstra tree. When it
29
33
  cannot be created or locked, the command still runs, unlocked, after a warning
30
34
  on stderr.
35
+
36
+ Evidence mode runs one frozen check for one open verifier attempt instead:
37
+
38
+ okstra worktree-lock --project-root <root> --invocation-metadata <meta.json> \
39
+ --check qa:<qaCommands id>
40
+ okstra worktree-lock --project-root <root> --invocation-metadata <meta.json> \
41
+ --check conformance:<stageKey>
42
+
43
+ The command, the worktree and any resourceKeys come from the verification
44
+ generation the invocation is bound to, never from flags. A conformance check
45
+ runs the runCommand of that stage's entry in the conformance manifest the
46
+ generation sealed, only for a stage the generation lists in conformanceStages
47
+ and only while the manifest bytes still match the seal. In an implementation
48
+ run only the stage QA owner may run it; in final verification every verifier
49
+ runs it. It takes the worktree
50
+ lock and then each resource lock in sorted order, re-checks the attempt and the
51
+ sealed target under them, saves stdout and stderr byte for byte while passing
52
+ them through, and publishes one record under the run's verification directory.
53
+ The exit code is the command's only when the record is complete and no signal
54
+ arrived. A SIGTERM, SIGINT or SIGHUP received while the check waits or runs
55
+ exits 128+N of the first one, whatever the record says. Any other outcome (lock
56
+ unavailable, attempt cancelled, target changed, output not saved, incomplete
57
+ drain, evidence error) exits 70 and names the record on stderr. A refused
58
+ invocation or check exits 2 and runs nothing.
31
59
  """
32
60
 
33
61
 
34
- def _shell() -> str:
35
- return os.environ.get("SHELL", "") or "/bin/sh"
62
+ def _announce_wait(lockfile: Path) -> None:
63
+ _notify(f"another command holds {lockfile}; waiting")
36
64
 
37
65
 
38
- def _announce_wait(lockfile: Path) -> None:
39
- sys.stderr.write(
40
- f"okstra worktree-lock: another command holds {lockfile}; waiting\n"
66
+ def _run(command: str, worktree: Path) -> int:
67
+ return shell_exit_code(
68
+ subprocess.run(shell_argv(command), cwd=worktree, check=False).returncode
41
69
  )
70
+
71
+
72
+ def _notify(message: str) -> None:
73
+ sys.stderr.write(f"okstra worktree-lock: {message}\n")
42
74
  sys.stderr.flush()
43
75
 
44
76
 
45
- def _run(command: str, worktree: Path) -> int:
46
- code = subprocess.run([_shell(), "-c", command], cwd=worktree, check=False).returncode
47
- # 시그널로 죽은 자식은 음수를 준다. 셸이 보고하는 128+N 으로 맞춘다.
48
- return 128 - code if code < 0 else code
77
+ def _run_evidence(project: Path, metadata: Path, check_ref: str) -> int:
78
+ store = default_verification_input_store()
79
+ try:
80
+ check = resolve_evidence_check(project, metadata, check_ref, store=store)
81
+ except EvidenceRefused as exc:
82
+ _notify(f"evidence refused: {exc}")
83
+ return 2
84
+ sys.stdout.flush()
85
+ return run_evidence_check(
86
+ check, metadata, store=store, home=okstra_home(), on_wait=_announce_wait,
87
+ notify=_notify,
88
+ )
49
89
 
50
90
 
51
91
  def main(argv: list[str] | None = None) -> int:
@@ -56,17 +96,33 @@ def main(argv: list[str] | None = None) -> int:
56
96
  formatter_class=argparse.RawDescriptionHelpFormatter,
57
97
  )
58
98
  parser.add_argument(
59
- "--worktree", type=Path, required=True,
99
+ "--worktree", type=Path,
60
100
  help="worktree the command runs in; also the lock key (resolved to its realpath)",
61
101
  )
62
102
  parser.add_argument(
63
- "--command", required=True,
103
+ "--command",
64
104
  help="the declared command, run verbatim through the shell",
65
105
  )
106
+ parser.add_argument("--project-root", type=Path, help="evidence mode: project root")
107
+ parser.add_argument(
108
+ "--invocation-metadata", type=Path,
109
+ help="evidence mode: the verifier invocation's .meta.json",
110
+ )
111
+ parser.add_argument(
112
+ "--check", help="evidence mode: qa:<qaCommands id> or conformance:<stageKey>",
113
+ )
66
114
  args = parser.parse_args(argv)
115
+ evidence = (args.project_root, args.invocation_metadata, args.check)
116
+ if any(value is not None for value in evidence):
117
+ if None in evidence or args.worktree is not None or args.command is not None:
118
+ parser.error("evidence mode takes exactly --project-root, "
119
+ "--invocation-metadata and --check")
120
+ return _run_evidence(*evidence)
121
+ if args.worktree is None or args.command is None:
122
+ parser.error("--worktree and --command are required")
67
123
  worktree = args.worktree.resolve()
68
124
  if not worktree.is_dir():
69
- sys.stderr.write(f"okstra worktree-lock: not a directory: {worktree}\n")
125
+ _notify(f"not a directory: {worktree}")
70
126
  return 2
71
127
  with contextlib.ExitStack() as stack:
72
128
  try:
@@ -76,10 +132,7 @@ def main(argv: list[str] | None = None) -> int:
76
132
  except OSError as exc:
77
133
  # 잠그지 못해도 검증자의 재실행 자체를 막지 않는다. 동시 실행의 위험은
78
134
  # 락 도입 전과 같고, 그 사실을 stderr 에 남긴다.
79
- sys.stderr.write(
80
- f"okstra worktree-lock: warning: cannot take the lock ({exc}); running unlocked\n"
81
- )
82
- sys.stderr.flush()
135
+ _notify(f"warning: cannot take the lock ({exc}); running unlocked")
83
136
  return _run(args.command, worktree)
84
137
 
85
138
 
@@ -290,6 +290,10 @@ def get_implementation_base(
290
290
  ) -> Optional[str]:
291
291
  """Return the fixed implementation base commit, or None when unset /
292
292
  task-key missing."""
293
+ # Validation gates read this and must leave no file behind; taking the lock
294
+ # creates `registry.lock`.
295
+ if not _registry_path().is_file():
296
+ return None
293
297
  key = task_key(project_id, task_group, task_id)
294
298
  with _registry_lock():
295
299
  data = _load()