okstra 0.231.1 → 0.232.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/README.md +12 -0
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +127 -0
  20. package/docs/architecture.md +7 -0
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  43. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  44. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  45. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  46. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  47. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  48. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  49. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  50. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  51. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  52. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  53. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  54. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  55. package/runtime/python/okstra_ctl/consumers.py +12 -9
  56. package/runtime/python/okstra_ctl/design_review.py +207 -0
  57. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  58. package/runtime/python/okstra_ctl/doctor.py +8 -25
  59. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  60. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  61. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  62. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  63. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  64. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  65. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  66. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  67. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  68. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  69. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  70. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  71. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  72. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  73. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  74. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  75. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  76. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  77. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  78. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  79. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  80. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  81. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  82. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  83. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  84. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  85. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  86. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  87. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  88. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  89. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  90. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  91. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  92. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  93. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  94. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  95. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  96. package/runtime/python/okstra_ctl/report_synthesis_packet.py +11 -2
  97. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  98. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  99. package/runtime/python/okstra_ctl/run.py +24 -1
  100. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  101. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  103. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  104. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  105. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  106. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  107. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  108. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  109. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  110. package/runtime/python/okstra_project/__init__.py +2 -0
  111. package/runtime/python/okstra_project/dirs.py +18 -0
  112. package/runtime/python/okstra_project/state.py +25 -20
  113. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  114. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  115. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  116. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  117. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  118. package/runtime/schemas/record-secret-patterns.json +41 -0
  119. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  120. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  121. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  122. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  123. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  124. package/runtime/templates/implementation-worker-preamble.md +4 -9
  125. package/runtime/templates/worker-prompt-preamble.md +4 -12
  126. package/runtime/validators/validate-run.py +14 -2
@@ -5,13 +5,17 @@ import hashlib
5
5
  import re
6
6
  from dataclasses import dataclass
7
7
  from pathlib import Path, PurePosixPath
8
+ from collections.abc import Sequence
8
9
 
9
10
  from .agent.invocation import verify_standalone_completion
10
11
  from .fixed_text import scalar
11
- from .code_review_coverage import (
12
- ReviewCensus, _HeadTree, _head_tree, _table_fields, check_review_coverage,
13
- read_review_census,
12
+ from .code_review_coverage import check_review_coverage
13
+ from .review_verdicts import (
14
+ ReviewCensus, _HeadTree, _head_tree, _table_fields, read_review_census,
14
15
  )
16
+ from .verification_input_types import FrozenReviewPolicy
17
+ from .qa_procedures import canonical_json_digest
18
+ from .review_policy import select_review_policy
15
19
 
16
20
 
17
21
  @dataclass(frozen=True)
@@ -30,21 +34,35 @@ class ReviewScope:
30
34
  )
31
35
 
32
36
 
33
- def _rule_digest(census: ReviewCensus, policies: list[Path]) -> str:
37
+ def _rule_digest(
38
+ census: ReviewCensus, policies: list[Path], policy: FrozenReviewPolicy | None = None,
39
+ resources: Sequence[str] = (),
40
+ ) -> str:
34
41
  digest = hashlib.sha256()
35
42
  values = [repr(census.rules), repr(census.references)]
43
+ if resources:
44
+ values.append(repr(tuple(resources)))
45
+ if policy is not None:
46
+ values.append(canonical_json_digest(policy))
36
47
  for reference in census.references.values():
37
48
  for location in reference.split(";"):
38
49
  name = re.sub(r":\d+(?:-\d+)?$", "", location.strip().partition("#")[0])
39
- values.append(
40
- hashlib.sha256(Path(name).expanduser().read_bytes()).hexdigest()
41
- )
42
- values.extend(hashlib.sha256(path.read_bytes()).hexdigest() for path in policies)
50
+ values.append(_policy_source_digest(Path(name).expanduser(), policy))
51
+ values.extend(_policy_source_digest(path, policy) for path in policies)
43
52
  for value in values:
44
53
  digest.update(value.encode() + b"\0")
