okstra 0.229.0 → 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 (119) 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 +105 -16
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +11 -18
  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/prompts/launch.template.md +5 -5
  16. package/runtime/prompts/lead/convergence.md +4 -4
  17. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  18. package/runtime/prompts/lead/phase-routing.md +1 -1
  19. package/runtime/prompts/lead/report-writer.md +3 -3
  20. package/runtime/prompts/lead/team-contract.md +3 -3
  21. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  22. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  23. package/runtime/python/okstra_ctl/cmux.py +4 -2
  24. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  26. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  27. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  28. package/runtime/python/okstra_ctl/conformance.py +30 -0
  29. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  30. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  31. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  32. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  33. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  34. package/runtime/python/okstra_ctl/ids.py +1 -41
  35. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  36. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  37. package/runtime/python/okstra_ctl/locks.py +28 -1
  38. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  39. package/runtime/python/okstra_ctl/paths.py +75 -33
  40. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  41. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  42. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  43. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  44. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  45. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  46. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  48. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  49. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  50. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  53. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  54. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  55. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  63. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  64. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  66. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  67. package/runtime/python/okstra_ctl/process_group.py +26 -3
  68. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  69. package/runtime/python/okstra_ctl/recap.py +1 -2
  70. package/runtime/python/okstra_ctl/render.py +10 -2
  71. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  72. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  73. package/runtime/python/okstra_ctl/run.py +24 -20
  74. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  75. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  76. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  77. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  78. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  79. package/runtime/python/okstra_ctl/verification_generation.py +22 -12
  80. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  81. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  82. package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
  83. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  84. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  85. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  86. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  87. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  88. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  89. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  90. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  91. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  92. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  93. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  94. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  95. package/runtime/skills/okstra-run/SKILL.md +6 -6
  96. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  97. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  98. package/runtime/validators/validate-run.py +110 -19
  99. package/docs/cli.md +0 -1060
  100. package/docs/container.md +0 -100
  101. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  102. package/docs/performance-improvement-plan-v2.md +0 -369
  103. package/runtime/python/okstra_ctl/container.py +0 -702
  104. package/runtime/python/okstra_ctl/rollup.py +0 -241
  105. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  106. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  107. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  108. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  109. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  110. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  111. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  112. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  113. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  114. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  115. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  116. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  117. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  118. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  119. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -0,0 +1,194 @@
