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,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:
@@ -103,6 +105,7 @@ class _HeadTree:
103
105
  root: Path
104
106
  commit: str
105
107
  line_counts: dict[str, int] = field(default_factory=dict)
108
+ base: _HeadTree | None = None
106
109
 
107
110
  def line_count(self, path: str) -> int:
108
111
  if path not in self.line_counts:
@@ -148,14 +151,21 @@ def _head_tree(project_root: Path, head: str) -> _HeadTree:
148
151
 
149
152
 
150
153
  def _source_evidence(tree: _HeadTree, cell: ReviewCell, evidence: str) -> str:
151
- match = re.fullmatch(r"(.+?):([1-9][0-9]*)`?(?: — .+)?", evidence.strip("`"))
154
+ source = evidence.strip("`")
155
+ if source.startswith("base:"):
156
+ if tree.base is None:
157
+ raise ValueError("base-side evidence requires --base")
158
+ tree = tree.base
159
+ source = source.removeprefix("base:")
160
+ match = re.fullmatch(r"(.+?):(0|[1-9][0-9]*)`?(?: — .+)?", source)
152
161
  target = cell.target.partition(":")[0]
153
162
  if match is None or match[1] != target:
154
163
  raise ValueError("evidence must cite the target source path:line")
155
164
  relative = PurePosixPath(target)
156
165
  if relative.is_absolute() or ".." in relative.parts:
157
166
  raise ValueError("source evidence escapes project")
158
- if int(match[2]) > tree.line_count(target):
167
+ count = tree.line_count(target)
168
+ if int(match[2]) > count or (int(match[2]) == 0 and count != 0):
159
169
  raise ValueError("source evidence line does not exist at head")
160
170
  return evidence
161
171
 