45
54
  return digest.hexdigest()
46
55
 
47
56
 
57
+ def _policy_source_digest(path: Path, policy: FrozenReviewPolicy | None) -> str:
58
+ if policy is None:
59
+ return hashlib.sha256(path.read_bytes()).hexdigest()
60
+ source = policy["sources"].get(str(path.absolute()))
61
+ if source is None:
62
+ raise ValueError(f"review reference was not captured in the frozen policy: {path}")
63
+ return source["digest"]
64
+
65
+
48
66
  def _dependencies(body: str, census: ReviewCensus) -> dict[str, set[str]]:
49
67
  dependencies: dict[str, set[str]] = {}
50
68
  section = ""
@@ -86,13 +104,22 @@ def review_scope(
86
104
  root: Path, census_path: Path, base: str, head: str, policies: list[Path], *,
87
105
  previous_head: str = "", previous_census: Path | None = None,
88
106
  completions: list[Path] | None = None,
107
+ policy: FrozenReviewPolicy | None = None,
89
108
  ) -> ReviewScope:
90
109
  census = read_review_census(census_path)
110
+ selections = [line.removeprefix("Review resources: ")
111
+ for line in census_path.read_text(encoding="utf-8").splitlines()
112
+ if line.startswith("Review resources: ")]
113
+ if len(selections) > 1:
114
+ raise ValueError("review census repeats its resource selection")
115
+ resources = tuple(part.strip() for part in selections[0].split(";")) if selections and selections[0] != "-" else ()
116
+ if policy is not None:
117
+ select_review_policy(policy, resources=resources)
91
118
  current = _head_tree(root, head)
92
119
  base_commit = _head_tree(root, base).commit
93
120
  if current._git("merge-base", "--is-ancestor", base_commit, current.commit).returncode:
94
121
  raise ValueError("review base is not an ancestor of head")
95
- rules = _rule_digest(census, policies)
122
+ rules = _rule_digest(census, policies, policy, resources)
96
123
  baseline = (
97
124
  f"Review base: {base_commit}\nReview head: {current.commit}\n"
98
125
  f"Review rules: {rules}\n"
@@ -93,7 +93,8 @@ _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
95
  okstra code-review check-coverage --head <ref> [--base <ref>] --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
96
- okstra code-review scope --base <ref> --head <ref> --census <path> --policy <path> [--previous-head <ref> --previous-census <path> --completion <path> ...]
96
+ okstra code-review census --base <ref> --head <ref> --rules <review-rules.json> --out <artifact-path> [--policy <path> ...] [--run-manifest <path>] [--resource <pack-relative-resource> ...]
97
+ okstra code-review scope --base <ref> --head <ref> --census <path> --review-policy <shared-policy-path> [--policy <captured-path> ...] [--previous-head <ref> --previous-census <path> --completion <path> ...]
97
98
  okstra code-review check-lines --base <ref> --head <ref> --cite <path:line> [--cite ...] [--project-root <dir>]
98
99
 
99
100
  Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
@@ -107,9 +108,13 @@ instead of a checked-out tree. This is read-only — it never creates
107
108
  directories or files. `check-coverage` reads head evidence at `--head` and explicit
108
109
  base evidence at `--base`, never the working tree, prints covered cells, missing rules and unknown cells, and exits
109
110
  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.
111
+ `census` writes the range's census to `--out` and keeps IDs from
112
+ `--previous-census`. It publishes one immutable policy at <out>.policy.json,
113
+ prints its Review policy path/digest, and selects its shared catalog with the
114
+ captured architecture. --run-manifest reuses frozen implementation rules;
115
+ --policy captures additional applied standards. It exits 1 when changed
116
+ non-Python code still needs function cells added by hand. Scope reads frozen
117
+ policy bodies; legacy scope without --review-policy requires --policy files.
113
118
  """
114
119
 
115
120
 
@@ -147,10 +152,14 @@ def _build_parser() -> argparse.ArgumentParser:
147
152
  parser.add_argument("--previous-census", default="",
148
153
  help="scope, census: previous full census")
149
154
  parser.add_argument("--rules", default="",
150
- help="census: file whose ## Rules table the census copies")
155
+ help="census: canonical shared review-rules.json provenance")
151
156
  parser.add_argument("--out", default="", help="census: file to write the census to")
152
157
  parser.add_argument("--policy", action="append", default=[],
153
- help="scope: policy/calibration source to fingerprint (repeatable)")
158
+ help="census: additional policy to freeze; scope: captured policy to fingerprint")
159
+ parser.add_argument("--review-policy", default="", help="scope: shared frozen review policy")
160
+ parser.add_argument("--run-manifest", default="", help="census: reuse this run's frozen review policy")
161
+ parser.add_argument("--resource", action="append", default=[],
162
+ help="census: additional captured pack-relative rule resource")
154
163
  parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
155
164
  parser.add_argument("--project-root", default="", help="explicit project root")
156
165
  parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
@@ -385,41 +394,106 @@ def main(argv: list[str] | None = None) -> int:
385
394
  def _census(args: argparse.Namespace, project_root: Path) -> int:
386
395
  from .code_review_census import build_review_census
387
396
  from .code_review_coverage import read_review_census
397
+ from .review_policy import render_review_rule_catalog, select_review_policy
388
398
 
389
399
  if not (args.base and args.head and args.rules and args.out):
390
400
  print("census: pass --base, --head, --rules and --out", file=sys.stderr)
391
401
  return 2
392
402
  try:
403
+ if Path(args.rules).name != "review-rules.json":
404
+ raise ValueError("census requires the shared review-rules.json; add project standards with --policy")
405
+ out = Path(args.out).absolute()
406
+ policy_path, policy, digest = _census_review_policy(args, project_root, out)
407
+ changed = changed_lines(project_root, args.base, args.head)
408
+ from .review_policy import review_policy_context
409
+
410
+ paths, manifests = review_policy_context(project_root, args.head, tuple(changed), base=args.base)
411
+ selected = select_review_policy(
412
+ policy, tuple(changed), project_paths=paths, manifest_contents=manifests,
413
+ resources=args.resource,
414
+ )
393
415
  result = build_review_census(
394
416
  project_root, args.base, args.head, Path(args.rules),
395
- changed_lines(project_root, args.base, args.head),
417
+ changed, frozen_rules=render_review_rule_catalog(selected),
396
418
  previous=Path(args.previous_census) if args.previous_census else None,
397
419
  )
398
- out = Path(args.out)
399
- out.write_text(result.text, encoding="utf-8")
420
+ selection = (f"Review policy digest: {digest}\nReview resources: "
421
+ + ("; ".join(args.resource) or "-") + "\n")
422
+ out.write_text(selection + result.text, encoding="utf-8")
400
423
  read_review_census(out)
401
424
  except (OSError, ValueError, SyntaxError, StateError,
402
425
  subprocess.CalledProcessError) as exc:
403
426
  print(f"census: {exc}", file=sys.stderr)
404
427
  return 2
428
+ print(f"Review policy: {policy_path}")
429
+ print(selection, end="")
405
430
  print(result.text, end="")
406
431
  return 1 if result.unresolved else 0
407
432
 
408
433
 
434
+ def _census_review_policy(
435
+ args: argparse.Namespace, project: Path, out: Path,
436
+ ) -> tuple[Path, dict, str]:
437
+ from .qa_procedures import canonical_json_digest, load_qa_config, content_digest, safe_qa_path
438
+ from .review_policy import capture_code_review_policy, publish_review_policy, read_review_policy
439
+ from .verification_input_ref import VerificationInputReference
440
+ from .verification_inputs import read_verification_inputs
441
+ from .json_boundary import load_owned_object
442
+
443
+ destination = Path(str(out) + ".policy.json")
444
+ if not destination.is_relative_to(project.absolute() / ".okstra"):
445
+ raise ValueError("review census and policy must remain in project artifacts")
446
+ safe_qa_path(project, destination.relative_to(project.absolute()).as_posix())
447
+ extra = tuple(Path(path).expanduser().absolute() for path in args.policy)
448
+ frozen = None
449
+ if args.run_manifest:
450
+ manifest = load_owned_object(Path(args.run_manifest), artifact="run manifest")
451
+ reference = VerificationInputReference.required_from_artifact_fields(manifest)
452
+ inputs = read_verification_inputs(safe_qa_path(project, reference.relative_path), reference.digest)
453
+ if "reviewPolicy" not in inputs:
454
+ raise ValueError("the selected run has no frozen review policy")
455
+ frozen = inputs["reviewPolicy"]
456
+ if destination.exists():
457
+ policy = read_review_policy(destination)
458
+ if any(str(path) not in policy["sources"] for path in extra):
459
+ raise ValueError("additional policy is absent from the immutable review policy")
460
+ if frozen is not None:
461
+ if "authorPolicyDigest" not in policy:
462
+ raise ValueError("immutable review policy has no author policy identity; use a new census output")
463
+ if policy["authorPolicyDigest"] != canonical_json_digest(frozen):
464
+ raise ValueError("the selected run differs from the immutable review policy")
465
+ return destination, policy, content_digest(destination.read_bytes())
466
+ policy = capture_code_review_policy(project, {} if frozen is not None else load_qa_config(project),
467
+ additional_sources=extra, policy=frozen)
468
+ path, digest = publish_review_policy(project, destination, policy)
469
+ return path, policy, digest
470
+
471
+
409
472
  def _scope(args: argparse.Namespace, project_root: Path) -> int:
410
473
  from .agent.invocation import AgentInvocationError
411
474
  from .code_review_scope import review_scope
412
475
 
413
- if not (args.base and args.head and args.census and args.policy):
414
- print("scope: pass --base, --head, --census and --policy", file=sys.stderr)
476
+ if not (args.base and args.head and args.census and (args.policy or args.review_policy)):
477
+ print("scope: pass --base, --head, --census and --review-policy or --policy", file=sys.stderr)
415
478
  return 2
416
479
  try:
480
+ from .review_policy import read_review_policy
481
+ from .qa_procedures import content_digest
482
+
483
+ policy_path = Path(args.review_policy) if args.review_policy else None
484
+ if policy_path is not None:
485
+ digests = [row.removeprefix("Review policy digest: ")
486
+ for row in Path(args.census).read_text(encoding="utf-8").splitlines()
487
+ if row.startswith("Review policy digest: ")]
488
+ if digests != [content_digest(policy_path.read_bytes())]:
489
+ raise ValueError("census review policy digest is missing or differs from the shared policy")
417
490
  result = review_scope(
418
491
  project_root, Path(args.census), args.base, args.head,
419
492
  [Path(path).expanduser() for path in args.policy],
420
493
  previous_head=args.previous_head,
421
494
  previous_census=Path(args.previous_census) if args.previous_census else None,
422
495
  completions=[Path(path) for path in args.completion],
496
+ policy=read_review_policy(policy_path) if policy_path is not None else None,
423
497
  )
424
498
  except (OSError, ValueError, AgentInvocationError) as exc:
425
499
  print(f"scope: {exc}", file=sys.stderr)
@@ -141,6 +141,10 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
141
141
  status, force_reappend,
142
142
  fields.get("head_commit"),
143
143
  fields.get("source")):
144
+ if status == "done" and not fields.get("reconciled"):
145
+ from .design_review_evidence import validate_design_completion
146
+
147
+ validate_design_completion(plan_run_root, impl_task_key, stage, str(fields.get("head_commit") or ""))
144
148
  record: Dict[str, Any] = {
145
149
  "impl_task_key": impl_task_key,
146
150
  "stage": stage,
@@ -432,15 +436,14 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
432
436
  carry_path = str(cf.relative_to(task_root))
433
437
  except ValueError:
434
438
  carry_path = str(cf)
435
- append_consumer(
436
- plan_run_root,
437
- impl_task_key=impl_key,
438
- stage=stage,
439
- status="done",
440
- head_commit=head,
441
- carry_path=carry_path,
442
- source="carry-backfill",
443
- )
439
+ try:
440
+ append_consumer(
441
+ plan_run_root, impl_task_key=impl_key, stage=stage, status="done",
442
+ head_commit=head, carry_path=carry_path, source="carry-backfill",
443
+ )
444
+ except ValueError:
445
+ # expected-miss: a pending or invalid design review leaves the stage unsettled.
446
+ continue
444
447
  settled_stages.add(stage)
445
448
  recovered += 1
446
449
  return recovered
@@ -0,0 +1,207 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import re
5
+ from dataclasses import dataclass
6
+ from pathlib import Path
7
+ from collections.abc import Mapping
8
+ from typing import Any, TYPE_CHECKING, TypedDict
9
+
10
+ from .json_boundary import load_owned_object, write_owned_object_atomic
11
+ from .qa_procedures import canonical_json_digest
12
+ from .verification_input_types import FrozenReviewPolicy
13
+
14
+ if TYPE_CHECKING:
15
+ from .coverage_census import CellVerdicts
16
+ from .review_verdicts import ReviewCensus
17
+
18
+
19
+ class DesignReviewSnapshot(TypedDict):
20
+ base: str
21
+ head: str
22
+ policyDigest: str
23
+ census: str
24
+ manualInventory: dict[str, Any]
25
+ blockingSeverities: list[str]
26
+ blockingTiming: str
27
+
28
+
29
+ DESIGN_REVIEW_SCHEMA = {
30
+ "type": "object", "additionalProperties": False,
31
+ "required": list(DesignReviewSnapshot.__required_keys__),
32
+ "properties": {
33
+ "base": {"type": "string"}, "head": {"type": "string"},
34
+ "policyDigest": {"type": "string"}, "census": {"type": "string"},
35
+ "manualInventory": {"type": "object"},
36
+ "blockingSeverities": {"type": "array", "items": {"type": "string"}},
37
+ "blockingTiming": {"type": "string"},
38
+ },
39
+ }
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class DesignReviewResult:
44
+ coverage: CellVerdicts
45
+ findings: tuple[dict[str, str], ...]
46
+ blocking_findings: tuple[str, ...]
47
+
48
+ @property
49
+ def blocking(self) -> bool:
50
+ return bool(self.coverage.missing or self.coverage.unknown or self.blocking_findings)
51
+
52
+
53
+ def capture_design_review(
54
+ source: Path, base: str, head: str, policy: FrozenReviewPolicy, inventory_path: Path,
55
+ ) -> DesignReviewSnapshot:
56
+ from .code_review_census import build_review_census
57
+ from .code_review_target import changed_lines
58
+ from .review_verdicts import parse_review_census
59
+ from .review_policy import (
60
+ review_policy_catalog_path, review_policy_context, select_review_policy,
61
+ render_review_rule_catalog,
62
+ )
63
+
64
+ catalog_path = review_policy_catalog_path(policy)
65
+ catalog = json.loads(policy["sources"][str(catalog_path)]["body"])
66
+ changed = changed_lines(source, base, head)
67
+ paths, manifests = review_policy_context(source, head, tuple(changed), base=base)
68
+ selected = select_review_policy(policy, tuple(changed), project_paths=paths,
69
+ manifest_contents=manifests)
70
+ rules = render_review_rule_catalog(selected)
71
+ initial = build_review_census(source, base, head, catalog_path, changed, frozen_rules=rules)
72
+ inventory: dict[str, Any] = {}
73
+ if initial.unresolved:
74
+ inventory = _read_function_inventory(inventory_path, base, head, initial.unresolved)
75
+ result = build_review_census(source, base, head, catalog_path, changed,
76
+ frozen_rules=rules, inventory=inventory)
77
+ if result.unresolved:
78
+ raise ValueError("design review has unresolved function boundaries")
79
+ parse_review_census(result.text, allow_empty=True)
80
+ return {"base": base, "head": head, "policyDigest": canonical_json_digest(policy),
81
+ "census": result.text, "manualInventory": inventory,
82
+ "blockingSeverities": catalog["blockingSeverities"],
83
+ "blockingTiming": catalog["blockingTiming"]}
84
+
85
+
86
+ def _read_function_inventory(
87
+ path: Path, base: str, head: str, unresolved: tuple[str, ...],
88
+ ) -> dict[str, Any]:
89
+ if not path.exists():
90
+ write_owned_object_atomic(path, {"base": base, "head": head,
91
+ "files": {name: None for name in unresolved}},
92
+ artifact="function inventory")
93
+ raise ValueError(f"complete the function inventory before verifier dispatch: {path}")
94
+ payload = load_owned_object(path, artifact="function inventory")
95
+ if (set(payload) != {"base", "head", "files"} or payload["base"] != base
96
+ or payload["head"] != head or not isinstance(payload["files"], dict)
97
+ or set(payload["files"]) != set(unresolved)):
98
+ raise ValueError(f"function inventory must match this base, head and unresolved files: {path}")
99
+ return payload["files"]
100
+
101
+
102
+ def review_binding_lines(snapshot: DesignReviewSnapshot) -> tuple[str, ...]:
103
+ return (f"Review base: {snapshot['base']}", f"Review head: {snapshot['head']}",
104
+ f"Review rules: {snapshot['policyDigest']}",
105
+ f"Review census: {canonical_json_digest(snapshot)}")
106
+
107
+
108
+ def render_design_review(snapshot: DesignReviewSnapshot) -> str:
109
+ return ("\n## Frozen Design Review\n\n" + "\n".join(review_binding_lines(snapshot))
110
+ + "\n\n" + snapshot["census"]
111
+ + "\nIndependently inspect every cell and rule. Return the four binding lines verbatim, "
112
+ "one Coverage Verdicts row per cell (Cell | Checked | N/A | Findings | Evidence), "
113
+ "using only the rules assigned to that cell's Group in the Rules table. Account for "
114
+ "each assigned rule exactly once across Checked (comma-separated IDs), N/A "
115
+ "(RULE=reason) and Findings (RULE=finding-ID). Separate assignments with semicolons "
116
+ "and multiple finding IDs for one rule with commas. Use `-` for an empty field; "
117
+ "do not add rules from other groups even as N/A. Evidence starts with that cell's "
118
+ "literal target path:line, optionally backtick-quoted, followed by an optional "
119
+ "observation with a space or ` — ` separator. Do not use line ranges or replace "
120
+ "the target anchor with another file. Return the table under `## Coverage Verdicts` "
121
+ "and one `## Design Findings` section with a JSON array, including `[]` when empty. "
122
+ "Each finding has string fields id, cell, rule, kind (execution-error/design-violation), "
123
+ "severity (must-fix/should-fix/nit), timing (now/park), source (path:line), consequence, "
124
+ "fix, disposition (open/fixed/accepted-risk/rejected), basis. Give a reachable failing "
125
+ "input for an execution error or a rule violation and design impact for a design finding. "
126
+ "Every coverage finding ID must match its cell/rule in that array. Checked G2/G3/G5 "
127
+ "include `RULE=path:line observation` assignments after ` :: ` in Evidence, "
128
+ "separated with semicolons. Include observations only for checked rules; "
129
+ "N/A and Findings already explain their rules. Follow the coding-preflight "
130
+ "grading rubric; current open blocking findings force FAIL. Missing cells or rules "
131
+ "are incomplete, never clean. Other workers' results and executor self-check do not "
132
+ "satisfy your coverage. Also return exactly one `Verifier verdict: PASS|CONCERNS|FAIL` "
133
+ "line with the overall result, including command failures. Manual inventory completeness "
134
+ "remains lead judgment.\n")
135
+
136
+
137
+ def parse_design_review(
138
+ source: Path, snapshot: DesignReviewSnapshot, body: str,
139
+ ) -> DesignReviewResult:
140
+ from .review_verdicts import parse_review_census, parse_review_verdicts
141
+
142
+ for line in review_binding_lines(snapshot):
143
+ if body.splitlines().count(line) != 1:
144
+ raise ValueError("design review baseline missing or different: " + line.partition(":")[0])
145
+ census = parse_review_census(snapshot["census"], allow_empty=True)
146
+ coverage = parse_review_verdicts(source, census, [body], snapshot["head"], base=snapshot["base"])
147
+ matches = re.findall(r"^## Design Findings\s*\n```json\s*\n(.*?)\n```", body, re.M | re.S)
148
+ if len(matches) != 1:
149
+ raise ValueError("design review needs one Design Findings JSON array, including []")
150
+ findings = json.loads(matches[0])
151
+ if not isinstance(findings, list):
152
+ raise ValueError("design findings must be an array")
153
+ indexed: dict[str, dict[str, str]] = {}
154
+ for finding in findings:
155
+ _validate_finding(source, snapshot, census, finding)
156
+ if finding["id"] in indexed:
157
+ raise ValueError("duplicate design finding ID")
158
+ indexed[finding["id"]] = finding
159
+ _match_finding_rows(body, indexed)
160
+ blocking = tuple(row["id"] for row in indexed.values()
161
+ if row["severity"] in snapshot["blockingSeverities"]
162
+ and row["timing"] == snapshot["blockingTiming"]
163
+ and row["disposition"] == "open")
164
+ return DesignReviewResult(coverage, tuple(indexed.values()), blocking)
165
+
166
+
167
+ def _validate_finding(source: Path, snapshot: DesignReviewSnapshot, census: ReviewCensus,
168
+ finding: object) -> None:
169
+ from .review_verdicts import _head_tree, _source_evidence
170
+
171
+ fields = {"id", "cell", "rule", "kind", "severity", "timing", "source",
172
+ "consequence", "fix", "disposition", "basis"}
173
+ if (not isinstance(finding, dict) or set(finding) != fields
174
+ or any(not isinstance(value, str) or not value.strip() for value in finding.values())):
175
+ raise ValueError("design finding requires non-blank typed evidence and disposition fields")
176
+ cell = census.cells.get(finding["cell"])
177
+ if cell is None or finding["rule"] not in census.rules[cell.group]:
178
+ raise ValueError("design finding names an unknown cell or rule")
179
+ if (finding["kind"] not in ("execution-error", "design-violation")
180
+ or finding["severity"] not in ("must-fix", "should-fix", "nit")
181
+ or finding["timing"] not in ("now", "park")
182
+ or finding["disposition"] not in ("open", "fixed", "accepted-risk", "rejected")):
183
+ raise ValueError("design finding has an invalid grade or disposition")
184
+ tree = _head_tree(source, snapshot["head"])
185
+ tree.base = _head_tree(source, snapshot["base"])
186
+ _source_evidence(tree, cell, finding["source"])
187
+
188
+
189
+ def _match_finding_rows(body: str, findings: Mapping[str, Mapping[str, str]]) -> None:
190
+ from .review_verdicts import _keyed_values, _table_fields
191
+
192
+ section = body.partition("## Coverage Verdicts")[2].split("\n## ", 1)[0]
193
+ mentioned: set[str] = set()
194
+ for line in section.splitlines():
195
+ if not line.strip().startswith("|"):
196
+ continue
197
+ fields = _table_fields(line)
198
+ if not fields[0].startswith("C-CR-") or len(fields) != 5:
199
+ continue
200
+ for rule, ids in _keyed_values(fields[3]).items():
201
+ for identity in (value.strip() for value in ids.split(",")):
202
+ finding = findings.get(identity)
203
+ if finding is None or finding["cell"] != fields[0] or finding["rule"] != rule:
204
+ raise ValueError("coverage finding differs from Design Findings")
205
+ mentioned.add(identity)
206
+ if mentioned != findings.keys():
207
+ raise ValueError("Design Findings contains findings absent from coverage")