1
+ """Build a code-review census from a diff, so membership stays mechanical."""
2
+ from __future__ import annotations
3
+
4
+ import ast
5
+ import re
6
+ import subprocess
7
+ from dataclasses import dataclass
8
+ from pathlib import Path, PurePosixPath
9
+
10
+ from .code_review_coverage import read_review_census
11
+
12
+ _GROUPS = ("structural", "semantic", "state-and-tests", "general")
13
+ _FILE_GROUPS = {
14
+ "source": ("structural", "state-and-tests", "general"),
15
+ "test": ("state-and-tests",),
16
+ }
17
+ _ALWAYS_CENSUSED = ("skills/", "prompts/", "agents/", "templates/")
18
+ _LOCKFILES = {
19
+ "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "poetry.lock",
20
+ "Cargo.lock", "uv.lock", "Gemfile.lock", "composer.lock",
21
+ }
22
+ _GENERATED_ROOTS = ("dist/", "runtime/", "build/")
23
+ _DATA_SUFFIXES = {".json", ".yml", ".yaml", ".toml", ".ini", ".cfg", ".csv"}
24
+ _PROSE_SUFFIXES = {".md", ".markdown", ".rst", ".txt"}
25
+ _UNPARSED_CODE_SUFFIXES = {
26
+ ".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".tsx", ".jsx", ".sh", ".bash",
27
+ ".go", ".rs", ".java", ".kt", ".kts", ".rb", ".php", ".swift", ".c", ".h",
28
+ ".cc", ".cpp", ".hpp", ".cs", ".scala",
29
+ }
30
+ _TEST_PATH = re.compile(
31
+ r"(^|/)(tests?|spec|__tests__)/|(^|/)test_[^/]+\.py$|_test\.[^/]+$"
32
+ r"|\.(test|spec)\.[^/]+$"
33
+ )
34
+ _POSITION = re.compile(r":\d+(?::\d+)?(?= )")
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class CensusResult:
39
+ text: str
40
+ unresolved: tuple[str, ...]
41
+
42
+
43
+ def build_review_census(
44
+ repo: Path, base: str, head: str, rules_source: Path,
45
+ changed: dict[str, set[int]], *, previous: Path | None = None,
46
+ ) -> CensusResult:
47
+ rules = _rules_section(rules_source.read_text(encoding="utf-8"))
48
+ files = _changed_files(repo, base, head)
49
+ cells: list[tuple[str, str]] = []
50
+ exclusions: list[tuple[str, str]] = []
51
+ unresolved: list[str] = []
52
+ functions: list[str] = []
53
+ for path, binary in files:
54
+ reason = _exclusion(path, binary)
55
+ if reason:
56
+ exclusions.append((path, reason))
57
+ continue
58
+ kind = "test" if _TEST_PATH.search(path) else "source"
59
+ cells.extend((path, group) for group in _FILE_GROUPS[kind])
60
+ if kind == "test" or path not in changed:
61
+ continue
62
+ suffix = PurePosixPath(path).suffix
63
+ if suffix == ".py":
64
+ functions.extend(_changed_functions(repo, head, path, changed[path]))
65
+ elif suffix in _UNPARSED_CODE_SUFFIXES:
66
+ unresolved.append(path)
67
+ cells.extend((target, "semantic") for target in functions)
68
+ ordered = sorted(cells, key=lambda cell: _GROUPS.index(cell[1]))
69
+ ids, retired, new = _assign_ids(ordered, previous)
70
+ text = _render(rules, ordered, ids, exclusions, files, unresolved, retired, new,
71
+ previous is not None)
72
+ return CensusResult(text, tuple(unresolved))
73
+
74
+
75
+ def _rules_section(text: str) -> str:
76
+ start = text.find("## Rules")
77
+ if start < 0:
78
+ raise ValueError("rules source has no ## Rules table")
79
+ end = text.find("\n## ", start + 1)
80
+ return text[start:] if end < 0 else text[start:end + 1]
81
+
82
+
83
+ def _changed_files(repo: Path, base: str, head: str) -> list[tuple[str, bool]]:
84
+ listed = subprocess.run(
85
+ ["git", "-C", str(repo), "diff", "--numstat", "-z", "-M", "--no-ext-diff",
86
+ f"{base}..{head}", "--"],
87
+ capture_output=True, check=True,
88
+ ).stdout.decode("utf-8", "surrogateescape").split("\0")
89
+ files: list[tuple[str, bool]] = []
90
+ entries = iter(listed)
91
+ for entry in entries:
92
+ if not entry:
93
+ continue
94
+ added, _, rest = entry.partition("\t")
95
+ _deleted, _, path = rest.partition("\t")
96
+ if not path:
97
+ next(entries)
98
+ path = next(entries)
99
+ files.append((path, added == "-"))
100
+ return files
101
+
102
+
103
+ def _exclusion(path: str, binary: bool) -> str | None:
104
+ if path.startswith(_ALWAYS_CENSUSED):
105
+ return None
106
+ name = PurePosixPath(path).name
107
+ suffix = PurePosixPath(path).suffix.lower()
108
+ if name in _LOCKFILES or name.endswith(".sum"):
109
+ return "lockfile"
110
+ if path.startswith(_GENERATED_ROOTS):
111
+ return "generated build output"
112
+ if binary:
113
+ return "binary file"
114
+ if suffix in _DATA_SUFFIXES:
115
+ return "configuration or data without executable project code"
116
+ if suffix in _PROSE_SUFFIXES:
117
+ return "prose documentation without executable or agent-directive content"
118
+ return None
119
+
120
+
121
+ def _changed_functions(
122
+ repo: Path, head: str, path: str, lines: set[int],
123
+ ) -> list[str]:
124
+ source = subprocess.run(
125
+ ["git", "-C", str(repo), "show", f"{head}:{path}"],
126
+ capture_output=True, check=True,
127
+ ).stdout.decode("utf-8")
128
+ touched: list[str] = []
129
+
130
+ def visit(node: ast.AST, prefix: str) -> None:
131
+ for child in ast.iter_child_nodes(node):
132
+ if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
133
+ start = min([child.lineno, *(d.lineno for d in child.decorator_list)])
134
+ if lines.intersection(range(start, (child.end_lineno or start) + 1)):
135
+ touched.append(f"{path}:{child.lineno} {prefix}{child.name}")
136
+ visit(child, f"{prefix}{child.name}.")
137
+ elif isinstance(child, ast.ClassDef):
138
+ visit(child, f"{prefix}{child.name}.")
139
+
140
+ visit(ast.parse(source, filename=path), "")
141
+ return touched
142
+
143
+
144
+ def _identity(target: str, group: str) -> tuple[str, str]:
145
+ return _POSITION.sub("", target, count=1), group
146
+
147
+
148
+ def _assign_ids(
149
+ cells: list[tuple[str, str]], previous: Path | None,
150
+ ) -> tuple[list[str], list[str], list[str]]:
151
+ known: dict[tuple[str, str], str] = {}
152
+ highest = 0
153
+ if previous is not None:
154
+ old = read_review_census(previous)
155
+ for identity, cell in old.cells.items():
156
+ known[_identity(cell.target, cell.group)] = identity
157
+ highest = max(highest, int(identity.removeprefix("C-CR-")))
158
+ ids: list[str] = []
159
+ new: list[str] = []
160
+ for target, group in cells:
161
+ identity = known.pop(_identity(target, group), None)
162
+ if identity is None:
163
+ highest += 1
164
+ identity = f"C-CR-{highest:04d}"
165
+ new.append(identity)
166
+ ids.append(identity)
167
+ return ids, sorted(known.values()), new
168
+
169
+
170
+ def _render(
171
+ rules: str, cells: list[tuple[str, str]], ids: list[str],
172
+ exclusions: list[tuple[str, str]], files: list[tuple[str, bool]],
173
+ unresolved: list[str], retired: list[str], new: list[str], has_previous: bool,
174
+ ) -> str:
175
+ rows = [rules.rstrip("\n"), "", "## Cells"]
176
+ rows += ["| Cell | Target | Group |", "|---|---|---|"]
177
+ rows += [f"| {cell_id} | {target} | {group} |"
178
+ for cell_id, (target, group) in zip(ids, cells)]
179
+ rows += ["", "## Exclusions"]
180
+ rows += [f"- `{path}`: {reason}." for path, reason in exclusions] or ["- none"]
181
+ censused = len({target.partition(":")[0] for target, _ in cells})
182
+ rows += [
183
+ "", "## Accounting",
184
+ f"- Changed files: {len(files)}; censused: {censused}; "
185
+ f"excluded: {len(exclusions)}",
186
+ "- Unresolved function boundaries: " + (", ".join(unresolved) or "-"),
187
+ ]
188
+ if has_previous:
189
+ rows += [
190
+ "", "## Changes from previous census",
191
+ "- Retired: " + (", ".join(retired) or "-"),
192
+ "- New: " + (", ".join(new) or "-"),
193
+ ]
194
+ return "\n".join(rows) + "\n"
@@ -26,7 +26,9 @@ class ReviewCensus:
26
26
 