@@ -173,13 +183,13 @@ def _checked_rule_evidence(
173
183
  if observations.keys() - set(checked):
174
184
  raise ValueError("clean check evidence names an unchecked rule")
175
185
  for observation in observations.values():
176
- match = re.fullmatch(r"(`?.+?:[1-9][0-9]*`?) (.+)", observation)
186
+ match = re.fullmatch(r"(`?.+?:(?:0|[1-9][0-9]*)`?) (.+)", observation)
177
187
  if match is None:
178
188
  raise ValueError("clean check evidence needs source path:line and an observation")
179
189
  if re.fullmatch(r"(?:checked|clean|no issues?|none|n/?a)", match[2], re.I):
180
190
  raise ValueError("clean check evidence needs an observation, not a verdict label")
181
191
  citation = match[1].strip("`")
182
- source_cell = ReviewCell(citation.partition(":")[0], cell.group)
192
+ source_cell = ReviewCell(citation.removeprefix("base:").partition(":")[0], cell.group)
183
193
  _source_evidence(tree, source_cell, citation)
184
194
  return text
185
195
 
@@ -258,9 +268,12 @@ def _group_results(
258
268
 
259
269
  def check_review_coverage(
260
270
  project_root: Path, census_path: Path, completions: Sequence[Path], head: str,
271
+ *, base: str = "",
261
272
  ) -> CellVerdicts:
262
273
  census = read_review_census(census_path)
263
274
  tree = _head_tree(project_root, head)
275
+ if base:
276
+ tree.base = _head_tree(project_root, base)
264
277
  if not completions or len(set(completions)) != len(completions):
265
278
  raise ValueError("pass distinct completion paths for one reviewer")
266
279
  bodies: list[str] = []
@@ -109,9 +109,10 @@ def review_scope(
109
109
  old = read_review_census(previous_census)
110
110
  if old.rules != census.rules or old.references != census.references:
111
111
  return full("rule catalog changed")
112
- verdicts = check_review_coverage(root, previous_census, completions, prior.commit)
113
- if verdicts.missing or verdicts.unknown:
114
- return full("previous review coverage is incomplete")
112
+ verdicts = check_review_coverage(root, previous_census, completions, prior.commit,
113
+ base=base_commit)
114
+ if verdicts.unknown:
115
+ return full("previous review names unknown cells")
115
116
  try:
116
117
  dependencies = _prior_inputs(
117
118
  root, completions, old,
@@ -138,16 +139,19 @@ def _partition(
138
139
  known = set().union(*dependencies.values()) if dependencies else set()
139
140
  unknown = changed - known
140
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.
141
144
  for identity, cell in census.cells.items():
142
145
  sources = dependencies.get(identity, set())
143
146
  target = cell.target.partition(":")[0]
144
- if (not unknown and old.cells.get(identity) == cell and target in sources
147
+ if (old.cells.get(identity) == cell and target in sources
145
148
  and not changed.intersection(sources)
146
149
  and verdicts.get(identity, ("missing", ""))[0] in ("clean", "n/a")):
147
150
  carry.append(identity)
148
- reason = ("unmapped changed inputs: " + ", ".join(sorted(unknown))) if unknown else (
149
- "review changed dependencies and prior findings; attest carry boundaries"
150
- )
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"
151
155
  carry_ids = set(carry)
152
156
  return ReviewScope(
153
157
  baseline,
@@ -92,7 +92,7 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
92
92
  _CLI_EPILOG = r"""Usage:
93
93
  okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
94
94
  okstra code-review target --branch <name> --base <ref> [--date <YYYY-MM-DD>] [--project-root <dir>] --json
95
- okstra code-review check-coverage --head <ref> --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
95
+ okstra code-review check-coverage --head <ref> [--base <ref>] --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
96
96
  okstra code-review scope --base <ref> --head <ref> --census <path> --policy <path> [--previous-head <ref> --previous-census <path> --completion <path> ...]
97
97
  okstra code-review check-lines --base <ref> --head <ref> --cite <path:line> [--cite ...] [--project-root <dir>]
98
98
 
@@ -104,9 +104,12 @@ mode selects the base from the stage registry row. Both modes resolve the
104
104
  selected base to a fixed commit; branch mode requires an explicit base. An empty
105
105
  worktreePath means the review reads the branch ref
106
106
  instead of a checked-out tree. This is read-only — it never creates
107
- directories or files. `check-coverage` reads each evidence file at `--head`, not
108
- the working tree, prints covered cells, missing rules and unknown cells, and exits
107
+ directories or files. `check-coverage` reads head evidence at `--head` and explicit
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")
@@ -132,13 +138,17 @@ def _build_parser() -> argparse.ArgumentParser:
132
138
  )
133
139
  parser.add_argument(
134
140
  "--cite", action="append", default=[],
135
- help="check-lines: a finding's `path:line` (repeatable)",
141
+ help="check-lines: path:line, base:path:line or empty path:0 (repeatable)",
136
142
  )
137
143
  parser.add_argument("--census", default="", help="check-coverage: shared Rules and grouped Cells tables")
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")
@@ -185,16 +195,12 @@ def render_code_review_target_text(payload: dict) -> str:
185
195
 
186
196
 
187
197
  _HUNK_RE = re.compile(
188
- r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", re.MULTILINE,
198
+ r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@", re.MULTILINE,
189
199
  )
190
200
 
191
201
 
192
202
  def changed_lines(repo: Path, base: str, head: str) -> dict[str, set[int]]:
193
- """Head-side line numbers each file's diff touched.
194
-
195
- A deletion within a surviving file anchors on the line before the cut.
196
- A deleted file has no head-side citation.
197
- """
203
+ """Changed head anchors and explicit base-side deletion anchors."""
198
204
  options = (
199
205
  "--no-ext-diff", "--no-color", "--submodule=short", "-M",
200
206
  )
@@ -218,28 +224,49 @@ def changed_lines(repo: Path, base: str, head: str) -> dict[str, set[int]]:
218
224
  if status.startswith((b"R", b"C")):
219
225
  paths.append(os.fsdecode(next(fields)))
220
226
  selection = [f"{base}:{paths[0]}", f"{head}:{paths[1]}", "--"]
221
- if status == b"D":
222
- continue
223
227
  patch = subprocess.run(
224
228
  ["git", "-C", str(repo), "diff", "-U0", *options, *selection],
225
229
  capture_output=True, check=False,
226
230
  )
227
231
  if patch.returncode != 0:
228
232
  raise StateError(os.fsdecode(patch.stderr).strip(), stage="diff")
229
- touched = lines.setdefault(paths[-1], set())
230
- for section in os.fsdecode(patch.stdout).split("\ndiff --git "):
231
- header_lines = section.partition("\n@@ ")[0].split("\n")
232
- if "+++ /dev/null" in header_lines:
233
- continue
234
- for match in _HUNK_RE.finditer(section):
235
- start = int(match[1])
236
- count = 1 if match[2] is None else int(match[2])
237
- touched.update(
238
- range(start, start + count) if count else {max(start, 1)}
239
- )
233
+ _collect_changed_lines(lines, paths, os.fsdecode(patch.stdout))
234
+ if status == b"D":
235
+ lines.pop(paths[0], None)
236
+ source_commit, source_path = (base, paths[0]) if status == b"D" else (head, paths[-1])
237
+ size = subprocess.run(
238
+ ["git", "--literal-pathspecs", "-C", str(repo), "ls-tree", "-l", "-z",
239
+ source_commit, "--", source_path],
240
+ capture_output=True, check=False,
241
+ )
242
+ if size.returncode != 0:
243
+ raise StateError(os.fsdecode(size.stderr).strip(), stage="diff")
244
+ if size.stdout.partition(b"\t")[0].split()[-1:] == [b"0"]:
245
+ lines[f"base:{paths[0]}" if status == b"D" else paths[-1]] = {0}
240
246
  return lines
241
247
 
242
248
 
249
+ def _collect_changed_lines(
250
+ lines: dict[str, set[int]], paths: list[str], patch: str,
251
+ ) -> None:
252
+ for section in patch.split("\ndiff --git "):
253
+ header = section.partition("\n@@ ")[0].split("\n")
254
+ deleted = "+++ /dev/null" in header
255
+ if not deleted:
256
+ touched = lines.setdefault(paths[-1], set())
257
+ for match in _HUNK_RE.finditer(section):
258
+ old_start, new_start = int(match[1]), int(match[3])
259
+ old_count = 1 if match[2] is None else int(match[2])
260
+ new_count = 1 if match[4] is None else int(match[4])
261
+ if old_count:
262
+ lines.setdefault(f"base:{paths[0]}", set()).update(
263
+ range(old_start, old_start + old_count)
264
+ )
265
+ if not deleted:
266
+ touched.update(range(new_start, new_start + new_count) if new_count
267
+ else {max(new_start, 1)})
268
+
269
+
243
270
  def render_check_lines(changed: dict[str, set[int]], cites: list[str]) -> tuple[str, bool]:
244
271
  rows = ["Okstra code review citation check\n"]
245
272
  all_ok = True
@@ -298,6 +325,7 @@ def _check_coverage(args: argparse.Namespace, project_root: Path) -> int:
298
325
  result = check_review_coverage(
299
326
  project_root, Path(args.census), [Path(path) for path in args.completion],
300
327
  args.head,
328
+ base=args.base,
301
329
  )
302
330
  except (OSError, ValueError, AgentInvocationError) as exc:
303
331
  print(f"check-coverage: {exc}", file=sys.stderr)
@@ -323,6 +351,8 @@ def main(argv: list[str] | None = None) -> int:
323
351
 
324
352
  if args.command == "scope":
325
353
  return _scope(args, Path(project_root))
354
+ if args.command == "census":
355
+ return _census(args, Path(project_root))
326
356
  if args.command == "check-coverage":
327
357
  return _check_coverage(args, Path(project_root))
328
358
  if args.command == "check-lines":
@@ -352,6 +382,30 @@ def main(argv: list[str] | None = None) -> int:
352
382
  return 0
353
383
 
354
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
+
355
409
  def _scope(args: argparse.Namespace, project_root: Path) -> int:
356
410
  from .agent.invocation import AgentInvocationError
357
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")
@@ -103,6 +105,37 @@ def strip_stage_declaration_label(stage: int, value: str) -> str:
103
105
  return stripped[match.end():]
104
106
 
105
107
 
108
+ def conformance_script_matches(actual: str, declared: str) -> bool:
109
+ if actual == declared:
110
+ return True
111
+ if not actual or not declared:
112
+ return False
113
+ if actual.startswith("/") != declared.startswith("/"):
114
+ longer, shorter = (
115
+ (actual, declared) if actual.startswith("/") else (declared, actual)
116
+ )
117
+ return longer.endswith("/" + shorter)
118
+ return False
119
+
120
+
121
+ def conformance_entry_mismatches(
122
+ *, actual_script: str, declared_script: str,
123
+ actual_requires: object, declared_requires: frozenset[str],
124
+ ) -> list[str]:
125
+ errors = []
126
+ if not conformance_script_matches(actual_script, declared_script):
127
+ errors.append("script mismatch")
128
+ actual_capabilities = (
129
+ frozenset(actual_requires)
130
+ if isinstance(actual_requires, list)
131
+ and all(isinstance(value, str) for value in actual_requires)
132
+ else None
133
+ )
134
+ if actual_capabilities is None or not actual_capabilities >= declared_requires:
135
+ errors.append("requires mismatch")
136
+ return errors
137
+
138
+
106
139
  def missing_declared_scripts(entries: object, task_root: Path) -> list[str]:
107
140
  """승인 계획이 가리키는 script 파일이 task_root 아래에 없으면 오류.
108
141
 
@@ -445,6 +478,34 @@ def parse_qa_result(stdout: str) -> QaResult:
445
478
  return QaResult(overall=overall, requirements=requirements)
446
479
 
447
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
+
448
509
  @dataclass
449
510
  class ConformanceVerdict:
450
511
  stage_key: str