27
27
 
28
28
  def _table_fields(line: str) -> list[str]:
29
- return [field.strip() for field in line.strip().strip("|").split("|")]
29
+ # Markdown writes a literal pipe inside a table cell as `\|`.
30
+ fields = re.split(r"(?<!\\)\|", line.strip().strip("|"))
31
+ return [field.strip().replace("\\|", "|") for field in fields]
30
32
 
31
33
 
32
34
  def read_review_census(path: Path) -> ReviewCensus:
@@ -111,8 +111,8 @@ def review_scope(
111
111
  return full("rule catalog changed")
112
112
  verdicts = check_review_coverage(root, previous_census, completions, prior.commit,
113
113
  base=base_commit)
114
- if verdicts.missing or verdicts.unknown:
115
- return full("previous review coverage is incomplete")
114
+ if verdicts.unknown:
115
+ return full("previous review names unknown cells")
116
116
  try:
117
117
  dependencies = _prior_inputs(
118
118
  root, completions, old,
@@ -139,16 +139,19 @@ def _partition(
139
139
  known = set().union(*dependencies.values()) if dependencies else set()
140
140
  unknown = changed - known
141
141
  carry = []
142
+ # A changed path outside every recorded inventory reopens only the cells that
143
+ # list it; reviewers still search the delta for effects the inventory missed.
142
144
  for identity, cell in census.cells.items():
143
145
  sources = dependencies.get(identity, set())
144
146
  target = cell.target.partition(":")[0]
145
- if (not unknown and old.cells.get(identity) == cell and target in sources
147
+ if (old.cells.get(identity) == cell and target in sources
146
148
  and not changed.intersection(sources)
147
149
  and verdicts.get(identity, ("missing", ""))[0] in ("clean", "n/a")):
148
150
  carry.append(identity)
149
- reason = ("unmapped changed inputs: " + ", ".join(sorted(unknown))) if unknown else (
150
- "review changed dependencies and prior findings; attest carry boundaries"
151
- )
151
+ reason = "review changed dependencies, prior findings and unverified cells"
152
+ if unknown:
153
+ reason += "; search unmapped changed inputs: " + ", ".join(sorted(unknown))
154
+ reason += "; attest carry boundaries"
152
155
  carry_ids = set(carry)
153
156
  return ReviewScope(
154
157
  baseline,
@@ -107,6 +107,9 @@ instead of a checked-out tree. This is read-only — it never creates
107
107
  directories or files. `check-coverage` reads head evidence at `--head` and explicit
108
108
  base evidence at `--base`, never the working tree, prints covered cells, missing rules and unknown cells, and exits
109
109
  1 for incomplete coverage and 2 for invalid input or completion evidence.
110
+ `census` writes the range's census to `--out`, copying the Rules table from
111
+ `--rules` and keeping IDs from `--previous-census`; it exits 1 when changed
112
+ non-Python code still needs function cells added by hand.
110
113
  """
111
114
 
112
115
 
@@ -117,7 +120,10 @@ def _build_parser() -> argparse.ArgumentParser:
117
120
  prog="okstra code-review",
118
121
  description="Resolve a code review's diff range and result file path, or check finding citations."
119
122
  )
120
- parser.add_argument("command", choices=("target", "check-lines", "check-coverage", "scope"))
123
+ parser.add_argument(
124
+ "command",
125
+ choices=("target", "check-lines", "check-coverage", "scope", "census"),
126
+ )
121
127
  parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
122
128
  parser.add_argument("--stage", type=int, default=0, help="stage number to review")
123
129
  parser.add_argument("--branch", default="", help="branch to review")
@@ -138,7 +144,11 @@ def _build_parser() -> argparse.ArgumentParser:
138
144
  parser.add_argument("--completion", action="append", default=[],
139
145
  help="check-coverage: verified reviewer completion (repeat for gap-fills)")
140
146
  parser.add_argument("--previous-head", default="", help="scope: previous reviewed commit")
141
- parser.add_argument("--previous-census", default="", help="scope: previous full census")
147
+ parser.add_argument("--previous-census", default="",
148
+ help="scope, census: previous full census")
149
+ parser.add_argument("--rules", default="",
150
+ help="census: file whose ## Rules table the census copies")
151
+ parser.add_argument("--out", default="", help="census: file to write the census to")
142
152
  parser.add_argument("--policy", action="append", default=[],
143
153
  help="scope: policy/calibration source to fingerprint (repeatable)")
144
154
  parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
@@ -341,6 +351,8 @@ def main(argv: list[str] | None = None) -> int:
341
351
 
342
352
  if args.command == "scope":
343
353
  return _scope(args, Path(project_root))
354
+ if args.command == "census":
355
+ return _census(args, Path(project_root))
344
356
  if args.command == "check-coverage":
345
357
  return _check_coverage(args, Path(project_root))
346
358
  if args.command == "check-lines":
@@ -370,6 +382,30 @@ def main(argv: list[str] | None = None) -> int:
370
382
  return 0
371
383
 
372
384
 
385
+ def _census(args: argparse.Namespace, project_root: Path) -> int:
386
+ from .code_review_census import build_review_census
387
+ from .code_review_coverage import read_review_census
388
+
389
+ if not (args.base and args.head and args.rules and args.out):
390
+ print("census: pass --base, --head, --rules and --out", file=sys.stderr)
391
+ return 2
392
+ try:
393
+ result = build_review_census(
394
+ project_root, args.base, args.head, Path(args.rules),
395
+ changed_lines(project_root, args.base, args.head),
396
+ previous=Path(args.previous_census) if args.previous_census else None,
397
+ )
398
+ out = Path(args.out)
399
+ out.write_text(result.text, encoding="utf-8")
400
+ read_review_census(out)
401
+ except (OSError, ValueError, SyntaxError, StateError,
402
+ subprocess.CalledProcessError) as exc:
403
+ print(f"census: {exc}", file=sys.stderr)
404
+ return 2
405
+ print(result.text, end="")
406
+ return 1 if result.unresolved else 0
407
+
408
+
373
409
  def _scope(args: argparse.Namespace, project_root: Path) -> int:
374
410
  from .agent.invocation import AgentInvocationError
375
411
  from .code_review_scope import review_scope
@@ -16,8 +16,10 @@ import fnmatch
16
16
  import re
17
17
  from dataclasses import dataclass
18
18
  from pathlib import Path
19
+ from typing import Any, Mapping
19
20
 
20
21
  from .qa_commands import verification_command_defects
22
+ from .qa_procedures import content_digest
21
23
 
22
24
  # diff 가 건드린 표면과 대조할 capability 태그 화이트리스트.
23
25
  CAPABILITY_WHITELIST: tuple[str, ...] = ("db", "io", "http", "external")
@@ -476,6 +478,34 @@ def parse_qa_result(stdout: str) -> QaResult:
476
478
  return QaResult(overall=overall, requirements=requirements)
477
479
 
478
480
 
481
+ def execution_evidence_defect(record: Mapping[str, Any], stdout: bytes) -> str | None:
482
+ """Why an evidence-mode execution record cannot back a result; None when it can."""
483
+ if record.get("status") != "completed":
484
+ return f"status is {record.get('status')}"
485
+ stream = record.get("stdout")
486
+ if (not isinstance(stream, Mapping) or stream.get("bytes") != len(stdout)
487
+ or stream.get("digest") != content_digest(stdout)):
488
+ return "saved stdout is not the output the record observed"
489
+ return None
490
+
491
+
492
+ def qa_result_from_execution(
493
+ record: Mapping[str, Any], stdout: bytes,
494
+ ) -> QaResult | None:
495
+ """Derive one stage's result from an evidence-mode execution record.
496
+
497
+ None means no usable evidence; `execution_evidence_defect` says why.
498
+ """
499
+ if execution_evidence_defect(record, stdout) is not None:
500
+ return None
501
+ result = parse_qa_result(stdout.decode("utf-8", errors="replace"))
502
+ # The marker is the script's claim; the observed exit is the runner's. A
503
+ # signalled run records no exit code, so it is never zero here either.
504
+ if result.overall == "PASS" and record.get("exitCode") != 0:
505
+ return QaResult(overall="FAIL", requirements=result.requirements)
506
+ return result
507
+
508
+
479
509
  @dataclass
480
510
  class ConformanceVerdict:
481
511
  stage_key: str
@@ -0,0 +1,235 @@
1
+ """Select the verification execution records that decide stage conformance.
2
+
3
+ Each stage is decided by the newest sealed generation that lists it. An
4
+ implementation run takes the result from the stage QA owner only; final
5
+ verification needs a PASS from every verifier it dispatched.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass, field
10
+ from pathlib import Path
11
+ from typing import Iterable, Mapping
12
+
13
+ from .agent.invocation import AgentInvocationError
14
+ from .conformance import QaResult, execution_evidence_defect, qa_result_from_execution
15
+ from .execution_identity import ExecutionManifest, Invocation
16
+ from .execution_manifest import read_execution_manifest
17
+ from .json_boundary import JsonBoundaryError, load_owned_object
18
+ from .paths import RunRef
19
+ from .qa_commands import QA_VERIFIER_AUDIENCE_BY_TASK_TYPE
20
+ from .qa_procedures import content_digest
21
+ from .verification_conformance import conformance_stage
22
+ from .verification_dispatch import verification_generation_number
23
+ from .verification_evidence import (
24
+ conformance_check_owner_ref, read_verification_execution_record,
25
+ )
26
+ from .verification_generation import (
27
+ VerificationGenerationRecord, read_verification_generation,
28
+ )
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class StageEvidence:
33
+ """`records` are the latest record files examined for this stage, including
34
+ the `rejections`: records that are no usable evidence, with the reason."""
35
+
36
+ result: QaResult | None
37
+ records: tuple[Path, ...]
38
+ rejections: Mapping[Path, str] = field(default_factory=dict)
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class RunConformanceEvidence:
43
+ """`stages` are the conformance stages a bound verifier generation requires."""
44
+
45
+ stages: frozenset[int]
46
+ results: Mapping[str, StageEvidence]
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class _VerifierOutcome:
51
+ result: QaResult | None
52
+ record: Path | None = None
53
+ rejection: str | None = None
54
+
55
+
56
+ _NO_OUTCOME = _VerifierOutcome(None)
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class _BoundInvocation:
61
+ """One verifier invocation and the generation its dispatch kind seals."""
62
+
63
+ invocation: Invocation
64
+ generation_number: int
65
+ index: int
66
+ generation: VerificationGenerationRecord | None
67
+ generation_ref: dict[str, str]
68
+
69
+ def seals(self, stage: int) -> bool:
70
+ return (self.generation is not None
71
+ and stage in self.generation.get("conformanceStages", ()))
72
+
73
+
74
+ def collect_conformance_evidence(
75
+ project: Path, manifest_path: Path, stage_keys: Iterable[str],
76
+ ) -> RunConformanceEvidence:
77
+ try:
78
+ return _collect(project.resolve(), manifest_path.resolve(), tuple(stage_keys))
79
+ except (AgentInvocationError, OSError) as exc:
80
+ raise ValueError(str(exc)) from exc
81
+
82
+
83
+ def _collect(
84
+ project: Path, manifest_path: Path, stage_keys: tuple[str, ...],
85
+ ) -> RunConformanceEvidence:
86
+ manifest = load_owned_object(manifest_path, artifact="run manifest")
87
+ ref = RunRef.from_manifest(manifest_path, manifest)
88
+ audience = QA_VERIFIER_AUDIENCE_BY_TASK_TYPE.get(manifest.get("taskType"))
89
+ if audience is None:
90
+ raise ValueError("verification evidence requires a QA-executing run")
91
+ execution = read_execution_manifest(manifest_path)
92
+ verifiers = _bound_verifiers(project, ref, execution, audience)
93
+ owner = conformance_check_owner_ref(manifest)
94
+ counted = list(verifiers) if owner is None else [owner]
95
+ latest_attempt = _latest_attempts(execution)
96
+ return RunConformanceEvidence(_required_stages(verifiers), {
97
+ key: _stage_evidence(ref, verifiers, counted, key, latest_attempt)
98
+ for key in stage_keys
99
+ })
100
+
101
+
102
+ def _stage_evidence(
103
+ ref: RunRef, verifiers: Mapping[str, list[_BoundInvocation]],
104
+ counted: list[str], stage_key: str, latest_attempt: Mapping[str, int],
105
+ ) -> StageEvidence:
106
+ """A counted verifier with no invocation bound to the newest generation that
107
+ seals the stage leaves it without a result; an older generation's record
108
+ observed the work before the round that sealed the newer one."""
109
+ try:
110
+ stage = conformance_stage(stage_key)
111
+ except ValueError:
112
+ # expected-miss: a malformed key names no stage a generation can seal,
113
+ # so no record can exist for it.
114
+ return StageEvidence(None, ())
115
+ newest = max((binding.generation_number for bindings in verifiers.values()
116
+ for binding in bindings if binding.seals(stage)), default=None)
117
+ if newest is None:
118
+ return StageEvidence(None, ())
119
+ return _combine([
120
+ _verifier_result(ref, role_execution_ref, verifiers.get(role_execution_ref, []),
121
+ newest, stage_key, latest_attempt)
122
+ for role_execution_ref in counted
123
+ ])
124
+
125
+
126
+ def _bound_verifiers(
127
+ project: Path, ref: RunRef, execution: ExecutionManifest, audience: str,
128
+ ) -> dict[str, list[_BoundInvocation]]:
129
+ """Each verifier's invocations, newest first."""
130
+ verifiers: dict[str, list[_BoundInvocation]] = {}
131
+ for index, invocation in enumerate(execution.invocations):
132
+ if invocation.duty_id == audience:
133
+ verifiers.setdefault(invocation.role_execution_ref, []).append(
134
+ _bind(project, ref, invocation, index),
135
+ )
136
+ for bindings in verifiers.values():
137
+ bindings.sort(key=lambda binding: (binding.generation_number, binding.index),
138
+ reverse=True)
139
+ return verifiers
140
+
141
+
142
+ def _latest_attempts(execution: ExecutionManifest) -> dict[str, int]:
143
+ latest: dict[str, int] = {}
144
+ for row in execution.attempts:
145
+ latest[row.invocation_ref] = max(row.attempt, latest.get(row.invocation_ref, 0))
146
+ return latest
147
+
148
+
149
+ def _required_stages(verifiers: Mapping[str, list[_BoundInvocation]]) -> frozenset[int]:
150
+ return frozenset(
151
+ stage for bindings in verifiers.values() for binding in bindings
152
+ if binding.generation is not None
153
+ for stage in binding.generation.get("conformanceStages", ())
154
+ )
155
+
156
+
157
+ def _bind(
158
+ project: Path, ref: RunRef, invocation: Invocation, index: int,
159
+ ) -> _BoundInvocation:
160
+ number = verification_generation_number(invocation.dispatch_kind)
161
+ path = ref.verification_generation(number)
162
+ relative = path.relative_to(project).as_posix()
163
+ if not path.is_file():
164
+ return _BoundInvocation(invocation, number, index, None,
165
+ {"path": relative, "digest": ""})
166
+ digest = content_digest(path.read_bytes())
167
+ return _BoundInvocation(invocation, number, index,
168
+ read_verification_generation(path, digest),
169
+ {"path": relative, "digest": digest})
170
+
171
+
172
+ def _verifier_result(
173
+ ref: RunRef, role_execution_ref: str, bindings: list[_BoundInvocation],
174
+ generation_number: int, stage_key: str, latest_attempt: Mapping[str, int],
175
+ ) -> _VerifierOutcome:
176
+ chosen = next((binding for binding in bindings if binding.generation is not None
177
+ and binding.generation_number == generation_number), None)
178
+ if chosen is None:
179
+ return _NO_OUTCOME
180
+ invocation_ref = chosen.invocation.invocation_ref
181
+ attempt = latest_attempt.get(invocation_ref)
182
+ if attempt is None:
183
+ return _NO_OUTCOME
184
+ check_ref = f"conformance:{stage_key}"
185
+ check_run = ref.latest_verification_check_run(invocation_ref, attempt, check_ref)
186
+ if check_run is None:
187
+ return _NO_OUTCOME
188
+ run_dir = ref.verification_execution_dir(
189
+ invocation_ref, attempt, check_ref, check_run,
190
+ )
191
+ expected = {
192
+ "invocationRef": invocation_ref, "roleExecutionRef": role_execution_ref,
193
+ "attempt": attempt, "checkRef": check_ref, "checkRun": check_run,
194
+ "verificationGeneration": chosen.generation_ref,
195
+ }
196
+ record_path = run_dir / "record.json"
197
+ result, rejection = _recorded_result(run_dir, expected)
198
+ return _VerifierOutcome(result, record_path, rejection)
199
+
200
+
201
+ def _recorded_result(
202
+ run_dir: Path, expected: Mapping[str, object],
203
+ ) -> tuple[QaResult | None, str | None]:
204
+ try:
205
+ record = read_verification_execution_record(run_dir / "record.json")
206
+ except (JsonBoundaryError, OSError) as exc:
207
+ return None, f"record is unreadable ({exc})"
208
+ if any(record[name] != value for name, value in expected.items()):
209
+ return None, ("record identity, attempt, check run or generation differs "
210
+ "from its location")
211
+ try:
212
+ output = (run_dir / "stdout.log").read_bytes()
213
+ except OSError as exc:
214
+ return None, f"saved stdout is unreadable ({exc})"
215
+ defect = execution_evidence_defect(record, output)
216
+ if defect is not None:
217
+ return None, defect
218
+ return qa_result_from_execution(record, output), None
219
+
220
+
221
+ def _combine(outcomes: list[_VerifierOutcome]) -> StageEvidence:
222
+ records = tuple(outcome.record for outcome in outcomes if outcome.record is not None)
223
+ rejections = {outcome.record: outcome.rejection for outcome in outcomes
224
+ if outcome.record is not None and outcome.rejection is not None}
225
+ values = [outcome.result for outcome in outcomes]
226
+ if not values:
227
+ return StageEvidence(None, records, rejections)
228
+ for overall in ("FAIL", "MISSING"):
229
+ found = next((result for result in values
230
+ if result is not None and result.overall == overall), None)
231
+ if found is not None:
232
+ return StageEvidence(found, records, rejections)
233
+ if any(result is None for result in values):
234
+ return StageEvidence(None, records, rejections)
235
+ return StageEvidence(values[0], records, rejections)
@@ -13,7 +13,7 @@ import re
13
13
  from pathlib import Path
14
14
  from typing import Mapping, Sequence
15
15
 
16
- from .execution_identity import ExecutionManifest
16
+ from .execution_identity import Attempt, ExecutionManifest
17
17
  from .file_size_cap import FILE_LINE_LIMIT, FileSizeViolation
18
18
  from .json_boundary import load_owned_object
19
19
 
@@ -72,6 +72,23 @@ def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_n
72
72
  return f"-{scope}-reverify-r{round_number}-" in invocation_ref
73
73
 
74
74
 
75
+ def completed_round_attempts(
76
+ manifest: ExecutionManifest, round_number: int | None, role: str,
77
+ ) -> list[Attempt]:
78
+ """Finished `ok` attempts of `role` in correction round N (None: initial)."""
79
+ roles = {row.role_execution_ref: row.role for row in manifest.role_executions}
80
+ invocations = {
81
+ row.invocation_ref for row in manifest.invocations
82
+ if correction_round(row.dispatch_kind) == round_number
83
+ and roles.get(row.role_execution_ref) == role
84
+ }
85
+ return [
86
+ row for row in manifest.attempts
87
+ if row.invocation_ref in invocations
88
+ and row.finished_at is not None and row.status == "ok"
89
+ ]
90
+
91
+
75
92
  def validate_correction_dispatch(
76
93
  manifest: ExecutionManifest, jobs: Sequence[object],
77
94
  ) -> None:
@@ -82,19 +99,8 @@ def validate_correction_dispatch(
82
99
  verifier reads a tree the fix has not reached, as the executor/verifier batch split
83
100
  already guards for the initial round.
84
101
  """
85
- roles = {row.role_execution_ref: row.role for row in manifest.role_executions}
86
- finished_ok = {
87
- row.invocation_ref for row in manifest.attempts
88
- if row.finished_at is not None and row.status == "ok"
89
- }
90
-
91
102
  def completed(round_number: int, role: str) -> bool:
92
- return any(
93
- correction_round(row.dispatch_kind) == round_number
94
- and roles.get(row.role_execution_ref) == role
95
- and row.invocation_ref in finished_ok
96
- for row in manifest.invocations
97
- )
103
+ return bool(completed_round_attempts(manifest, round_number, role))
98
104
 
99
105
  for job in jobs:
100
106
  round_number = correction_round(getattr(job, "dispatch_kind", ""))
@@ -2506,7 +2506,7 @@ def _record_wrapper_failure(
2506
2506
  and that Lead does not need to re-record it. Nothing did: no code path
2507
2507
  anywhere called the error-log writer, so every wrapper failure vanished, and
2508
2508
  with it the `instruction-set/prior-run-errors.md` digest the next run reads
2509
- and the `/okstra-inspect errors` report. The dispatcher is the only component
2509
+ and the error report. The dispatcher is the only component
2510
2510
  that holds the exit code, so it is the one that writes.
2511
2511
 
2512
2512
  Never raises. Logging is bookkeeping around a dispatch that has already
@@ -133,6 +133,7 @@ WORKER_STATUSES = frozenset(
133
133
  NON_TERMINAL_WORKER_STATUSES = frozenset({"in-progress"})
134
134
  TERMINAL_WORKER_STATUSES = WORKER_STATUSES - NON_TERMINAL_WORKER_STATUSES
135
135
  REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
136
+ UNSUCCESSFUL_WORKER_STATUSES = TERMINAL_WORKER_STATUSES - {"completed"}
136
137
 
137
138
 
138
139
  def generate_claude_session_id() -> str: